hostexplorer programmer's guideftp.iitm.ac.in/.../documentation/hostexplorerprogramming.pdfii...

HostExplorer®Programmer’s Guide

ii

HostExplorer Programmer’s GuideVersion 10.0Published in Canada — July 31, 2004

Hummingbird Ltd. — Corporate Headquarters1 Sparks Avenue • Toronto, Ontario • M2H 2W1 • CanadaToll Free Canada/U.S.A. +1 877 FLY HUMM (359 4866)Tel +1 416 496 2200 • Fax +1 416 496 2207 • E-mail [email protected]

For more information, visit www.hummingbird.com

RESTRICTED RIGHTS LEGEND Unpublished rights reserved under the copyright laws of the United States. The SOFTWARE is provided with restricted rights. Use, duplications, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of The Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, subparagraph (c) (1) and (2) (a) (15) of the Commercial Computer Software-Restricted Rights clause at 48 CFR 52.227-19, as applicable, similar clauses in the FAR and NASA FAR Supplement, any successor or similar regulation.

Information in this document is subject to change without notice and does not represent a commitment on the part of Hummingbird Ltd. Not all copyrights pertain to all products.

Copyright © 2004, Hummingbird Ltd. All rights reserved. Trademarks and logos are the intellectual property of Hummingbird Ltd.

Connectivity Kerberos, Connectivity Secure Shell, Connectivity SecureTerm, Connectivity SSL, Exceed, Exceed 3D, Exceed Connectivity Suite, Exceed onDemand, Exceed onDemand Client, Exceed onDemand Deployment Wizard, Exceed onDemand Server, Exceed onDemand Server Manager, Exceed PowerSuite, Exceed XDK, HostExplorer, HostExplorer Connectivity Suite, Host Access Services, HostExplorer Print Services, HostExplorer Web, Hummingbird Basic, Hummingbird Certificate Manager, Hummingbird Connectivity, Hummingbird Connectivity Suite, Hummingbird Core Services, Hummingbird Deployment Packager, Hummingbird Deployment Wizard, Hummingbird e-Gateway, Hummingbird FTP, Hummingbird InetD, Hummingbird Enterprise 2004, Hummingbird Proxy Server, Hummingbird SOCKS Client, NFS Maestro, NFS Maestro Client, NFS Maestro Gateway, NFS Maestro Server, NFS Maestro Solo, NFS Maestro Tuner, TXP, TXPM, and Xweb are trademarks of Hummingbird Ltd. and/or its subsidiaries.

All other copyrights, trademarks, and tradenames are the property of their respective owners.

ACKNOWLEDGEMENTS Portions of the code have been contributed by MIT. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.OpenSSL.org/).

DISCLAIMER Hummingbird Ltd. software and documentation has been tested and reviewed. Nevertheless, Hummingbird Ltd. makes no warranty or representation, either express or implied, with respect to the software and documentation included. In no event will Hummingbird Ltd. be liable for direct, indirect, special, incidental, or consequential damages resulting from any defect in the software or documentation included with these products. In particular, Hummingbird Ltd. shall have no liability for any programs or data used with these products, including the cost of recovering such programs or data.

mailto:[email protected]://www.hummingbird.com/

Related Documentation and Services

ManualsAll manuals are available in print and PDF. The PDF versions require Adobe Acrobat Reader and are installed only if you perform a Complete installation, or if you select them during a custom installation. Your Hummingbird product comes with the following manuals:

HelpThe online Help is a comprehensive, context-sensitive collection of information regarding your Hummingbird product. It contains conceptual and reference information, and detailed, step-by-step procedures to assist you in completing your tasks.

To view Help on any Windows NT 4.0 operating system, you must ensure that Internet Explorer v4.01 or later and the HTML Help viewer files are installed on your computer. The HTML Help viewer files are distributed in Hhupd.exe. If you have administrator privileges, Hummingbird Setup Wizard will install Hhupd.exe automatically if necessary.

Release NotesThe release notes for each product contain descriptions of the new features and details on release-time issues. They

are available in both print and HTML. The HTML version can be installed with the software. Read the release notes before installing your product.

HostExplorer User’s Guide Provides information on how to access corporate mainframe data through HostExplorer terminal emulation components, as well as how to automate and configure host sessions.

HostExplorer Programmer’s Guide (PDF format only)

Provides programmers with information on how to customize HostExplorer, FTP, and WyseTerm through Visual Basic and Visual C++ scripts using HostExplorer APIs.

Hummingbird Basic Language Programmer’s Guide

Provides procedural and reference information, tips, and suggestions for working with Hummingbird Basic Language using Hummingbird Basic Workbench and Dialog Editor.

iii

Hummingbird Exposé Online

Hummingbird Exposé Online is an electronic mailing list and online newsletter. It was created to facilitate the delivery of Hummingbird product-related information. It also provides tips, help, and interaction with Hummingbird users. To subscribe/unsubscribe, browse to the following web address:

http://www.hummingbird.com/expose/about.html

User Groups and Mailing ListsThe user group is an unmoderated, electronic mailing list that facilitates discussion of product-related issues to help users resolve common problems and to provide tips, help, and contact with other users.

To join a user group:

Send an e-mail to [email protected]. Leave the Subject line blank. In the body of the e-mail message, type the following:

subscribe hostexplorer-users Your Name

To unsubscribe:

Send an e-mail to [email protected]. Leave the Subject line blank. In the body of the e-mail message, type the following:

unsubscribe hostexplorer-users Your Name

To post a messages to the user group:

Send your e-mail to:

[email protected]

To search the mailing list archives:

Go to the following web site:

http://www.hummingbird.com/support/usergroups.html

iv

mailto:[email protected]://www.hummingbird.com/expose/about.htmlmailto:[email protected]:[email protected]://www.hummingbird.com/support/usergroups.html

Contents

Chapter 1: Introducing HostExplorer Programming 1

Introducing HostExplorer Programming ................................................................ 2

Chapter 2: Customizing HostExplorer 3

Introducing HostExplorer APIs ................................................................................ 4

OLE Support .............................................................................................................. 8OLE Automation ........................................................................................ 8OLE Objects ............................................................................................... 9Methods and Properties of the Application Object ................................. 10Methods and Properties of the Hosts Object ........................................... 20Methods and Properties of the Host Object ............................................ 24Methods and Properties of the Area Object ............................................. 77Methods and Properties of the Field Object ............................................ 91Methods and Properties of the Cfg3270, Cfg5250, and CfgVT Objects 100Unsupported OLE Methods and Properties .......................................... 169Differences Between Hummingbird Basic and WinWrap Basic ............ 170

File Transfer Options ............................................................................................. 189File Transfer Options ............................................................................. 189General Options ..................................................................................... 189CMS-Specific Options on Upload ......................................................... 190TSO-Specific Options on Upload .......................................................... 190MUSIC-Specific Options on Upload ..................................................... 191

Special Sequences ................................................................................................... 1923270/5250 Special Sequences ................................................................. 192VT Special Sequences ............................................................................. 194

About the Terminal Objects .................................................................................. 196Methods of the Terminal Objects .......................................................... 196Properties of the Terminal Objects ........................................................ 200

v

HostExplorer Programmer’s Guide

About COM Objects .............................................................................................. 208Relationship Between COM Objects ...................................................... 209Unsupported COM Methods and Properties ........................................ 209Renamed or Moved COM Methods, Properties, and Interfaces ........... 211

About the Profile Object ........................................................................................ 264Profile Interface ...................................................................................... 264ProfileTerminal Interface ....................................................................... 345ProfileGraphics Interface ....................................................................... 408ProfileKeyboard Interface ...................................................................... 420ProfileMouse Interface ........................................................................... 447ProfileToolbar Interface ......................................................................... 451ProfileTrackMenu Interface ................................................................... 467ProfileTranslationTable Interface .......................................................... 472ProfileVTCharset Interface .................................................................... 474ProfileEdit Interface ............................................................................... 483ProfileColor Interface ............................................................................ 551ProfileFileTransfer Interface .................................................................. 553ProfileCursor Interface .......................................................................... 652ProfileFonts Interface ............................................................................. 660ProfilePCPrint Interface ........................................................................ 665ProfilePrintScreen Interface ................................................................... 674ProfileSecurity Interface ........................................................................ 707ProfileDisplay Interface ......................................................................... 720ProfilePrintSession Interface ................................................................. 755ProfileCapture Interface ........................................................................ 770ProfileHostPrinting Interface ................................................................ 781ProfileHotspots Interface ....................................................................... 820ProfileEvents Interface ........................................................................... 829ProfileConnection Interface ................................................................... 834ProfileSessionWindow Interface ............................................................ 913ProfileSound Interface ........................................................................... 946Data Types of the Profile Object ............................................................ 950

