QTermSDK API

For a list of error codes see the faq page.

Registered Object Identifiers

These are the name used to create an instance of one of the Quickware automation objects:

QTermUTS QTermUTS.Application

ActiveUTS ActiveUTS.ActiveUTSCtrl.1

Web-UTS WebUTS.WebUTSCtrl.1

QTermT27 QTermT27.Application

ActiveT27 ActiveT27.ActiveT27Ctrl.1

Web-T27 WebT27.WebT27Ctrl.1

AccessServer AccessServer.Application

Field Types

In general, the documentation conventions are "C" based. Here is a list of equivalent Visual Basic types:

Doc "C" VB

short short Integer

string BSTR String

boolean boolean Boolean

handle handle Object handle

long long Long

long* long* ByRef Long

Note: variables passed by reference are indicated using the "C" convention of using an asterisk (*) as in long* pForeColor. Visual Basic programs understand from the type library that these variables are to be passed by reference but PowerBuilder scripts need to use the REF keyword on the call, for example: uts1.object.GetCursor(REF row, REF col).

Application Object Methods (QTerm only)

A controlling program can use these application level methods and properties to control a running instance of QTerm.

Method	Description	Return
Open(String settingsFileName)	Open a settings file. If settingsFileName is blank, the default QTerm settings file is opened.	long
Quit	Terminate QTerm	void

Application Object Events

Event	Description
OnQuit()	The application is about to terminate

Application Object Properties (QTerm only)

Property Name	Description	Type
Application	Just returns this application object (read only)	handle
Caption	Main window title text	String
FullName	Application path name (read only)	String
Height	Window height (read only)	long
Hosts	Handle to the Hosts collection (read only)	handle
Left	Left window coordinate (read only)	long
Name	Application name (read only)	String
Left	Left window coordinate (read only)	long
Parent	Just returns this application object (read only)	handle
Terminals	Handle to the Terminals collection (read only)	handle
Top	Top window coordinate (read only)	long
Visible	Main window visibility	BOOL
Width	Window width (read only)	long

Terminals Collection Properties (QTerm only)

After you get the Terminals collection handle from the Application (above), you can ask for a handle to any of the terminal screens by using the Item property, or retrieve the front terminal screen from the ActiveTerminal property.

Property Name	Description	Type
ActiveTerminal	Returns a handle to the current front terminal screen.	handle
Count	Number of terminals	long
Item(index)	Application path name (read only)	handle

Hosts Collection Properties (QTerm only)

After you get the Hosts collection handle from the Application (above), you can ask for a handle to any of the host entries by using the Item property. See Host Definition Format for details of the host definition.

Property Name	Description	Type
Add(String hostDefinition)	Add a host entry	long
Count	Number of Hosts	long
Modify(long index, String hostDefinition)	Modify the indexed host	long
Item(long index)	Returns handle to indexed host	handle
Remove(long index)	Remove the indexed host	void

Terminal Object Methods

These methods can be used from an external program controlling QTerm or from a container program with an embedded ActiveX control to direct the terminal object to many functions. For example, to connect to a host, to display data on the screen, to move about the screen and to send data to the host.

