Reflection Desktop VBA Guide
Key Concepts / Using the Reflection Object Model
In This Topic
    Using the Reflection Object Model
    In This Topic

    To develop solutions that use the Reflection VBA, you'll need to interact with the objects provided by the Reflection object model. This topic introduces the most important objects:

    Application Object

    Terminal and Web Control Objects

    Frame and View Objects

    Legacy Project Objects

    Application Object

    Conceptually, the Application object represents the Reflection application. It is the top root object from which you can get various parts of the object model. The Application object is not visible within a project (that is, it doesn't appear in the Project Explorer pane in Visual Basic for Applications).

    In Reflection macros, you'll need to access this top level object to programmatically create sessions, find out how many sessions are running, or access other running sessions.  

    Getting a handle to Reflection
    Copy Code
    Dim app As Attachmate_Reflection_Objects_Framework.ApplicationObject
    Set app = GetObject("Reflection Workspace")
    


    From another application, you can use an existing instance of Reflection if it is running or open an instance if it is not:

    Creating a new instance of Reflection
    Copy Code
    Dim app As Attachmate_Reflection_Objects_Framework.ApplicationObject
    On Error Resume Next
    'Try to use the existing workspace
    Set app = GetObject("Reflection Workspace")
    
    On Error GoTo 0
    'Otherwise, create new instance of Reflection
    If IsEmpty(app) Or (app Is Nothing) Then
    Set app = New Attachmate_Reflection_Objects_Framework.ApplicationObject
    End If
    

    Terminal, Screen, and Web Control Objects

    To work with host sessions, you use Terminal and Screen objects. Together with their child objects, the Terminal and Screen objects make up all of the functionality within a host session. For Reflection Web sessions, you'll use the WebControl object to access the session objects.

    If you are writing a Reflection macro in a session project folder, you can use the ThisIbmTerminal property to get the terminal for the existing session:
    Using the ThisIbmTerminal property
    Copy Code
    ThisIbmTerminal.HostAddress = "demo:ibm3270.sim"
    ThisIbmTerminal.Port = "623"
    


    If you are writing a macro in another application like Microsoft Excel or you're writing a Reflection macro and you want to create a new session, you'll need to create a terminal. You can do this by creating a new terminal session or by opening a session document file.

    Creating or opening an IBM terminal
    Copy Code
    Dim terminalA As Attachmate_Reflection_Objects_Emulation_IbmHosts.IbmTerminal
    Dim terminalB As Attachmate_Reflection_Objects_Emulation_IbmHosts.IbmTerminal
    Dim terminalC As Attachmate_Reflection_Objects_Emulation_IbmHosts.IbmTerminal
    
    'Create an Ibm3270 control and set the host address
    Set terminalA = app.CreateControl2("{09E5A1B4-0BA6-4546-A27D-FE4762B7ACE1}")
    terminalA.HostAddress = "demo:ibm3270.sim"
    terminalA.Port = "623"
      
    'For a 5250 ibmterminal control, use the following Guid:
    Set terminalB = app.CreateControl2("{AF03A446-F278-4624-B9EF-C896DF2CA1CA}" )
     
    'Open a session document file to create a terminal control for the new session
    Set terminalC = app.CreateControl(Environ$("USERPROFILE")
    "\Documents\OpenText\Reflection\" "mySavedSession.rd3x")
    

    The IBM Terminal Object is the parent of the following objects:

      Let's take a look at some of the key objects.

    The IbmScreen object

     The Screen object represents the host application screen. It provides methods and properties to access host screen data.

    'Print the screen text at column 1 and row 1, with a length of 30 characters
    Debug.Print ThisIbmTerminal.screen.GetText(1, 1, 30)
    

    The FileTransfer object

     The FileTransfer object provides properties for configuring host file transfer and methods for executing a file transfer to or from the host.

    Transferring a file
    Copy Code
    'This sample sends a file to the host. Before you run the sample, make sure the cursor is on a TSO command line.
    Sub FileTransferSendSample()
     
        path = Environ$("USERPROFILE") & "\Documents\OpenText\Reflection\" & "test.txt"
      
        'Set the  3270 operating environment to TSO
        ThisIbmTerminal.FileTransfer.XfrHostSys = HostSystem_Tso
      
        ThisIbmTerminal.FileTransfer.INDSendFile path, "bvtst02.test7.txt", INDFileTransferType_Ascii, _  FileExistsOption_Overwrite, True
      
    End Sub
    

    The Productivity object

    Use the Productivity object to get access  to objects like screen history.

    Getting access to Screen History with the Productivity object
    Copy Code
    ThisIbmTerminal.Productivity.ScreenHistory.CaptureScreen
    
                   

    The Theme object

    The Theme object represents a visual theme in the application. You can load custom themes or change properties of the current theme.

    Loading a theme
    Copy Code
    Sub loadTheme()
        'Load a custom theme
        customTheme = Environ$("USERPROFILE") _
        & "\Documents\OpenText\Reflection\Themes\customTheme.themex"
       
        ThisIbmTerminal.Theme.Load (customTheme)
    End Sub
    

    If you are writing a Reflection macro in a session project folder, you can use the ThisTerminal property to get the terminal for the existing session:

    'Create a Telnet connection and set the host name to connect to
    ThisTerminal.ConnectionSettingsTelnet.HostAddress = "yourHostName"
    


    If you are writing a macro in another application like Microsoft Excel or you're writing a Reflection macro and you want to create a new session, you'll need to create a terminal. You can do this by creating a new terminal session or by opening a session document file.

    Creating or opening a new Open Systems terminal
    Copy Code
    Dim terminalA As Attachmate_Reflection_Objects_Emulation_OpenSystems.Terminal
    Dim terminalB As Attachmate_Reflection_Objects_Emulation_OpenSystems.Terminal
    'Create a terminal control
    Set terminalA = app.CreateControl2("{BE835A80-CAB2-40d2-AFC0-6848E486BF58}")
      
    'Create a telnet connection and set the host name to connect to
    terminalA.ConnectionSettingsTelnet.HostAddress = "yourHostName"
    
    'Create a terminal control by opening a session document file
    Set terminalB = app.CreateControl(Environ$("USERPROFILE") & _
    "\Documents\OpenText\Reflection\" & "testFile.rdox")
    

    The Open Systems Terminal object is the parent of the following objects:

     Let's take a look at some of the key objects.

                   

    The ConnectionSettings objects

    The terminal object has a number of connection settings objects that support different types of connections, including: Telnet, SSH, Rlogin, serial port, and best network. You'll need to use one of these objects to set the host address and other connection properties.

    Setting ConnectionSettings
    Copy Code
    'Create a telnet connection and set the host name to connect to
    terminal.ConnectionSettingsTelnet.HostAddress = "yourHostName"
    
                   

    The Screen object

     The Screen object represents the host application screen. It provides methods and properties to access host screen data.

    Accessing screen data
    Copy Code
    Sub PrintScreen()
        'Print the screen display to the Immediate window
       
        Dim cols As Integer
        Dim rows As Integer
       
        cols = ThisScreen.DisplayColumns
        rows = ThisScreen.DisplayRows
       
        Debug.Print ThisScreen.GetText2(1, 1, cols, rows)
    End Sub
    
                                  

    The Productivity object

    Use the Productivity object to get access  to features like screen history.

    ThisTerminal.Productivity.ScreenHistory.CaptureScreen
    
                   

    The Theme object

    The Theme object represents a visual theme in the application. You can load custom themes or change properties of the current theme.

    Loading a theme
    Copy Code
    'Load a custom theme
    customTheme = Environ$("USERPROFILE") _
    & "\Documents\OpenText\Reflection\Themes\customTheme.themex"
                           
    ThisTerminal.Theme.Load (customTheme)
    
                                   

    Each Web session includes a WebControl object, a WebDocument object, and one or more WebElement objects. (From WebDocuments, you can get WebElements; from those WebElements, you can get child WebElements.)

    Let's take a look at these objects.

    WebControl

    The WebControl contains the controls required to display a Web page in the Reflection Workspace.

    Getting a handle to a Web control
    Copy Code
    Dim app As Attachmate_Reflection_Objects_Framework.ApplicationObject
    webCtrl As WebControl
       
    'Get a handle to the existing application object (the workspace) and create a Web control
    Set app = GetObject("Reflection Workspace")
    Set webCtrl = app.CreateControl2("{F1F058B1-0472-4095-A782-3D7333813AD0}")
    

    WebDocument

    The WebDocument object provides access to the IE Web document and the methods and properties used to get Web elements and control the document.

    Use the Web Control to get the Web document. Make sure it is ready before you assign it.

    Getting a Web document
    Copy Code
    Dim wDocument As WebDocument
    Dim wElement As WebElement
    
    'Wait until the Web page is ready and then set it as the Web document
    Do Until webCtrl.ReadyState = WebBrowserReadyState_Complete
      Wait (1000)
    Loop
    Set wDocument = webCtrl.Document
    

    WebElement

    Use the WebElement object to get the HTML elements you'll need to interact with JavaScript. 

    Finding a Web element
    Copy Code
    Dim wElementArray() As WebElement
    
    'Iterate through all the links to find the link with the "Add Data" text and then click the link
    wElementArray() = wDocument.GetElementsByTagName("a")
    For i = 0 To UBound(wElementArray)
      If InStr(wElementArray(i).InnerHtml, "Add Data") = 1 Then
        wElementArray(i).Click
        Exit For
      End If
    Next i
    


    If you're writing a macro in a Web document VBA project, you can use the ThisWebControl property to access the Web objects:

    'Get the Web element with the "coolTable" ID 
    ThisWebControl.Document.GetElementById ("coolTable")
    

    Frame and View Objects

    Two high level objects are required to display Reflection sessions:

    To display a session, you'll need to get the Frame object, Create a View object, and associate the Terminal object with the View object. 

    Displaying a session
    Copy Code
    Dim Frame As Attachmate_Reflection_Objects.Frame
     Dim view As Attachmate_Reflection_Objects.view
     'Create controls to open and display the session document.
     Set Frame = app.GetObject("Frame")
     'Make Frame visible to display the workspace
     Frame.Visible = True
     'Create a view for the terminal to display the session
     Set view = frame.CreateView(terminal)
    


    You can also access the Frame object with the ThisFrame property. If you're programming in a Reflection project module, you can use the ThisView property to access the view for the session.

    Getting the Frame and View objects in a project module
    Copy Code
    ThisFrame.Visible=True  
    ThisView.ActiveTabBackgroundColor = RGB(0, 0, 0)
    ThisView.ActiveTabForegroundColor = RGB(255, 255, 255)
    ThisView.InactiveTabBackgroundColor = RGB(20, 200, 250)
    


    You can use Frame object methods to access views and terminal controls of other open sessions.  

    To identify a particular View object, you can specify it by title, ID, or file path. For example, to write a macro that acts on one of three open session documents, you can get a View object by using the text that appears on the session's tab or by using the path to where its session file is saved. After you have the View object, you can use it to get the terminal control object for that session.

    Getting a View and a Terminal control
    Copy Code
    Sub CheckViews()
        Dim osTerminal As Attachmate_Reflection_Objects_Emulation_OpenSystems.Terminal
        Dim ibmTerminal As Attachmate_Reflection_Objects_Emulation_IbmHosts.ibmTerminal
        Dim webCntrl As Attachmate_Reflection_Objects.WebControl
             
        Dim sessionName As String
        Dim views() As Attachmate_Reflection_Objects.View
        Dim osView As Attachmate_Reflection_Objects.View
                             
        'Catch error if sessions are not open
        On Error GoTo MyHandler
                             
        'Get the view and terminal control from the session path and filename
        sessionName = Environ$("USERPROFILE") & "\Documents\OpenText\Reflection\" & "GetDataFromExcel.rd3x"
        views = ThisFrame.GetViewsByFilePath(sessionName)
        Set ibmTerminal = views(0).control
                             
        'Get the view and terminal control from the title text on the view's tab
        sessionName = "osSession.rdox"
        Set osView = ThisFrame.GetViewByTitleText(sessionName)
        Set osTerminal = osView.control
        
        Exit Sub
                             
        'If a session is not open, send a message to open it and then exit
        MyHandler:
           MsgBox "You need to open" & sessionName
        Exit Sub
    
    End Sub 
    
                   

    Legacy Project Objects

    For each legacy document, Reflection creates an additional VBA project for the supported legacy API. This legacy API VBA project includes objects that provide backward compatibility for legacy macros. (You can view the legacy API VBA project in the Project Explorer window of the Visual Basic Editor.) To determine which legacy API is supported, see Using Extra! and Legacy Reflection Macros.

    See Also