About the Parser Objects ....................................................................................... 951Methods of the Parser Objects ............................................................... 957Properties of the Parser Objects ........................................................... 1062Data Types of the Parser Objects ......................................................... 1177

vi


About the Transport Objects .............................................................................. 1178Methods of the Transport Objects ....................................................... 1181Properties of the Transport Objects ..................................................... 1205Data Types of the Transport Objects ................................................... 1284

About OHIO ........................................................................................................ 1285OhioManager Interface ........................................................................ 1285OhioSessions Interface ......................................................................... 1291OhioSession Interface .......................................................................... 1295OhioScreen Interface ........................................................................... 1304OhioOIA Interface ............................................................................... 1326OhioFields Interface ............................................................................. 1334OhioField Interface .............................................................................. 1340OhioPosition Interface ......................................................................... 1355Data Types of OHIO ............................................................................ 1359

About Legacy APIs ............................................................................................... 1366EHLLAPI and WinHLLAPI DLL Support ............................................ 1366Special EHLLAPI and WinHLLAPI Flags ............................................ 1368

EHLLAPI Support ................................................................................................ 1369EHLLAPI Module ................................................................................ 1369Irma Compatibility Mode .................................................................... 1369EHLLAPI Calls ..................................................................................... 1369Visual Basic Interface ........................................................................... 1385EHLLAPI Support in VT and NVT Modes .......................................... 1390EHLLAPI Development Files ............................................................... 1391NVT Mode Functions .......................................................................... 1391NVT Mode Exceptions ......................................................................... 1392Configuration Tips ............................................................................... 1393

WinHLLAPI Module ........................................................................................... 1394WinHLLAPI Development Files .......................................................... 1394

Dynamic Data Exchange (DDE) ......................................................................... 1395What is DDE? ....................................................................................... 1395How Does DDE Work? ........................................................................ 1395DDE Terminology ................................................................................ 1404DDE Sample Code ................................................................................ 1406System Topic ........................................................................................ 1407

vii


Chapter 3: Customizing FTP 1410

Introducing FTP API ........................................................................................... 1411

Sample Client Source Code ................................................................................. 1412

Customizing FTP ................................................................................................. 1412Initialization and Termination Functions ........................................... 1412

Directory Functions ............................................................................................. 1413Connection and Access Functions ....................................................... 1415File Transfer Functions ........................................................................ 1417Deleting and Renaming Functions ...................................................... 1419Tree Functions ..................................................................................... 1420Transfer Type Settings ......................................................................... 1422Local File Creation Settings ................................................................. 1424Remote Command Functions .............................................................. 1426FTP Session Settings ............................................................................. 1428Miscellaneous FTP Command Functions and Settings ....................... 1431Error Handling Function ..................................................................... 1434

Customizing FTP OLE ........................................................................................ 1434Introducing FTP OLE API ................................................................... 1434Creating an OLE Script ........................................................................ 1435IHclFtpEngine Object .......................................................................... 1436IHclFtpSession Object .......................................................................... 1437IHclFtpSessions Object ........................................................................ 1439

Chapter 4: Customizing WyseTerm 1441

User-Defined Types ............................................................................................. 1473

Introducing WyseTerm API ................................................................................ 1474

Configuring Telnet Using DDE .......................................................................... 1475Conversing with Telnet using DDE ..................................................... 1475Request and Execute Syntax ................................................................. 1475DDE Topics Available in Telnet ........................................................... 1476System Topic Request Items (HTelnet|System) ................................... 1477Terminal Topic Items (HTelnet|Terminal) ......................................... 1478Emulation Type Topic Items (HTelnet|EmulationType) .................... 1485Page Topic Items (HTelnet|Page) ........................................................ 1492

viii


Configuring Telnet Using OLE ........................................................................... 1498Automating Telnet using OLE ............................................................. 1498Starting Telnet in Hummingbird Basic Using OLE ............................. 1498Property and Method Syntax ............................................................... 1499Available OLE Objects in Telnet .......................................................... 1500WyseTerm Object ................................................................................. 1501Emulation Object ................................................................................. 1508Page Object .......................................................................................... 1523Title Object .......................................................................................... 1529

Appendix: General Accessibility and Technical Support 1531

General Accessibility ............................................................................................ 1532Microsoft Accessibility Options ........................................................... 1533

Technical Support ................................................................................................ 1534

Index 1535

ix

Chapter 1

Introducing HostExplorerProgramming


2

Introducing HostExplorer Programming

HostExplorer products provide a wide range of application programming interfaces (APIs), a document standard used to program applications. These APIs let you exploit the functionality and features of HostExplorer products from within your own programs and scripts.

Rather than creating your own code to redesign applications, you can use the available HostExplorer APIs. These APIs let you extend the functionality of your available programming languages (for example, Visual C++ and Visual Basic) to write scripts. With HostExplorer programming you can:

• Use OLE Automation APIs to add File Transfer capabilities to your own application.

• Use a small amount of Visual Basic script to embed an HETerminal screen within a web page, as well as add HTML user interface features for absolute control over how the terminal is used.

• Use Visual Basic or C++ scripts to provide a new front end to an existing application, and use the Parser or Terminal objects to communicate back to the modified application.

• Automate terminal display panels to improve their appearance and usability.

• Automate repetitive tasks (for example, checking data) which improves the reliability of data.

You can customize the following HostExplorer programs using the corresponding application programming interfaces (APIs) and available scripts.

• HostExplorer

• FTP

• WyseTerm

For information on creating, compiling, and debugging scripts using Hummingbird Basic Language, see the Hummingbird Basic Workbench help. Hummingbird Basic Workbench is an application that is available with the Hummingbird Accessories product. If you want to view the help file, install Hummingbird Basic Workbench, if you have not done so already.

Chapter 2

Customizing HostExplorer


Introducing HostExplorer APIs

As part of the latest business trend, companies are rethinking how to access valuable information from the mainframe. Programmers need to create applications that make better use of host information. They need application programming interfaces (APIs) to allow for PC-to-host or UNIX-to-host communication.

HostExplorer provides a wide range of APIs that let you automate and use HostExplorer functionality from within your own programs and scripts.

With programming languages such as C++ and Basic, you can use the methods and properties within these APIs to customize HostExplorer to suit your needs or those of your customers. For example, you can use these APIs to:

• redesign a graphical user interface (GUI) in an application

• incorporate an application into a Web page

• create interactive Web sites

HostExplorer APIs are based on the following popular standards:

• OLE (Object Linking and Embedding) automation

• COM (Component Object Model)

• OHIO (Open Host Interface Objects)

OLE AutomationOLE Automation is a Windows tool that lets you automate the exchange of data between applications, and lets you access and control HostExplorer.

For more information, see OLE Automation.

4


HostExplorer COM ObjectsCOM objects provide methods and properties that let you manipulate the behavior of objects and create relationships between objects. These objects offer the most efficient means of accessing an application’s features and functionality, and they can be used by any COM-compliant application. You can use a COM object to make a direct call, and the system returns a pointer to that interface.

HostExplorer provides the following COM objects, which allow you to seamlessly integrate HostExplorer functionality within your own applications:

• Terminal objects

• Profile object

• Parser objects

• Transport objects

A functional diagram illustrates how objects work together to access host data from the mainframe.

The most common libraries are:

• HostExplorer 3270 Type Library

• HostExplorer 5250 Type Library

• HostExplorer VT Type Library

• HESession 1.0 Type Library

Note: Methods and properties for TN3270 and TN5250 terminal types do not apply to Hummingbird Connectivity SecureTerm.

Note: The three Terminal objects (3270, 5250, and VT) are ActiveX objects that let you embed the HostExplorer terminal into your own applications.