Method Name	Description	Return
AddKey(long cmd, long key, boolean shift, boolean ctl, boolean alt)	Add an entry to the current key map. If the key combination already exists it will be overwritten. The cmd values are defined in the CommandIDs section of the type library and may be viewed by an object browser. The key values are those defined by Microsoft as virtual key codes, such as VK_RETURN.	void
CaptureStart(String fileName)	Start capture screen data to fileName	long non-zero if error
CaptureStop()	Stop capture	void
ClearCapture()	Clears capture file and any captured data in memory	void
Connect(String hostName)	Connect to hostName. If the hostName parameter is just a name then the control will fire a GetHostInfo event to resolve the IP address etc. The actual result (connect confirm or connect reject) is indicated either on a subsequent GetStatus call or via an event. The hostName can be a special case of the character "+" which simulates a connection and sets the connected status. This is useful for DataStream mode (see InputData). If the hostName parameter is a string then it must provide the required host details, as a string with comma separated values (see Host Definition Format for details).	long non-zero if error
Copy()	Clipboard copy	void
CopyTable()	Clipboard copy as comma separated table data	void
Cut()	Clipboard cut	void
DeleteInDisplay()	Delete character at the current cursor position and shift data left up to end of field	void
DeleteInLine()	Delete character at the current cursor position and shift data left up to end of line	void
DeleteLine()	Delete current row	void
Disconnect()	Disconnect from host. If connected, a disconnected event will be fired when the connection is terminated.	long non-zero if error
Display(String textString)	Display textString at current cursor	void
DisplayFF()	Display a FF at current cursor position	void
DisplayLF()	Display a LF at current cursor position	void
DisplaySOE()	Display an SOE at current cursor position	void
DisplayTab()	Display an Tab at current cursor position	void
DuplicateLine()	Duplicate current row	void
EraseCharacter()	Erase character at current cursor position	void
EraseDisplay(boolean eraseCompletely)	Erase the screen from cursor position or completely if eraseCompletely is true.	void
EraseEOF()	Erase to end of field	void
EraseField()	Erase all current field	void
EraseLine()	Erase to end of line	void
EraseUnprotected()	Erase unprotected data to end of field	void
FindKey(long key, boolean shift, boolean ctl, boolean alt)	Find the specified key combination in the key map and return the corresponding command id if found.	long non-zero value of assigned command if found
FindText(String pTextString)	Searches for the specified string on the screen from the current cursor position to the end of display. The string to be searched for must be contained on one screen line and is specified by textString, a null terminated string. The search is case sensitive and, if the find is successful, the cursor is repositioned to the first character of the found string.	long non-zero if error
GetAttribute()	Get the screen attribute at current cursor	long attribute flags
GetCmdName(long cmd)	Return the command name for a specific command id	String cmdString
GetColor(long* pForeColor, long* pBackColor)	Get the foreground and background color indices at the current cursor	void
GetCursor(long* pRow, long* pCol)	Get current cursor row and column (note you can also access termRow and termColumn directly).	void
GetFieldText(long maxBytes)	Get text from screen field at current cursor . The cursor must be previously set to the required start position and then this method copies the screen data from that position up to the end of the screen field into the returned string.	String foundString
GetKey(long index, long* cmd, long* key, long* shift, long* ctl, long* alt)	Get the entry in the key map specified key by index. If index is valid, the corresponding command and key modifier information is returned. This is useful for iterating through the key map, starting at index 0 until the call returns FALSE.	Boolean TRUE if index is valid
GetKeyName(long key, boolean shift, boolean ctl, boolean alt)	Get the name of the key corresponding to the specified key code and modifier flags.	String keyName
GetRowText(long row, long startCol, long columns)	Get text from the screen row at the specified position. This function call copies the screen data from that position up to the end of the row into the returned string. For T27, if row is 1 greater than the number of screen rows data is retrieved from the status line.	String foundString
GetSelectionStartEnd(long* pStartRow, long* pStartCol, long* pEndRow, long* pEndCol, long* blockMode)	Get the start and end row and column positions of selected screen area (all zeroes if no current selection)	long
GetStatus(long* pConnected, long* pMsgArrived)	Returns the status of the host connection. pConnected has one of the following values: 0 = disconnected 1 = connecting 2 = connected 3 = disconnecting The pMsgArrived parameter is set to 1 if a new message has arrived since the last call to GetStatus	void
GetStatusFlags()	Get current status flags, defined as follows: STATUS_CONNECTED = 0x0001 STATUS_MSG_ARRIVED = 0x0002 STATUS_KEYBD_LOCKED= 0x0004 STATUS_MSG_WAITING = 0x0008 STATUS_SELECTED = 0x0010	short status flags
GetText(long startRow, long startCol, long endRow, long endCol)	Get text off the screen from the specified rows into the returned string.	String foundString
InputAttention()	Assume an attention message has been sent from the host	void
InputData(String textString)	Display textString, at the current cursor position interpreting the textString as a data stream from the host	void
InsertInDisplay()	Insert character at the current cursor position and shift data right up to end of field	void
InsertInLine()	Insert character at the current cursor position and shift data right up to end of line	void
InsertLine()	Insert new row at current cursor	void
LineSwapDown()	Swap current row with row below	void
LineSwapUp()	Swap current row with row above	void
LoadProperties(String fileName, long index)	Load the terminal properties from the settings file, for terminal number index. (ActiveX control only)	long
MoveBackspace()	Backspace the cursor	void
MoveBackTab()	Tab backwards	void
MoveDown()	Move the cursor down	void
MoveHome ()	To the home position	void
MoveLeft()	Move the cursor left	void
MoveRight()	Move the cursor right	void
MoveReturn()	Move the cursor to start of next row	void
MoveScrollUp()	Scroll the screen up one row	void
MoveTab()	Tab forwards	void
MoveTo(long row, long col)	Move the cursor to given row/column	void
MoveToEOF()	Move to end of current field	void
MoveToLineBegin()	Move to start of row	void
MoveToLineEnd()	Move to end of row data	void
MoveToUnprotected()	Move to next unprotected position	void
MoveUp()	Move the cursor up	void
NextPage()	Move cursor up	void
NextRecall()	Display next entry from command recall list	void
Paste()	Clipboard paste	void
PreviousPage()	Select previous terminal page	void
PreviousRecall()	Display previous entry from command recall list	void
PrintCancel()	Cancel print operation	void
PrintEject()	Terminate current print operation and close spool document	void
PrintFromSOE()	Print the screen up to the current cursor position	void
PrintPageSetup()	Invoke the page setup common dialog	void
PrintScreen()	Print the screen	void
PrintScreenData()	Print the screen as transparent data	void
PrintSelected()	Print the selected text	void
PrintToFile()	Cause further printing to be sent to a disk file(s)	void
PutText(long startRow, long startCol, long endRow, long endCol, String textString, boolean spacePad)	Display textString at the specified position. If the text string does not occupy all the specified area then setting the spacePad parameter to true causes the remainder to be space filled. For T27, if row is 1 greater than the number of screen rows data is displayed on the status line.	void
RemoveKey(long cmd, long key, boolean shift, boolean ctl, boolean alt)	Remove an entry from the current key map. If cmd is zero the key combination will be removed regardless of the assigned command. See AddKey for comments on the cmd and key values.	boolean TRUE if successfuly removed
ResetTerminal()	Resets the terminal including all settings properties that have been changed	void
Resize(long width, long height)	Resize control window (ActiveX only)	void
ResumeInput()	Allow host input	void
RollDown()	Roll screen down one row	void
RollUp()	Roll screen up one row	void
SaveProperties(String fileName, long index)	Save the terminal properties to the settings file, for terminal number index. (ActiveX control only)	long
SelectDown()	Extend text selection downwards	void
SelectLeft()	Extend text selection left	void
SelectRight()	Extend text selection right	void
SelectUp()	Extend text selection upwards	void
SendFKey(long keyNumber)	Send a function key to the host (UTS only)	long non-zero if error
SendMsgWait()	Send a MsgWait (break) to the host (UTS) or a Specify to the host (T27)	long non-zero if error
SendText(String pTextString)	Send a text message directly to the host. Note that the screen is not updated by this function call.	long non-zero if error
ShowGraphics()	Display graphics screen, if available	void
ShowText()	Display text screen	void
SnapScreenToCapture()	Snap the screen data to capture file, if capture open	void
StopInput()	Stop host input (use ResumeInput later)	void
TraceStart(String fileName)	Start trace. If fileName is a null string ("") then a file name is generated of the form ProductLognnn.txt.	void
TraceStop(bool viewFile)	Stop trace. If viewFile is true then a prompt to view the trace file is displayed.	void
UnlockKeyboard()	Unlock the keyboard, allowing keyboard input	void
Wait(long timeout)	Wait for the screen to be updated by the host. Returns true if updated or false if timeout expired. Note: The wait functions are mostly useful when creating scripts (eg VBscript) which cannot handle events.	boolean
WaitConnected(bool connected, long timeout)	Wait to be connected (connected = true) or disconnected (connected = false). Returns false if timeout expired.	boolean
WaitScreenText(short row, short col, String text, long timeout)	Wait for the screen at row/col to be set to text by the host. Note that setting both row and col to zero (0) requests to search the whole screen for text. Returns false if timeout expired. For T27, if row is 1 greater than the number of screen rows data is checked on the status line.	boolean
Xmit()	Simulate xmit key being pressed which initiates the sending of data from the screen to the host. The actual data transmitted depends upon the terminal type, the control page setting, the current cursor position and the start of entry position. Typically a UTS screen will be in XMIT VAR mode which means that all unprotected data between the SOE character or home position and the current cursor position is to be transmitted.	long non-zero if error

