The 7.0 version of QTerm brings a new look and easily accessible function panels which
can be permanently displayed (pinned) or can be automatically hidden and only displayed when
moused over. Mutiple frame windows are also supported with one or more terminal windows in each frame. This allows you
to easily take advantage of multiple monitors.
If you are interested in trying out the new version please click here to download the software
Click New to close.
This SDK tells you how to easily construct host access solutions, using either the QTerm application or our ActiveX controls, tailored to your specific requirements.
Quickware markets several host access products, including the QTerm terminal emulators and the ActiveTerminal controls. ActiveTerminal is the family name for ActiveX controls that support mainframe access. Currently Quickware provides ActiveUTS and ActiveT27, to connect to Unisys 2200 and A-Series mainframes respectively.
Both of these product families support COM compliant interfaces, for which the exposed properties and methods are basically the same; therefore both are described in this same document. The ActiveX controls and QTerm (since 5.3) have the ability to fire events.
This document describes the automation interfaces that allow user programs to interact with a host application using the standard OLE/COM mechanisms of Properties, Methods and Events.
The term Automation refers to the usage in the context of OLE/COM by which one program controls another through a defined interface. The interface is defined in terms of exposed properties and methods. In this manner the automation is uni-directional (the controlling program controls the controlled program) but each invoked method may request information to be returned, thereby supporting two way passage of information although it is governed by the controlling program.
Automation involves the methods and properties exposed by an application, which therefore provides services to the calling program as an "out of process server" since it is running as an executable program with its own thread. This is subtly different to similar methods provided by an ActiveX control because ActiveX controls are, in all reality, DLLs and therefore run in-process.
You can automate your host access using the standard COM interfaces to QTerm. There are two clear requirements for such automation and probably as many as you care to think of. Two frequent scenarios are:
Front ending QTerm with your application; here you can have QTerm invisible in the background responding to your calls upon the various methods. You will tell QTerm to connect to a host, send a message, screen scrape the host replies, display this information in your program and so on. All the user sees is your GUI program.
Using QTerm as an adjunct to your application; here you would have QTerm visible and operational. The user would be entering data at a QTerm screen as normal. Your application may or may not be visible to the user and it would monitor the session data, perhaps triggering filling in of lengthy product details, thereby assisting the user in form filling operations. Or, fetching data from a completely different source and displaying advice to the user.
Document Object Model
QTerm embodies a Document Object Model, on the lines of the application/document object model recommended by Microsoft. The hierarchy starts with an Application object, followed by a Terminals collection object and then by the individual Terminal object. A table below details all the properties and methods of the Application object and the Terminals object.
What does this mean to you? Well, taking VB as the sample environment, the first thing you need to do is to get the application object so, naturally enough, you use:
Note the syntax here, omitting the first parameter tells VB that you want to get a currently registered object (from the Running Object Table) and not to create a new one. In the VTermTest sample you can see that, if this fails, we create a new application object:
After you have the handle to the application object it's plain sailing. You either know the terminal you want to use or you can get the active terminal (the front terminal).
Now you have the handle to a current terminal object you can use all the methods and properties pertaining to terminal and printer, as listed in the accompanying tables, for example:
Sample VB code to display Hello World on a terminal screen
Sub Form_Load() dim QTermApp As Object dim qterm As Object ' First try to get an already running object On Error Resume Next Set QTermApp = GetObject(, "QTermUTS.Application") ' check we got the object ok If Err.Number = 429 Then ' Create a new object Err.Clear Set QTermApp = CreateObject("QTermUTS.Application") If Err.Number <> 0 Then MsgBox "Failed to create object" Exit Sub End If End If ' tell app to open config if 0 terminals If (QTermApp.Terminals.count = 0) Then QTermApp.Open End If
' get front terminal and display hello Set qterm = QTermApp.Terminals.ActiveTerminal qterm.display "hello world" End Sub
A good example of dealing with timing issues is a Timer Control in Visual Basic. Such a control is invisible at run time, can be enabled or disabled under program control and gains control at intervals determined initially by definition and thereafter by program control.
The timer control can be programmed to call the GetStatus method at regular intervals, to determine if an event has occurred on an open connection. The advantage of this technique is that the activity is like a background watchdog. In the foreground all other controls are active and responsive. The program is very much alive and responsive to the user but, as soon as a message arrives from the host application, the program responds and processes the message - by displaying text, highlighting buttons, posting an alert or whatever response has been designed.
If the response to a GetStatus call results in an indication that a message has arrived, the user program will typically issue a GetFieldText or GetRowText to retrieve the data.
This is a Visual Basic program that provides a test interface for QTerm automation. Select either QTermUTS or QTermT27 from the combo box and then click on the GetQTerm button. This will issue a GetObject to obtain a dispatch handle to a running QTerm, or will first start QTerm if necessary.
This is a Visual Basic program that provides a test interface for QTerm automation, about as simple as it gets!
A visual basic program that demonstrates capturing of events fired from QTermUTS or QTermT27.
ActiveUTS and ActiveT27 are ActiveX controls (in-proc servers) and can therefore be used within any container that supports hosting of such controls, such as a Visual Basic program. Typical usage falls into one of two arenas, as an invisible transport provider for host connections or as a visible "terminal" screen on the container's window.
A typical scenario would be where you develop a GUI program tailored to your host transactions and need the control to provide the host transport, presentation protocol and data stream interpretation. What this means is that a hidden screen is used to "display" all the host messages and your messages to be sent to the host. Your program can then use all the screen scraping methods provided in order to conduct a conversation with the host. In this case you will probably make most use of the exposed properties and methods to control the session because all user interaction would be with your program and not directly with the control's screen (being invisible).
Here you would design a Visual Basic, PowerBuilder, or whatever, application and make space available on your main window to show the control. In this case the user interacts with the screen via mouse and keyboard as with the full QTerm emulator. You can add buttons and list boxes etc. to your program and use them to drive the exposed properties and methods of the control to augment the user interaction.
A very important facet of automation is the ability to fire events. As you will see below, many events are defined and you may wonder if you have to respond to all of them. The answer is - as many as you need to. For example many events indicate the state of the connection and the screen, so you can display the current connection status and the row/column position or enable/disable UI elements. If you're not bothered about displaying this type of information, simply ignore those events.
Since the principal function of the ActiveTerminal controls is to connect to a host let's take a look at how sessions are connected. There are 3 main methods for a user to request a connection:
As the control issues the connect request to the host the connection status changes and the control may fire the following events to the container:
After a session has been successfully established the host may disconnect the session at any time or the user may close the session (with $$CLOSE) and the following events may be fired:
There are two basic ways you can programmatically send text to the host. You can display text on the screen and perform a transmit operation or you can simply send a string to the host, bypassing the screen.
Sending Special Sequences
Both the UTS and T27 protocols allow for sending special (non-data) sequences to the host, for example UTS function keys or the T27 Specify.
There are various ways you can receive data from the host. Bear in mind that is the the terminal object that is actually receiving and interpreting the data so what you want to know is when a message has been received. You can poll the object at regular intervals and use the various methods to retrieve data from the screen buffer, or you can be event driven if using the components within your own program.
Once you know that a message has arrived and been displayed on the screen you can use any of the available "text returning" methods to retrieve the data:
From within your program you can simulate anything that a human user could do, such as moving the cursor,. typing characters, tabbing, erasing data, printing etc. Here are a few of the useful methods to do this (see API documentation for a complete list):
The TraceStart and TraceStop methods provide a very powerful tracing feature by which you can capture all logged events and connection messages. Using TraceStart with a file name and all this data is written to the specified file. Or, if you don't specify a file name, you can receive the trace messages in your own program via the OnLogMessage event and possibly display them in real time.
Sample Visual Basic programs are included to demonstrate the use of the COM interfaces. Note that the ActiveTerminal controls do not own any menus or toolbars, the container programs provide these.
This is a Visual Basic program that provides a test interface for an ActiveUTS component. It displays the ActiveUTS component in a fixed size window and contains many menu items to invoke methods of the component. A list box displays each event fired by the ActiveUTS component. The Logon buttons demonstrate 2 methods of programming a dialog with the host (sending messages and waiting for messages).
This is a Visual Basic program that hosts one instance of the ActiveUTS component to create a simple terminal emulator. It shows how to add menu items, toolbar functions and a live status bar to control the component and respond to fired events.
This is a Visual Basic program that hosts one instance of the ActiveUTS component and one instance of MSChart. Select figures by dragging with the mouse and see the graph change dynamically.
double click on thumbnail for larger view and then use the browser back button to return here
This is a Visual Basic program that provides a test interface for an ActiveT27 component. It displays the ActiveT27 component in a fixed size window and contains many menu items to invoke methods of the component. A list box displays each event fired by the ActiveT27 component.
This is a Visual Basic program that hosts one instance of the ActiveT27 component to create a simple terminal emulator. It shows how to add menu items, toolbar functions and a live status bar to control the component and respond to fired events.
For programming details please see API documentation.