5


In Visual Basic, you can add the visual controls (for example, 3270, 5250, and VT type libraries) to the project by clicking Component on the Project menu. You can add objects such as HESession and HEOhio by clicking References on the Project menu. When you add the objects, they become available in a drop-down menu. Using this drop-down menu, you can select objects in Dim statements, as well as other Visual Basic statements.

When you are using the visual controls and you add the basic object, this object is displayed on the component bar. When you add the selected control to a form in the project, Visual Basic automatically creates the object. In the following example, Visual Basic automatically creates the Session and Transport objects. Visual Basic automatically creates other objects after you connect to the session, therefore, you must assign references to these objects. In the following example, the active control is named My3270 in the project. This control is an instance of the HE3270Terminal object that you added as a visual component to the project:

Example:

Dim MySession As HESessionDim MyTransport As Object…Set MySession = My3270.SessionSet MyTransport = My3270.Transport

OHIOOHIO is a developing standard; it addresses the need for a standardized programming interface to host data. HostExplorer provides Ohio interfaces, which contain methods and properties that you can use to access different types of host data.

The Ohio object consists of classes, such as OhioManager and OhioSession, as described in the draft IETF standard.

In Visual Basic, you typically declare objects in one of the following formats:

• Dim OManager As HEOHIOLib.OhioManager

• Dim OSession As OhioSession

6


After you add the HEOhio 1.0 Type Library, the most common library for Ohio, to the project references list, either of the two formats will work. OhioManager, OhioSession, and HEOHIOLib appear in the drop-down menu that is displayed when you type the Visual Basic “AS” keyword.

Legacy APIsIn addition to COM objects and OHIO, HostExplorer provides the following existing (or “legacy”) APIs:

• EHLLAPI (Extended HLLAPI) and WinHLLAPI (Windows HLLAPI)—Allow other Windows programs (for example, Attachmate® Extra! for Windows) to communicate and control HostExplorer terminal emulators.

• DDE (Dynamic Data Exchange)—A tool that allows programs (for example, Microsoft Excel, Word, and Visual Basic) to communicate with the HostExplorer 3270 emulator.

While these APIs are less efficient and use larger and more rigid objects than COM and OHIO, you can still use them to write applications and thus avoid rewriting your own code. HostExplorer’s support of these earlier APIs helps maximize an organization’s investment in its development.

Note: In Ohio, you must create the object as follows:

Set OManager=CreateObject("HEOhio.OhioManager")

7


OLE Support

OLE Automation3270 5250 VT

OLE Automation is a facility provided by Windows that lets you exchange data between applications. You can use OLE Automation to automate these tasks.

You can also use OLE Automation to access and control HostExplorer. You can write OLE Automation clients using a variety of tools, including Hummingbird Basic, Visual Basic, C++, and other languages.

The name of the Automation object is "HostExplorer."

The following example uses Visual Basic:

Dim HE as ObjectSet HE = CreateObject( "HostExplorer" )

Now, use the language extensions as you would in the built-in macro editor:

HE.CurrentHost.Keys "Login JOHN@E"…

If you need to add OLE objects to a project during development, add the hostex32.exe file as a reference. Visual Basic then adds the objects, properties, and methods to your project. You can view the objects using the Object Browser.

Some sample macros are provided in the EB directory located in the main HostExplorer program folder.

OLE Automation Reference3270 5250 VT

OLE Automation is a facility provided by Windows that lets you exchange data between applications. You can use OLE Automation to automate these tasks.

8


You can access and control HostExplorer through OLE Automation. You can use OLE Automation clients to write and use a variety of tools including Hummingbird Basic, Visual Basic, C++ and more. HostExplorer provides a number of OLE Automation Objects that you can use to develop scripts to control HostExplorer and its operations. You can view OLE Automation Objects as methods and properties.

OLE Objects3270 5250 VT

HostExplorer provides methods and properties for the following OLE objects:

• Application

• Hosts

• Host

• Area

• Field

• Cfg3270, Cfg5250, and CfgVT

A method is a construct that, when executed, performs an action and possibly returns a value. For example, you can use the Keys method to simulate pressing keys in HostExplorer. This method returns the value of the return code, indicating whether you pressed the keys successfully. A method can optionally take parameters.

A property is an interface to a variable in HostExplorer. Unlike a method, it does not perform an action or take any parameters. You can use a property to retrieve or set the value of its associated variable in HostExplorer. For example, you can use the AllowUpdates host property to get or set the value of the Screen Updates flag, which determines whether the program updates the screen. Properties that you can retrieve, but not alter, are called read-only properties.

9


The following diagram illustrates the relationship between the OLE objects.

Methods and Properties of the Application ObjectThe methods and properties of the Application object let you manipulate various aspects of a HostExplorer session.

The following Application object methods and properties are available.

• CurrentHost

• GetCurrentDir

• GetProfileString

• HostFromProfile

• NewSession

• Word

• ExitAll

• GetFilePath

• Hosts Collection

• HostFromShortName

• StartSession

• WriteProfileString

10


CurrentHostProperty, Application Object 3270 5250 VT

The CurrentHost property is a pointer to the current host object, which is the session with the last focus. If there is only one session, this object represents a pointer to that session.

Note: Because this object represents the session that last had the focus, the value of CurrentHost may change throughout your program when you start new sessions. To prevent this, use the Host object by assigning a static reference to the current session. For example:

Dim Host as ObjectSet Host = HE.CurrentHost… Now use Host.* object …

Syntax CurrentHost

Example Sub MainDim HE as ObjectDim Host as Object

Set HE = CreateObject( "HostExplorer" )Set Host = HE.CurrentHost

Host.PrintScreen

End Sub

11


ExitAllMethod, Application Object 3270 5250 VT

You can use this method to immediately terminate and close all active sessions. Make this method the last call to HostExplorer because it automatically unloads the emulator.

GetCurrentDirMethod, Application Object 3270 5250 VT

The GetCurrentDir method returns the current working directory.

Syntax ExitAll

Example Sub MainDim HE as ObjectSet HE = CreateObject( "HostExplorer" )…HE.ExitAll

End Sub

Syntax szDir$ = GetCurrentDir

where szDir$ is the current working directory.

Example Sub MainDim HE as ObjectSet HE = CreateObject( "HostExplorer" )

Path$ = HE.GetCurrentDirPrint Path$

End Sub

12


GetFilePathMethod, Application Object 3270 5250 VT

The GetFilePath method displays a dialog box that prompts you for a file path. The returned string is a complete path and file name. If you click the Cancel button, the system returns a null string.

GetProfileStringMethod, Application Object 3270 5250 VT

You can use the GetProfileString method to retrieve a value from any .ini file.

Syntax szPath$ = GetFilePath ( szDefName$, szDefExt$, szDefDir$, szTitle$, iOption% )

where:

• szPath$—The path string returned from the dialog box if the user pressed OK.

Selecting a different directory changes the current directory of the application.

• szDefName$—Used to set the initial file name. If you omit this by specifying an empty string (" "), *.szDefExt$ is used.

• szDefExt$—Used to initially show files whose extension matches this string value. You can specify multiple extensions by using a comma (,) as the separator. If you omit this by specifying an empty string (" "), * is used.

• szDefDir$—Used to set the initial directory. If you omit this by specifying an empty string (" "), the system uses the current directory.

• szTitle$—Used to set the title of the dialog box. If you omit this by specifying an empty string (" "), "Open" is used.

• iOption%—The numeric value that determines the file selection options. If you omit this, the system uses a zero.The available options are: 0—Only allow the user to select a file that exists, 1—Confirm creation when the user selects a file that does not exist, 2—Allow the user to select any file whether it exists or not, 3—Confirm overwrite when the user selects a file that exists


Print HE.GetFilePath( "Hostex32.exe", "EXE", "Program Files", "Get FilePath",0)

End Sub

13


The szSection$ parameter is the section name. This parameter must always be present. The szKey$ parameter is the key name. You can pass an empty string as this parameter to read all the keys in the section. The system separates all keys by newline characters. The szINIFileName$ parameter is the file name. If you omit a path, the system looks for the file in the Windows directory.

HostFromProfileMethod, Application Object 3270 5250 VT