Terminal Object Events

These are all the event handling functions for events that are fired by the control. Many events do not require any action. For example, if the cursor is moved or the keyboard is unlocked and you don't care then there is no action to be taken.

Several events have a "processed" parameter which you can set to true if you completely process this event here and you do not want the control to take any further action.

Event	Description
OnAlert(long severity, String alertText, long errorNumber)	Error notification with message for display (alertText) and potential error number. severity 0 = information 1 = warning 2 = error
OnClosedCaptureFile(String captureFilename)	The capture file has been closed.
OnClosedPrintFile(String printFilename)	A print file has been closed.
OnConnected(boolean* processed)	The session status has changed to Connected. Set processed to TRUE if you don't want the control to display a screen message (eg if you have already displayed a message box).
OnConnecting()	The session status has changed to Connecting.
OnConnectRequestNotSent(long error, boolean* processed)	A connect request to a host could not be sent, the reason is provided in error. Set processed to TRUE if you don't want the control to display a screen message (e.g. if you have already displayed a message box).
OnConnectRequestRejected(long error, boolean* processed)	A connect request was rejected by the host, the reason is provided in error. Set processed to TRUE if you don't want the control to display a screen message (eg if you have already displayed a message box).
OnCursorMoved(long row, long col)	Notification that the screen cursor has moved, in order to display cursor coordinates etc.
OnCouldntSendMessage(long error, boolean* processed)	A message could not be sent to the host, the reason is provided in error, typically because the connection has been broken. Set processed to TRUE if you don't want the control to display a screen message (e.g. if you have already displayed a message box).
OnDisconnected(boolean* processed)	The session status has changed to Disconnected. Set processed to TRUE if you don't want the control to display a screen message (eg if you have already displayed a message box).
OnDisconnecting()	The session status has changed to Disconnecting.
OnDisplayedMessage(String msg, long msgLength)	A new message from the host has just been displayed.
OnFontChanged(String newFontName)	The screen font has been changed.
OnGetHostInfo(String hostName, String* pHostInfo)	The control needs the address etc of hostName, typically to resolve a connection when the user types in $$open hostName.
OnHostScriptAborted()	A host script has been aborted, typically when the host requests a script execution and a host script is already active.
OnHostScriptStart(String scriptName, boolean* processed)	The host has sent a message containing <esc><q> to trigger a script execution. Set processed to TRUE if you don't want the control to execute the script
OnKeyboardLocked()	Notification that the keyboard has been locked, in order that a visual indication may be displayed.
OnKeyboardUnlocked()	Notification that the keyboard has been unlocked, in order that a visual indication may be displayed.
OnLogMessage(long logType, String logName, String logBuffer, long logBufferLength, String logMessage)	An event has occurred that may be logged. A text message is provided in logMessage and an optional trace buffer is provided in logBuffer.
OnMessageSent(String msg, boolean* processed)	A message has been sent to the host.
OnNotConnectedCantSend(boolean* processed)	A message could not be sent because there is no current host connection. Set processed to TRUE if you don't want the control to display a screen message (e.g. if you have already displayed a message box). Set processed to TRUE if you don't want the control to display a screen message (eg if you have already displayed a message box).
OnPreAttention(boolean* processed)	An attention message is about to be sent to the host (MsgWait for UTS or Specify for T27). Set processed to TRUE if this event should not be processed.
OnPreFunctionKey(long fkey, boolean* processed)	A function key is about to be processed, fkey contains the function key number. Set processed to TRUE if this event should not be processed. (UTS only)
OnPreKeyPress(long key, boolean shift, boolean ctl, boolean alt, boolean* processed)	A key has been pressed and is about to be processed, key contains the key code. Set processed to TRUE if the keystroke should not be processed, typically because a higher level script has already processed it.
OnPreLeftMouseDoubleClick(boolean* processed)	The left mouse button has been double clicked and is about to be processed. Set processed to TRUE if this event should not be processed.
OnPreRightMouseDoubleClick(boolean* processed)	The right mouse button has been double clicked and is about to be processed. Set processed to TRUE if this event should not be processed.
OnPreSendMessage(String msg, long msgLength, boolean* processed)	A message is about to be sent to the host. Set processed to TRUE if the message should not be sent.
OnPreTransmit(boolean* processed)	The transmit function is about to be processed. Set processed to TRUE if this event should not be processed.
OnReceivedAttention(boolean* processed)	An attention (break) message has been received from the host. (UTS only). Set processed to TRUE if you don't want the control to process this attention message.
OnReceivedMessage(String msg, long msgLength, boolean* processed)	A new data message has been received from the host. Set processed to a non-zero value if the message should not be interpreted and displayed. Note that the optional status values 2 through 11 apply only to UTS terminals and that the status will only be returned to the host if it has already indicated that such status is required after a message has been processed. 1 = processed, no special status 2 = DEVICE_STATUS_NOT_CONFIGURED 3 = DEVICE_STATUS_NOT_AVAILABLE 4 = DEVICE_STATUS_NO_MEDIA 5 = DEVICE_STATUS_READY 6 = DEVICE_STATUS_INPUT_DATA_ERROR 7 = DEVICE_STATUS_OUPUT_ERROR 8 = DEVICE_STATUS_END_OF_MEDIA 9 = DEVICE_STATUS_DEVICE_DOWN 10 = DEVICE_STATUS_OUTPUT_ERROR_CLEAR 11 = DEVICE_STATUS_POC
OnRightMouseClick(boolean* processed)	Notification that a right mouse click event has occurred in order to display a popup menu. Set processed to TRUE if a popup menu should not be displayed.
OnScreenActive()	The control's terminal screen has become active.
OnScreenDeactive()	The control's terminal screen has become deactive.
OnXmitDone()	Fired after a transmit operation is complete
OnXmitWhenNotConnected(boolean* processed)	The transmit key has been pressed when not connected to a host. Typical to display a connection message or host list and then issue a Connect to the control. Set processed to TRUE if you don't want the control to display a screen message (eg if you have already displayed a message box).

