QTermSDK

API documentation    

Description

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. 

QTerm Automation

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.

Automation Usage

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:

QTermApp = GetObject(, "QTermUTS.Application")
or
QTermApp = GetObject(, "QTermT27.Application")

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:

QTermApp = CreateObject("QTermUTS.Application")
or
QTermApp = CreateObject("QTermT27.Application")

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

qterm = QTermApp.Terminals.Item(2)
or
qterm = QTermApp.ActiveTerminal

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:

qterm.EraseDisplay(true)
qterm.optFlashingCursor = true
qterm.termName = "TERMXX"
qterm.Connect(demand)

 

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

Background Timer

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.

VTermTest

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.

VHello

This is a Visual Basic program that provides a test interface for QTerm automation, about as simple as it gets!

.

VTermEvents

A visual basic program that demonstrates capturing of events fired from QTermUTS or QTermT27.

ActiveTerminal

Usage

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.

Invisible Transport

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

Visible Terminal

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. 

Events

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. 

Session Management

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:

1. The container application can present any UI component (typically a button) on the window by which the user can request a connection. The container could then call the Connect method:
   
   ' set terminal name and type
   ActiveX.TermName = "Term1"
   ActiveX.termType = 0
   
   ' form host string (eg Host,HostApp,1.2.3.4,102)
   Dim hostInfo As String
   hostInfo = "HostName" & "," & hostApp & "," & IPadr & "," & PortNum
   
   ' issue connect
   Dim reply As Integer
   reply = ActiveX.Connect(hostInfo)
   
   You can then wait for the connect type events.  The OnConnected event signals a successful connection.
   
2. Press XMIT. This will fire an OnXmitWhenNotConnected event. This simply tells the container what happened. A typical response would be for the container to display a list of hosts for the user to choose from. Or the container could immediately call the Connect method, if only one host was available.
3. Enter $$OPEN HostName. The control will parse this input and fire an OnGetHostInfo event to retrieve the IP address, TCP port etc from the container. It then uses this information to proceed with the 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:

1. OnConnecting
2. OnConnected
3. OnConnectRequestNotSent
4. OnConnectRequestRejected

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:

1. OnDisconnecting
2. OnDisconnected

Sending Text

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.

Send String
ActiveX.SendText ("text to be sent directly to the host")

Display and transmit
ActiveX.Display ("text to be displayed on the screen")
ActiveX.Xmit

Note: in this case the text is displayed at the current screen location what is transmitted to the host depends upon the current screen mode and screen content, just as if you had displayed the text and manually pressed the transmit button.

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.

UTS: Send Function Key or MsgWait
ActiveUTS.SendFKey(1)
ActiveUTS.SendMsgWait

T27: Send Specify
ActiveX.SendMsgWait

Receiving data

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.

Polling the Object

Private Sub GetText_Click()
    ' this is how you would get text if polling the object, first check if a new
    ' message has arrived from the host and been displayed on the screen
    Dim flags As Integer
    flags = ActiveX.GetStatusFlags
    If (flags And STATUS_MSG_ARRIVED) Then
        ' pick up five characters from the current cursor position
        Dim count As Long
        fieldText = ActiveX.GetText(row1, col1, row2, col2)
    End If
End Sub

Event Driven

Private Sub ActiveX_OnDisplayedMessage(ByVal msg As String, ByVal msgLength As Long)
   ' Here you know that a message has been received and displayed
   ' so you can pick up data from screen (only you know what data 
   ' you are expecting and whereabouts on the screen it will be).
   ' The raw message data is provided on this callback but is usually 
   ' uninteresting since you really want the screen data.
   dim fieldText as String
   fieldText = ActiveX.GetText(row1, col1, row2, col2)
End Sub

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:

Screen Manipulation

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

Tracing

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 Programs

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.

• VActvUTS, a VB container program for ActiveUTS
• VTermUTS, a VB simple terminal emulator using ActiveUTS
• VTermChart, a VB graphing example using ActiveUTS
• VActvT27, a VB container program for ActiveT27
• VTermT27, a VB simple terminal emulator using ActiveT27

VActvUTS

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

VTermUTS

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.

VTermChart

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

VActvT27

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.

VTermT27

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.

Programming Details

For programming details please see API documentation.

`