The HostFromProfile method is a pointer to the host object that was started from the specified session profile.

Syntax szValue$ = GetProfileString( szSection$, szKey$, szINIFileName$ )

where:

• szSection$—The section of the file (the name in square brackets).

• szKey$—The key to read.

• szINIFileName$—The name of the .ini file to read.

• szValue$—The string value read from the .ini file.


szBeep$ = HE.GetProfileString( "Windows", "Beep", "c:\winnt\win.ini" )MsgBox "The content of that key is: " & szBeep$, , "Output"

End Sub

Syntax Set Host = HostFromProfile( strProfile$ )

where strProfile$ is the name of the session profile.


Set HE = CreateObject( "HostExplorer" )Set Host = HE.HostFromProfile( "c:\winnt\Profiles\AllUsers\ _Application Data\Hummingbird\Connectivity\10.00\Profile\ _MyProfile.hep" )

End Sub

14


HostFromShortNameMethod, Application Object 3270 5250 VT

The HostFromShortName method is a pointer to the host object that contains the specified session short name.

Hosts CollectionObject, Application Object 3270 5250 VT

The Hosts Collection object accesses available sessions by their unique session ID.

Refer to the Next property for an example of the suggested way to enumerate all of the current host objects.

Syntax Set Host = HostFromShortName( strShortName$ )

Parameters strShortName$—The name of the session short name.


Set HE = CreateObject( "HostExplorer" )Set Host = HE.HostFromShortName("A")

End Sub

Note: Hosts(n) may or may not be set to “Nothing”, even if the number of hosts is greater than n, since each successive session’s unique ID is incremented by 1 and has nothing to do with whether or not sessions close.

Syntax Set Host = Hosts( UniqueSessID% ) Hosts.Count

where UniqueSessID% is the unique ID for the session.

15


NewSessionMethod, Application Object 3270 5250 VT

You can use the NewSession method to create a new session control block within HostExplorer. Use this method if you want to create a new session from scratch without using a previously saved profile. The NewSession method returns a value representing the unique session ID of the new session. The first available session has a session ID of 0.

The default terminal type is 3270. To change the default, add the following line to the HEOleAut.Settings section in the global hostex.ini file, located in the HostExplorer directory where the user files are stored on your machine. For the appropriate directory path for your platform, refer to the list of the default locations for the user files. For more information, see“Default Locations for User Files” on page 1409.

[HEOleAut.Settings]New Session Terminal Type = x

Example Sub MainDim HE as ObjectDim Host3270 as ObjectDim Host5250 as ObjectSet HE = CreateObject( "HostExplorer" )

SessID3270 = HE.StartSession( "VMCMS.3270" )SessID5250 = HE.StartSession( "INT.5250" )

Set Host3270 = HE.Hosts( SessID3270 )Set Host5250 = HE.Hosts( SessID5250 )

End Sub

Note: HostExplorer continues to support this method. However, the Open method to create a new session, but you can also use it to specify a session profile or terminal type. If there are any programs or macros that used the NewSession method in version 6.x, you must review (and possibly modify) them for versions 7.x and 8.x.

16


where x is one of the following values:

• 1—TERMINAL_3270

• 2—TERMINAL_TELNET

• 4—TERMINAL_5250

StartSessionMethod, Application Object 3270 5250 VT

You can use the StartSession method to start a new session from a profile saved on disk. This method takes one parameter that is the name of the profile. You can specify the ProfileName in one of two ways:

• Specify a complete directory path to the MyProfile.hep file in the Profile\3270 directory where the user files are stored on your machine. For the appropriate directory path for your platform, refer to the list of

Syntax UniqueSessID% = NewSession

where UniqueSessID% is the ID of the session started.

Example '$Include:"-E\hebasic.ebh"

Sub MainDim Host as ObjectDim HE as ObjectDim Cfg as ObjectSet HE = CreateObject( "HostExplorer" )

UniqueSessID% = HE.NewSessionSet Host = HE.Hosts(UniqueSessID%)Set Cfg = Host.CfgHost.Model =TELNET_VT220' Set terminal model nextHost.ConnectBy = IO_TELNET' Set transport next

Cfg.Host = "myhost.mydomain"Cfg.ConnectTimeout = 30Cfg.TCPPort = 23

Host.ConnectEnd Sub

17


the default locations for the user files. For more information, see “Default Locations for User Files” on page 1409.

• Specify the older format if the profile is in a first-level folder "MyProfile.MyFolder".

The value UniqueSessID% returned is the session ID for the host session created. You can use this session ID to access the Host object directly.

Note: HostExplorer continues to support this method. However, the Open method to create a new session, but you can also use it to specify a session profile or terminal type. If there are any programs or macros that used the StartSession method in version 6.x, you must review (and possibly modify) them for versions 7.x and 8.x.

Syntax UniqueSessID% = StartSession( szProfileName$ )

szProfileName$—The name of the profile to load and connect.

UniqueSessID%—The ID of the session started.

Example Sub MainDim HE as ObjectDim Host as ObjectSet HE = CreateObject( "HostExplorer" )

UniqueSessID% = HE.StartSession( "VMCMS.3270" )

Set Host = HE.Hosts( UniqueSessID% )End Sub

18


WordMethod, Application Object 3270 5250 VT

You can use the Word method to parse out the nth word of a string. The first parameter is the string that you want to parse. The second parameter contains a string of valid delimiters to parse the words. The third parameter is the index of the word to retrieve. Unlike other methods, the first word of a string has an index of 1.

WriteProfileStringMethod, Application Object 3270 5250 VT

You can use the WriteProfileString method to write an INI key value to a file. The szSection$ parameter is the section name and is mandatory. The szKey$ parameter is the key name. If you pass an empty string as the szKey$ and szValue$ parameters, the entire section is deleted. The szValue$

Syntax szWord$ = Word( szString$, szParse$, index% )

where:

• szString$—The string to parse.

• szParse$—The string of delimiters to parse szString$.

• index%—The index of the word to parse out.

• szWord$—The word parsed by the method.


szWord$ = HE.Word("I have a lazy brown dog", " ", 2 )MsgBox "The second word in the string is " & "'" & szWord$ & "'"

End Sub

19


parameter is the value for the key. If you pass an empty string as the szValue$, then the key is deleted from the section. The szINIFileName$ parameter is the file name. If you omit a path, the system looks for the file in the Windows directory.

Methods and Properties of the Hosts ObjectThe Hosts object consists of a collection of hosts. You can use the object to cycle through the sessions and perform actions. The following Hosts object methods and properties are available:

• CloseAll

• Count

• Item

• Next

• Open

Syntax WriteProfileString szSection$, szKey$, szValue$, szINIFileName$

where:

• szSection$—The section of the file (the name is in square brackets).

• szKey$—The key to write.

• szINIFileName$—The name of the .ini file to write.


HE.WriteProfileString "Windows", "Beep", "No", "c:\winnt\win.ini"End Sub

Note: These methods and properties are valid for all terminal types (that is, TN3270, TN5250, and TNVT).

20


CloseAllMethod, Hosts Object 3270 5250 VT

You can use this method to immediately terminate and close all active sessions. Make this method the last call to HostExplorer because it automatically unloads the emulator.

CountProperty, Hosts Object 3270 5250 VT

This property returns the total number of sessions available.

ItemProperty, Hosts Object 3270 5250 VT

This property returns the pointer to the session (n) where n is a unique session ID.

Syntax Hosts.CloseAll


…HE.Hosts.CloseAll

End Sub

Syntax count% = Hosts.Count


…count% = HE.Hosts.Count

End Sub

Syntax Set Host = Hosts.Item (ID%)

where ID% is the ID of the session.

21


NextProperty, Hosts Object 3270 5250 VT

This property returns the next session after the specified session. If you specify "Null", it returns the first session.

OpenMethod, Hosts Object 3270 5250 VT

You can use the Open method to start a new session from a profile saved on disk or to create a new session from scratch without using a previously saved profile. This method takes one parameter that is the name of the profile. You can specify the ProfileName in one of two ways:

• Specify a complete directory path to the MyProfile.hep file in the Profile\3270 directory where the user files are stored on your machine.


…Set Host = HE.Hosts(0)