Terminals Object Properties (QTerm only)

Use these QTerm application properties to retrieve a handle to a terminal etc

Property Name	Description	Type
ActiveTerminal	Returns a handle to the front terminal	handle
Count	Returns the count of terminals	long
Item(long index)	Returns a handle the requested terminal number (the first terminal is index 0)	handle

Terminal Object Properties

Use these terminal object properties to get or set various terminal settings.

Color Properties

Each color property is a value of 0 through 15, or -1 to indicate it is not enabled. The numbers 0-15 index a set of color values, as follows:

0	Black	8	Dark gray
1	Red	9	Maroon
2	Green	10	Dark green
3	Yellow	11	Olive
4	Blue	12	Dark blue
5	Magenta	13	Purple
6	Cyan	14	Teal
7	White	15	Light gray

Field Type Indices

The terminal emulators allow you to set the foreground and background colors for each type of field (unprotected, alpha only etc). When retrieving or setting a color property you need to specify the field type as an index, as detailed below:

Field Type Index		Description
COLOR_FIELD_UNPROT	0	unprotected
COLOR_FIELD_UNPROT_LOW	1	unprotected low intensity (UTS)
COLOR_FIELD_ALPHA	2	alpha
COLOR_FIELD_ALPHA_LOW	3	alpha low intensity (UTS)
COLOR_FIELD_NUM	4	numeric
COLOR_FIELD_NUM_LOW	5	numeric low intensity (UTS)
COLOR_FIELD_PROT	6	protected
COLOR_FIELD_PROT_LOW	7	protected low intensity (UTS)
COLOR_FIELD_PROTXMIT	8	protected transmittable (T27)
COLOR_FIELD_SECURE	9	secure
COLOR_FIELD_SECURE_LOW	10	secure low intensity (UTS)
COLOR_FIELD_RIGHT	11	right justified
COLOR_FIELD_RIGHT_LOW	12	right justified low intensity (UTS)
COLOR_FIELD_REVERSE	13	reverse video
COLOR_FIELD_REVERSE_LOW	14	reverse video low intensity (UTS)
COLOR_FIELD_FLASH	15	flashing
COLOR_FIELD_FLASH_LOW	16	flashing low intensity (UTS)
COLOR_FIELD_STATUSLINE	17	status line (T27)