End Sub

Syntax Set Host = Hosts.Next (HostX)

where HostX is the specified host.


Set Host = Nothing ' Prepares 'Next’ method to get the first host

for i = 1 to HE.Hosts.CountSet Host = HE.Hosts.Next(Host)MsgBox "The current short name is: " + Host.ShortName

next i

End Sub

22


For the appropriate directory path for your platform, refer to the list of the default locations for the user files. For more information, see “Default Locations for User Files” on page 1409.

• Specify the older format if the profile is in a first level folder "MyProfile.MyFolder".

Syntax Set Host = Hosts.Open( szProfileName$ )

Set Host = Hosts.Open (TERMINAL_TELNET)

where szProfileName$ is the name of the profile to load and connect.

Example The following example involves opening an existing profile:

Sub MainDim HE as ObjectDim Host as ObjectSet HE = CreateObject( "HostExplorer" )

Set Host = HE.Hosts.Open( szProfileName$ )

End Sub

The following example involves opening a new profile:

'$Include: "-E\hebasic.ebh"

Sub MainDim HE as ObjectDim MyHost as Object

Set HE = CreateObject( "HostExplorer" )

'Default connection method – IO_TELNETSet MyHost = HE.Hosts.Open( TERMINAL_3270 )

MyHost.Cfg.Host = "MyHost.MyDomain"

'Set MyHost = HE.Hosts.Open( TERMINAL_3270, IO_MSSNA) 'Connect with MSSNA'MyHost.Cfg.LUName = "MYLUNAME"

MyHost.Cfg.ConnectTimeout = 30MyHost.Connect

End Sub

23


Methods and Properties of the Host ObjectThe Host object methods and properties let you configure and manipulate all aspects of a screen. You can access a host screen in two ways. You can use the CurrentHost object, which always refers to the screen that has or last had the focus, or the Hosts(n) object where n is a value from 1 to Hosts.Count (the total number of available sessions). The latter is the method used to access the n'th session available. If you are writing scripts that simply access one session, use of the CurrentHost object is the recommended method. You can access host methods directly using the With statement, or by creating an object for easy reference.

The following Host object methods and properties are available:

• Host Activate • OIAUpdated

• AllowClose • Pause

• AllowUpdates • PrintScreen

• BFPress • ProtectedText

• BFStatus • PSReserved

• Bytes • PSUpdated

• Capture • PutText

• CaptureOIA • QueryCloseRequest

• Close • QuickKeyFile

• Columns • ReceiveFile

• Connect • Restore

• ConnectBy • Row

• ConnectErrorStatus • Rows

• ConnectRC • RunCmd

• Cursor • RunQuickKey

• CursorRC • SaveScreen

• Device3279 • SaveScrollback

• Disconnect • Search

24


• EAB • SendFile

• FieldID • SetFont

• FontLarger • ShortName

• FontSmaller • Show

• GetIOBuffer • ShowToolbar

• Hide • SilentConnect

• HideToolbar • SystemColor

• HighlightText • TerminalMode

• Hosts Collection • Text

• Index • TextRC

• InsertMode • TN3270

• IsConnected • TrackMenu

• IsXfer • Update

• Keyboard • WaitConnected

• Keys • WaitForIO

• LoadQuickKeyFile • WaitForString

• LoadSlideShowFile • WaitForStringRC

• Maximize • WaitIdle

• Minimize • WaitPSUpdated

• Model • WaitXfer

• MouseToCursor • XferCount

• OIA • XferRC

• SaveQuickKeyFile

25


Host ActivateMethod, Host Object 3270 5250 VT

You can use this method to activate the host object. This brings the host object to focus by making the screen window the top-level window on the desktop.

AllowCloseProperty, Host Object 3270 5250 VT

You can use this property to allow or prevent the user from closing the current session. To allow the user to close the session, set the AllowClose property to TRUE. To prevent the user from closing the session, set the property to FALSE.

Syntax Activate


' Bring this window to the topHE.CurrentHost.Activate

End Sub

Syntax AllowClose = TRUE/FALSE


bAllowClose = HE.CurrentHost.AllowCloseHE.CurrentHost.AllowClose = FALSE

End Sub

26


AllowUpdatesProperty, Host Object 3270 5250 VT

You can use this property to return or set the screen updates flag. When disabled, the system does not perform screen updates. Use this flag to optimize performance or prevent a user from seeing updates while you are performing transactions.

BFPressMethod, Host Object 3270

You can use this method to send the modified data to the host system. The parameter allows you to specify the actual AID (Attention Identifier) sent to the host system in the 3270 datastream. This method is used to support RPQ 7J0048.

Syntax AllowUpdates = TRUE/FALSE


bUpdates = HE.CurrentHost.AllowUpdatesHE.CurrentHost.AllowUpdates = FALSE

End Sub

Syntax BFPress iAIDValue%

where iAIDValue% is the AID key value for the host datastream.


HE.CurrentHost.BFPress &h7D' Press Enter keyEnd Sub

27


BFStatusProperty, Host Object 3270

This read-only property is used to return the status of the extended function keys used to support RPQ 7J0048. The string returned contains the status for each extended function key. There are 48 function keys. The status character for each key can be: '0' - Key is Off, '1' - Key is On, '2' - Key is flashing. Therefore, to check the status of BF Key 10, you would check the tenth character in the string.

BytesProperty, Host Object 3270 5250 VT

This read-only property returns the number of bytes in the presentation space of the host object. It is equal to the number of columns multiplied by the number of rows.

Syntax szStatus$ = BFStatus

where szStatus$ is the status string for all BF keys.


status$ = HE.CurrentHost.BFStatusEnd Sub

Syntax iBytes% = Bytes


iBytes% = HE.CurrentHost.BytesMsgBox "The number of Bytes in the presentation space is & iBytes%, , "

Information"End Sub

28


CaptureProperty, Host Object 3270 5250 VT

You can use this read/write property to get or set the capture mode for the host object. You can retrieve the current setting for the capture mode or you can set a new value.

You can enable constant capturing of TN3270 and TN5250 panels as they are received from the host. In Telnet, you can capture data in Text or Raw Mode. The capture file is set using the SaveFile property.

CaptureOIAProperty, Host Object 3270 5250

You can use this read/write property to get or set the capture operator information area (OIA) flag for the host object. When the value is TRUE, the system captures the OIA in every screen. When the value is FALSE, the system does not capture the OIA.

Syntax Capture = TRUE/FALSE


bMode = HE.CurrentHost.CaptureHE.CurrentHost.Capture = TRUE

End Sub

Syntax CaptureOIA = TRUE/FALSE


bMode = HE.CurrentHost.CaptureOIAHE.CurrentHost.CaptureOIA = TRUEHE.CurrentHost.SaveScreen "c:\screen.txt"

End Sub

29


CloseMethod, Host Object 3270 5250 VT

You can use this method to close (terminate) the host session and object. This method immediately terminates any host connection and closes the session window.

ColumnsProperty, Host Object 3270 5250 VT

This read-only property returns the number of columns currently defined in the Host object.

ConnectMethod, Host Object 3270 5250 VT

You can use this method to connect a session to a host system. You can only make this call if your current session does not already have a host connection. This method maps directly to the File, Connect menu.

Syntax Close


' Close the current host sessionHE.CurrentHost.Close

End Sub

Syntax iCols% = Columns


iColumns = HE.CurrentHost.ColumnsMsgBox "The number of Columns in presentation space is " & iColumns, ,

"Information"End Sub

30


You can set the host system name and other connection parameters through the Cfg3270 and CfgVT objects.

ConnectByProperty, Host Object 3270 5250 VT

You can use this property to set or retrieve the connection type. The following definitions exist in the hebasic.ebh header:

Const IO_TELNET = 0' All terminal typesConst IO_MODEM = 1' VT OnlyConst IO_MSSNA = 2' 3270 OnlyConst IO_NWSAA = 3' 3270 OnlyConst IO_DEMOLINK = 4' All terminal types

Syntax Connect


HE.CurrentHost.Cfg3270.Host = "MyHost"HE.CurrentHost.Cfg3270.TCPPort = 23HE.CurrentHost.Connect

End Sub

Syntax iMode% = ConnectBy


Sub MainDim HE as ObjectDim Host as Object

Set HE = CreateObject( "HostExplorer" )Set Host = HE.Hosts.Open(1) '1 = 3270 terminal

Host.Model = TN3270_MODEL_2' Set terminal model nextHost.ConnectBy = IO_TELNET' Set connection methodHost.Cfg3270.Host = "myhost.mydomain" ' Set host nameHost.Connect

End Sub

31


ConnectErrorStatusProperty, Host Object VT

This read-only property returns the error status for the last connect request. Valid return codes are:

• 0—No error.

• 1—Busy signal.

• 2—No answer.

• 3—No dial tone.

• 4—Unspecified problem after dialing.

ConnectRCProperty, Host Object 3270 5250 VT

This read-only property returns the connection status for the last connect request. Valid return codes are:

• 0—Not connected.

• 1—Connecting.

• 2—Connected.

Syntax iRc% = ConnectErrorStatus


HE.StartSession "Default.VT"

If HE.CurrentHost.ConnectRC = 0 ThenMsgBox "Error occurred during connect. Rc: " + Str$ (HE.CurrentHost.C

onnectErrorStatus)End If

End Sub

32


CursorProperty, Host Object 3270 5250 VT

You can use this property to get or set the cursor location. The location is expressed with an absolute number from 1 to the screen size. If the value is outside this range, the system ignores the call. In VT mode, the Cursor property is read-only.

Syntax iRc% = ConnectRC


HE.StartSession "Default.3270"

If HE.CurrentHost.ConnectRC 2 ThenMsgBox "Error occurred during connect. Rc: " + Str$ (HE.CurrentHost.C

onnectRC)End If

End Sub

Syntax Cursor = iPos%


iPos% = HE.CurrentHost.CursorHE.CurrentHost.Cursor = 1760MsgBox "The position of the cursor is at " & iPos%, ,"Information"

End Sub

33


CursorRCProperty, Host Object 3270 5250

You can use this property to set the cursor location by using row and column values. If a value is outside the valid range, the system ignores the call. The first position on the screen is row 1 column 1.

Device3279Property, Host Object 3270

This read/write property lets you set the 3270 device as FALSE (3278) or TRUE (3279). For this value to take effect, you must first disconnect and reconnect the session.

Syntax CursorRC iRow%, iCol%

where:

• iRow%—The row position.

• iCol%—The column position.


HE.CurrentHost.CursorRc 5, 6' Set cursor to Row 5, Col 6End Sub

Syntax b3279Device = Device3279


b3279Device = HE.CurrentHost.Device3279MsgBox "The 3270 Device is set to " & b3279Device, , "Information"

End Sub

34


DisconnectMethod, Host Object 3270 5250 VT

You can use this method to disconnect a session from a host system. You can call this method only if your session is currently connected. This method maps directly to the Disconnect item on the File menu.

EABProperty, Host Object 3270

You can use this read/write property to get or set Extended Attribute support. If the value is TRUE, the system enables Extended Attributes. Changing this value takes effect only after you disconnect and reconnect the session.

Syntax Disconnect


HE.CurrentHost.DisconnectEnd Sub

Syntax bVal = EAB


bEAB = HE.CurrentHost.EABMsgBox "The Extended Attribute support has a value of " + bEAB

End Sub

35


FieldIDMethod, Host Object 3270 5250

This method returns the field index for a given position on the screen. You can use this method to access the field object directly. The first position on the screen is 1, whereas the first Field ID index is 0.

Fields CollectionObject, Host Object 3270 5250

The Fields Collection object lets you manipulate a field through a series of methods and properties. This interface provides a device-independent way of dealing with data on the host screen. The first field is Field 0.

Syntax iFieldID% = FieldID( iPos% )

where:

• iPos%—The position to query.

• iFieldID%—The field ID returned for the queried position.


iFldID = HE.CurrentHost.FieldID( 1760 )MsgBox "The ID of the field at position 1760 is " & "'" + iFldID & "'", , "Information"

End Sub

Syntax Dim Fld as ObjectSet Fld = CurrentHost.Fields( iFieldNum% )

where iFieldNum% is the field index to return.

Example Sub MainDim Fld as ObjectDim HE as Object

Set HE = CreateObject( "HostExplorer" )Set Fld = HE.CurrentHost.Fields(2)

MsgBox "Field 2 has length: " + Str$(Fld.Length) + ", Position: " + Str$(Fld.Pos) + ", Value: " + _ Fld.Text

End Sub

36


FontLargerMethod, Host Object 3270 5250 VT

You can use this method to change the session font to the next largest font.

FontSmallerMethod, Host Object 3270 5250 VT

You can use this method to change the session font to the next smallest font.

Syntax FontLarger


HE.CurrentHost.FontLargerEnd Sub

Syntax FontSmaller


HE.CurrentHost.FontSmallerEnd Sub

37


GetIOBufferMethod, Host Object 3270

This method is used when simulating a Host connection through the OLE interface. When you create a connection using the Demo Link, you can retrieve the host data stream, which would normally be sent to the host. This method retrieves the host data stream field-by-field. The first field is field 1. If you pass an iFieldNum% of -1, the AID value is returned as an integer string. For example, "Enter", which is AID 0x7D, would return the string "125".

HideMethod, Host Object 3270 5250 VT

You can use this method to hide the host object. This will hide the screen whether it is minimized, normal, or maximized. When the screen is hidden, it no longer appears in the taskbar.

Syntax strVal$ = GetIOBuffer( iFieldNum% )

where:

• iFieldNum%—The field to query.

• strVal$—The string returned from the I/O buffer.


' Wait for 60 seconds for user to press action keyiRc% = HE.CurrentHost.WaitForIO( 60 )

If iRc% = 0 ThencAID$ = HE.CurrentHost.GetIOBuffer( -1 )strField1$ = HE.CurrentHost.GetIOBuffer( 1 )

End IfEnd Sub

Syntax Hide

38


HideToolbarMethod, Host Object 3270 5250 VT

You can use this method to hide the session toolbar.

HighlightTextMethod, Host Object 3270 5250 VT

You can use this method to return text that you have highlighted on the screen by using your mouse. The parameter row% selects the row of highlighted text to return. Row 1 is the first highlighted row; row 2 is the second, and so on. Passing a row number of 0 will result in the entire highlighted block being returned with newline characters "\n" as line separators. If you specify an invalid row number, you will get a null string.


' Hide the current host screenHE.CurrentHost.Hide

End Sub

Syntax HideToolbar


HE.CurrentHost.HideToolbarEnd Sub

Syntax szText$ = HighlightText( row% )

where:

• row%—The highlighted row to return.

• szText$—The string returned.

39


Host Object Methods and Properties3270 5250 VT

The methods and properties of the Host object let you configure and manipulate all aspects of a screen. You can access a host screen in two ways:

• Use the CurrentHost object (applies to the currently or previously active screen). This method is useful if you are writing scripts that access only one session.

• Use the Hosts(n) object, where n is a value from 1 to Hosts.Count (the total number of available sessions). You can use this method to access the nth session available.


szText$ = HE.CurrentHost.HighlightText( 0 )MsgBox "The content of the highlighted area is " & szText$, ,"Hummingb

ird Basic Output"End Sub

Note: You can access host methods directly using the “With” statement, or by creating an object for easy reference.

40


IndexProperty, Host Object 3270 5250 VT

You can use this property to return the unique ID for the current session. This is the session control block ID used internally. This corresponds to the value used in the Hosts(n) property. The first session has an index value of 0.


HE.CurrentHost.InsertMode = FALSEEnd SubSub MainDim HE as ObjectSet HE = CreateObject( "HostExplorer" )

With HE.CurrentHost.InsertMode = FALSEEnd With

End SubSub MainDim HE as ObjectSet HE = CreateObject( "HostExplorer" )

Dim Host as ObjectSet Host = HE.Hosts(1)' Access 1st session

Host.InsertMode = FALSEEnd Sub

Syntax UniqueSessID


UniqueSessID% = HE.CurrentHost.IndexMsgBox "The ID of the current session is " & UniqueSessID%, ,"Information"

End Sub

41


InsertModeProperty, Host Object 3270 5250