General Terminal Properties

These properties apply to all terminal types.

Property Name	Description	Type
termAutoFont	Auto sizing font mode 0 = not auto font 1 = auto font 2 = auto width 3 = auto height	short
termBackColor(long index)	Set the background color for the field type specified by index	short
termColumn	Current screen column	short
termColumns	Number of screen columns	short
termFontName	Font name	String
termFontSize	Font point size	short
termForeColor(long index)	Set the foreground color for the field type specified by index
termLastHost	Last host accessed (read only)	String
termName	Terminal name	String
termNetworkChar	Set the network control character as used on caommands to open and close connections (default is '$', as in $$OPEN and $$CLOSE)	short
termPages	Number of screen pages	short
termRow	Current screen row	short
termRows	Number of screen rows	short
termTermType	Terminal type: UTS: 0 = UTS20 1 = UTS40 4 = UTS60 T27: 0 = TD830ascii 1 = TD830 (ebcdic) 2 = TD830ndl (ebcdic + ndl)	short

T27 Specific Terminal Properties

These properties apply only to the T27 terminal type.

Property Name	Description	Type
termAltRS	Alternate RS character	short
termAltUS	Alternate US character	short
termEom	EOM character	short
termFixedTabPosition(long index)	Fixed tab positions. The index specifies one of 10 possible tabs (0 - 9). The column position of the tab is the property value.	short
termVariableTabPosition(long index)	Variable tab positions. The index specifies one of 10 possible tabs (0 - 9). The column position of the tab is the property value.	short

Terminal Options