This property is used to get or set the insert mode for the host session.

IsConnectedProperty, Host Object 3270 5250 VT

This read-only property returns the value TRUE if the session is connected to a host system. It returns the value FALSE if the session is not in use.

Syntax InsertMode = TRUE/FALSE


bMode = HE.CurrentHost.InsertModeHE.CurrentHost.InsertMode = TRUE

End Sub

Syntax bVal = IsConnected


If HE.CurrentHost.IsConnected = FALSE ThenMsgBox "Not connected to host system!", , "Information"

ElseMsgBox "Connected to host system!", , "Information"

End IfEnd Sub

42


IsXferProperty, Host Object 3270

This read-only property returns a TRUE value if a file transfer is currently taking place.

KeyboardProperty, Host Object 3270 5250 VT

You can use this property to get or set the locked keyboard mode. When set to TRUE, the host keyboard locks, preventing user input. You can unlock the host keyboard by setting this value to FALSE.

Syntax bVal = IsXfer


HE.CurrentHost.SendFile "c:\config.sys", "CONFIG SYS A1" , "( ASCII CRLF"If HE.CurrentHost.IsXfer ThenMsgBox "Wait until File Transfer is complete"

End IfEnd Sub

Syntax Keyboard = TRUE/FALSE


iKeybLocked = HE.CurrentHost.KeyboardHE.CurrentHost.Keyboard = FALSE

End Sub

43


KeysMethod, Host Object 3270 5250 VT

You can use this method to press keys while in HostExplorer. You can insert special sequences in 3270, 5250, or VT mode to press system keys such as Tab, Reset, and so on. Valid return codes are:

• 0—String processed successfully

• 5—Error processing string. Keyboard locked. If the keystring$ contains an AID key, the function will always return a value of 5.

Note: The Keys method is affected by the Type Ahead setting. If you send a 3270/5250 AID key and Type Ahead is enabled, the function will not return until the keyboard is unlocked by the host system. If Type Ahead is disabled, the function will always return immediately.

Syntax iRc% = Keys( keystring$ )

where:

• keyString$—The string to type.

• iRc%—The return code.


' Send USERID, Tab, PASSWORD, EnterHE.CurrentHost.Keys "USERID@TPASSWORD@E"

End Sub

44


LoadQuickKeyFileMethod, Host Object 3270 5250 VT

You can use this method to load a new set of Quick-Keys for this session. Quick-Keys are shared between sessions and loading a new set of Quick-Keys from one session will affect other sessions. Valid return codes are:

• 0—Successfully loaded Quick-Keys.

• 1—Error loading Quick-Keys.

LoadSlideShowFileMethod, Host Object 3270 5250 VT

You can use this method to load a datastream image for the current session. The file must contain the datastream in the correct binary format. You can create a datastream by using the Dlg-Save-Demo-File system command from the emulator. Valid return codes are:

• 0—Successfully loaded datastream image.

• 1—Error loading datastream image.

Syntax iRc% = LoadQuickKeyFile( szFileName$ )

where:

• szFileName$—The Quick-Key file to load. No path or extension specified.

• iRc%—The return code for the method.


iRc% = HE.CurrentHost.LoadQuickKeyFile( "MYQUICKKEYS" )End Sub

Syntax iRc% = LoadSlideShowFile( szFileName$ )

where:

• szFileName$—The path/file name to load.

• iRc%—The return code for the method.

45


MaximizeMethod, Host Object 3270 5250 VT

You can use this method to maximize the host session window.

MinimizeMethod, Host Object 3270 5250 VT

You can use this method to minimize the host session window.


iRc% = HE.CurrentHost.LoadSlideShowFile( "c:\test.dem" )End Sub

Syntax Maximize


' Maximize the current host screenHE.CurrentHost.Maximize

End Sub

Syntax Minimize


' Minimize the current host screenHE.CurrentHost.Minimize

End Sub

46


ModelProperty, Host Object 3270 5250 VT

This read/write property returns the model type for the session or sets the model for the session. Changing this value will take effect only after you disconnect and reconnect a session.

Syntax iModel% = Model

Mode For 3270, the possible values are: 2, 3, 4, or 5.

For 5250, the possible values are: 2 or 5.

For Telnet, the possible values are:

• TELNET_VT52

• TELNET_VT100

• TELNET_VT101

• TELNET_VT102

• TELNET_VT220

• TELNET_VT320

• TELNET_VT420

• TELNET_ANSI

• TELNET_SCOANSI


Sub MainDim HE as ObjectSet HE = CreateObject( "HostExplorer" )

iModel = HE.CurrentHost.ModelMsgBox "This session is of Model Type " + iModel, , "Information"

End Sub

47


MouseToCursorProperty, Host Object 3270 5250 VT

You can use this R/O property to return the position of the mouse in screen coordinates. If the mouse is not in the screen area, the value returned is -1. Otherwise, the value returned is between 1 and the screen size. The screen size is the number of rows multiplied by the number of columns.

OIAProperty, Host Object 3270 5250 VT

This property returns the operator information area (OIA) as a text string. This is a read-only property.

Syntax iPos% = MouseToCursor


iPos = HE.CurrentHost.MouseToCursorEnd Sub

Syntax szOIA$ = OIA


szOIA = HE.CurrentHost.OIAMsgBox szOIA, , "Content of Operator Information Area (OIA)"

End Sub

48


OIAUpdatedProperty, Host Object 3270 5250 VT

If the system returns a TRUE value (Updated), and the operator information area (OIA) was updated since the last call, the system will reset the internal flag to FALSE (Not Updated) after the call. This is a read-only property.

PauseMethod, Host Object 3270 5250 VT

You can use this method to pause the macro for the specified time in milliseconds.

PrintScreenMethod, Host Object 3270 5250 VT

You can use this method to print the current host session to the Windows printer specified in the profile for the session.

Syntax bVal = OIAUpdated


bUpdated = HE.CurrentHost.OIAUpdatedMsgBox "OIA Return Value is " & bUpdated, , "Information"

End Sub

Syntax PrintScreen


' Pause for 5 secondsHE.CurrentHost.Pause 5000

End Sub

Syntax PrintScreen

49


ProtectedTextMethod, Host Object 3270 5250

You can use this method to replace text in protected locations of the screen. Use this method carefully since you can overwrite field attributes.

PSReservedProperty, Host Object 3270 5250 VT

You can use this property to get or set the session-reserved flag. When you reserve a session (TRUE), the system does not allow user input. When the flag is FALSE (default), the user can type and use the menu. This makes the screen read-only.


HE.CurrentHost.PrintScreenEnd Sub

Syntax ProtectedText iRow%, iCol%, szText$

where:

• iRow%—The row in which to write text.

• iCol%—The column in which to write text.

• szText$—The text to write.


HE.CurrentHost.ProtectedText 2, 2, "Hello World"End Sub

Syntax PSReserved = TRUE/FALSE

50


PSUpdatedProperty, Host Object 3270 5250 VT

This read-only property returns a TRUE value if the presentation space was updated since the last call to this property. This property resets the internal flag to FALSE (not updated) after each call.

Use this function to synchronize with host applications.


bReserved = HE.CurrentHost.PSReservedHE.CurrentHost.PSReserved = FALSE

End Sub

Syntax bVal = PSUpdated


bUpdated = HE.CurrentHost.PSUpdatedMsgBox "Presentation Space Value is " & bUpdated, , "Information"

End Sub

51


PutTextMethod, Host Object 3270 5250 VT

You can use this method to write text to any unprotected location on the screen. In VT mode, the iRow and iCol parameters are ignored and can be omitted. The first location on the screen is Row 1 Column 1. This method is identical to the Keys method but it allows you to specify the location to write the text.

QueryCloseRequestProperty, Host Object 3270 5250 VT

You can use this property to see if the user attempted to close the session. The R/O property returns TRUE if the user attempted to close the session (File/Close Session, File/Exit All, Alt-F4). This query is valid only if you disabled the session close using the AllowClose property.

Syntax PutText szText$, iRow%, iCol%

where:

• szText$—The text to write.

• iRow%—The row in which to write text.

• iCol%—The column in which to write text.


HE.CurrentHost.PutText "Hello World", 2, 2End Sub

Syntax bCloseRequested = QueryCloseRequest


HE.CurrentHost.AllowClose = FALSEbCloseRequest = HE.CurrentHost.QueryCloseRequest

End Sub

52


QuickKeyFileProperty, Host Object 3270 5250 VT

You can use this read-only property to return the set of Quick-Keys that are currently loaded.

ReceiveFileMethod, Host Object 3270 VT

You can use this method to initiate a file transfer (download) from the host system.

In 3270 mode, the first parameter specifies the local file to receive the data, the second parameter specifies the host filename to download, and the last parameter specifies the host file transfer options. For more information, see “File Transfer Options” on page 189.

In VT mode, the first parameter specifies the local file to receive the data and the second parameter specifies the file transfer protocol to use. When using ZModem, this parameter should be a path since the filename will be provided by the ZModem protocol.

Syntax szQuickKey$ = QuickKeyFile


szQuickKeys$ = HE.CurrentHost.QuickKeyFileEnd Sub

53


Syntax For 3270 mode, the syntax is:

ReceiveFile pcfilename$, hostfilename$, options$

For VT mode, the syntax is:

ReceiveFile pcfilename$, iXferProtocol%

where:

• pcfilename$—The PC file name to receive the host file.

• hostfilename$—The name of the host file to download.

• options$—Options for this file transfer.

• iXferProtocol%—The file transfer protocol to use. Refer to hebasic.ebh for values.


' 3270 mode downloadHE.CurrentHost.ReceiveFile "c:\profile.txt", "PROFILE EXEC A1", "( ASCII CRLF"HE.CurrentHost.WaitXfer

' VT mode downloadHE.CurrentHost.ReceiveFile "c:\vtfile.txt", XFER_TYPE_ZMODEM

End Sub

54


RestoreMethod, Host Object 3270 5250 VT

You can use this method to restore the host object. This is a non-maximized mode.

RowMethod, Host Object 3270 5250 VT

You can use this method to retrieve the contents of the screen row-by-row. The numeric parameter specifies which row to retrieve. The value for the parameter can range between 1 and the number of rows in the presentation space. Here, you can convert nulls to blanks.

Syntax Restore


' Restore the current host screenHE.CurrentHost.Restore

End Sub

Syntax szRowText$ = Row( iRow% )

where:

• iRow%—The row from which to retrieve text.

• szRowText$—The string retrieved from the row.


SecondRow$ = HE.CurrentHost.Row(2)MsgBox "The content of the specified row in the presentation space is"

& SecondRow, , "Output"End Sub

55


RowsProperty, Host Object 3270 5250 VT

This read-only property returns the number of rows currently defined in the host object.

RunCmdMethod, Host Object 3270 5250 VT

You can use this method to run a system command within the session. You can assign system commands to keys and tool items. You can also use system commands within a macro.

Syntax Rows


iRows = HE.CurrentHost.RowsMsgBox "The number of rows in the presentation space is " & iRows, , "Information"

End Sub

Note: The RunCmd method is affected by the Type Ahead setting. If you send a 3270/5250 AID key (for example, Enter, PFx, and so on) and Type Ahead is enabled, the function will not return until the keyboard is unlocked by the host system. If Type Ahead is disabled, the function will always return immediately.

56


RunQuickKeyMethod, Host Object 3270 5250 VT

You can use this method to run a Quick-Key within the session.

Syntax RunCmd szCommandName$

where szCommandName$ is the name of command to execute.


' Show the Session Profile dialogHE.CurrentHost.RunCmd "Dlg-Edit-Session-Profile"

End Sub

Syntax RunQuickKey szQuickKeyName$

where szQuickKeyName$ is the name of the Quick-Key to execute.


'Make sure you create a Quick-Key before running this macroHE.CurrentHost.RunQuickKey "dothis"

End Sub

57


SaveQuickKeyFileMethod, Host Object 3270 5250 VT

You can use this method to save Quick-Keys to disk. Do not supply a path or extension for the file name.

SaveScreenMethod, Host Object 3270 5250 VT

You can use this method to save the session screen to a file.

Syntax SaveQuickKeyFile szQuickKeyFileName$

where szQuickKeyFileName$ is the file name of the Quick-Keys to save.


HE.CurrentHost.SaveQuickKeyFile "VMCMS"End Sub

Syntax SaveScreen szFileName$

where szFileName$ is the name of the file to which the screen is saved.


HE.CurrentHost.SaveScreen "c:\screen.txt"End Sub

58


SaveScrollbackMethod, Host Object VT

You can use this method to save the session scrollback buffer to a file.

SearchMethod, Host Object 3270 5250 VT

You can use this method to search the presentation space for the given search string. The bCaseSensitive flag specifies whether the search is case-sensitive or not. iRow% and iCol% specify the starting position for the search. If iRow% is not passed, the cursor row is used instead. If iCol% is not passed, the cursor column is used instead. Valid return codes are:

• n—The string was found in the presentation space at the location of n, where n is a value of 1 or greater. For example, a returned value of 1 indicates that the string is located at the top left-hand corner of the session screen.

• 0—String was not found in the presentation space.

Syntax SaveScrollback szFileName$

where szFileName$ is the name of the file to which the scrollback buffer is saved.


HE.CurrentHost.SaveScrollback "c:\scrollback.txt"End Sub

59


If you use variables in the parameter list (as opposed to constants), the method will return the row and column where the text was found.

SendFileMethod, Host Object 3270 VT

You can use this method to initiate a file transfer (upload) to the host system.

In 3270 mode, the first parameter specifies the local file to be uploaded, the second parameter specifies the host filename to receive the file, and the last parameter specifies the host file transfer options. For more information, see “File Transfer Options” on page 189.

Syntax iRc% = Search( szSearchString$, bCaseSensitive, iRow%, iCol% )

where:

• szSearchString$—The string that HostExplorer attempts to find.

• bCaseSensitive—The case-sensitive flag – TRUE/FALSE

• iRow%—The row in which to start the search.

• iCol%—The column in which to start the search.


iRow = 1iCol = 1

iRc% = HE.CurrentHost.Search( "VM/ESA", FALSE, iRow, iCol)If iRc% > 0 ThenMsgBox "String found at Row:" & iRow & ", Col: " & iCol

End IfEnd Sub

60


In VT mode, the first parameter specifies the local file to receive the data and the second parameter specifies the file transfer protocol to use.

SetFontMethod, Host Object 3270 5250 VT

You can use this method to change the session font to a specific name, width, and size. If you specify a width of 0, the system will select a visually proportioned font. The font generated may not actually match the characteristics of those you requested.

Syntax SendFile pcfilename$, hostfilename$, options$SendFile pcfilename$, iXferProtocol%

where:

• pcfilename$—The name of the PC file to upload to the host.

• hostfilename$—The name of the host file to receive the transferred file.

• options$—The option for this file transfer.

• iXferProtocol%—The file transfer protocol to use. Refer to hebasic.ebh for values.


' 3270 mode uploadHE.CurrentHost.SendFile "c:\config.sys", "CONFIG SYS A1", "( ASCII CRLF"HE.CurrentHost.WaitXfer

' VT mode uploadHE.CurrentHost.SendFile " c:\config.sys", XFER_TYPE_ZMODEM

End Sub

Syntax SetFont fontname$, width%, height%

where:

• fontname$—The name of the font.

• width%—The width of the font (in pixels).

• height%—The height of the font (in pixels).

61


ShortNameProperty, Host Object 3270 5250 VT

You can use this property to get or set the session short name.

The session short name is used primarily by HLLAPI applications. Changing the short name of a session will take effect immediately and does not require the emulator or session to be restarted.


HE.CurrentHost.SetFont "Courier New",0, 12End Sub

Note: The short name must be only one character.

Syntax ShortName = "c"

strVal$ = ShortName


' Assign letter 'A' to this sessionHE.CurrentHost.ShortName = "A"

End Sub

62


ShowMethod, Host Object 3270 5250 VT

You can use this method to show the Host object. This displays the screen whether it is minimized, normal, or maximized.

ShowToolbarMethod, Host Obj

hostexplorer programmer's guideftp.iitm.ac.in/.../documentation/hostexplorerprogramming.pdfii...

Documents