Technical Bulletin
Using OBJECTX™ 1.1 Controls in Microsoft® Internet Explorer 3.xx
Summary This technical bulletin focuses on using the NetManage® OBJECTX Development Kit (ODK), version 1.1, to embed NetManage controls in an Internet browser. OBJECTX is the NetManage product that implements Microsoft’s ActiveX™ technology. The only browser currently able to accept an ActiveX control directly is Microsoft’s Internet Explorer 3.xx and above; Netscape® may support ActiveX controls in the future.
Please read the documentation in the OBJECTX SDK for information on the controls in general. HTML examples and source code are included on the OBJECTX CD. Supported Browsers (as of September, 1997)
NOTE: Within this technical bulletin, references to “browser” will mean Microsoft Internet Explorer 3.xx unless explicitly stated otherwise.
Because of the version of software that provides the digital signature on OBJECTX controls, you must use Internet Explorer version 3.02 or later. Of course, you can disable security entirely, but this approach is highly discouraged. To make it easier for you to update your browser, the OBJECTX Development Kit contains Microsoft Internet Explorer 3.02.
Microsoft Internet Explorer 3.xx (and above) is the only Web browser that directly supports the embedding of ActiveX controls at this time. Netscape may have a version available in the future that will support ActiveX controls. There is a 3rd-party plug-in (ScriptActive™) available from NCompass® Labs that handles some ActiveX controls; however, that plug-in does not work well with the NetManage controls, which include several objects and Dynamic Linked Library (DLL) files.
NetManage is developing technology to provide for communications between the Netscape browser and the NetManage controls. This special-purpose dialog adapter will soon be available for the RUMBA® Mainframe Display and RUMBA Mainframe Printer ActiveX controls. Other NetManage controls can be “wrapped” with this technology.
NetManage, Inc. www.netmanage.com
Technical Bulletin
Security Issues NetManage and other providers of code-signed applications recently acquired new signing software from VeriSign™. The pre-packaged controls in the OBJECTX Development kit, version 1.1, are all signed with this latest software. These new certificates of authenticity can only be accepted by Internet Explorer 3.02 (Build 4.70.1300 and later versions) with the Authenticode 2.0 update. If you have security enabled (which you should if you want to protect your desktop from unknown applications), the digital signature will pop up, noting which application is about to be downloaded and who the supplier is. The ODK contains a new version of Microsoft Explorer that includes the Authenticode 2.0 update.
The digital certificate for the pre-packaged controls in the ODK 1.1 will note that the certificate expired 8/2/97. This DOES NOT mean that the certificate itself expired 8/2/97, but rather that the signing authority expired 8/2/97. This signing authority expired due to security changes Microsoft made in Internet Explorer, but all files signed before 8/2/97 remain valid. We just cannot create new certificates under the old authority. NetManage received new signing authority after the OBJECTX Development Kit, version 1.1, was released, and future certificates will reflect the new date (signing authorities usually are valid for one (1) year from date of issue). The individual controls are not digitally signed. Initiating Control Downloads to the Browser All the NetManage controls can be embedded directly in Internet Explorer by providing the file name (usually NNNN.OCX) and the 32-hex-digit Class ID (CLSID or GUID) in an HTML Object tag. However, you may prefer to use the pre-packaged controls provided with the ODK. An example using the control only would look like the following HTML snippet:
Please see the table below for the description of the elements of this HTML code. It is important to note that this code would bring down the control itself, without any of its supporting DLLs. Sometimes a "naked" control is useful, sometimes not. The control- only tag could be used to update the control itself for maintenance purposes through the use of the Version line in the registry under the control’s CLASSID.
The pre-packaged controls are provided in the form of a self-extracting, self-installing, self-registering .EXE file. Because of that, these pre-packaged control files must be
3653.DOC Page 2
Technical Bulletin
executed on the client machine. They are automatically brought down to the client machine by using the CODEBASE identifier within the
The following table describes the items in the example.
OBJECT ID The object ID is declared to be “Mframe”, which will be used throughout the HTML application. CLASSID The registry entry for this object is 91858523-87B5-11CE-A0B6-0800095A05C3. This is the registry ID for the standard RUMBA Mainframe Display control (WDMFDSP.OCX). If this object CLSID (uniquely the RUMBA Mainframe Display control in this case) is already registered in this machine’s registry, then the CODEBASE line is skipped. If the CLSID is not registered, then the browser’s HTML processor will perform the following functions on the file named in the CODEBASE line: • Download and Execute a file if it has a .EXE extension. • Download and Register a file if it has a .OCX extension. • Download and Register a file if it has a .DLL extension. If the file in the CODEBASE line is not located in the same directory as the application with the OBJECT tag, you must include an explicit path. CODEBASE Since there is no explicit path in this CODEBASE line, the MFDSP.EXE file will be loaded using the same URL as this HTML application. If the location is remote (across the Web), the file will be brought down across the Web—automatically! HEIGHT/ This line defines the visible size (in pixels) for the control once it has been embedded. In this WIDTH example, the mainframe presentation space will be 280 pixels high and 550 pixels wide. HTML does not provide for making the height/width values variable at this time, but there are ways to shrink or expand the display space using the mouse cursor which can be a function of a “wrapper” application around the control. You can change these values manually using any text or HTML editor.
The pre-packaged controls in the ODK do not contain any applications. You must use the sample applications provided with the ODK, the samples referenced in this technical bulletin (available on the NetManage FTP site), or write an application yourself.
3653.DOC Page 3
Technical Bulletin
The pre-packaged control files included with the ODK are listed in the following table.
File Name Control & Interface Size (KB) AS4DSPDH.EXE AS/400® Display, Demo Host 2,778 AS4DSPSN.EXE AS/400 Display, MS SNA Server 3.094 AS4DSPTN.EXE AS/400 Display, TN5250 2,776 AS4PRTDH.EXE AS/400 Printer, Demo Host 2,611 AS4PRTSN.EXE AS/400 Printer, MS SNA® Server 2,872 MFDSPDH.EXE Mainframe Display, Demo Host 2,600 MFDSPSA.EXE Mainframe Display, NetWare® SAA® 2,599 MFDSPSN.EXE Mainframe Display, MS SNA Server 2,484 MFDSPTN.EXE Mainframe Display, TN3270 2,731 MFPRTDH.EXE Mainframe Printer, Demo Host 2,657 MFPRTSN.EXE Mainframe Printer, MS SNA Server 2,541 MFPRTTN.EXE Mainframe Printer, TN3270E 2,788 UNXDSPDH.EXE UNIX® Display, Demo Host 3,342 UNXDSPTN.EXE UNIX Display, Telnet 3,005
The file sizes noted above are the sizes of the files that come across the network. The files as installed usually require about 3 MB, depending on the interface. When the pre- packaged control file is executed, its integrated install program places the files in a directory structure under ..\Program Files\WallData\… and updates the registry.
There is a file on the CD for the mainframe display and printer controls for the MS SNA Server interface; however, that file does not work with released product yet. PTFs are available to supply this interface if it is required. Uninstalling Controls There is an Uninstall utility, UNINST.EXE, included on the OBJECTX 1.1 Development Kit. This utility is useful for removing the controls’ CLSIDs from the registry. It also removes the program files associated with the controls, but does leave some configuration files and the directory structure. After you have executed UNINST.EXE, you can drag the \WallData directory structure under Program Files to the Windows Recycle Bin to completely remove the NetManage components from your system.
3653.DOC Page 4
Technical Bulletin
Language Support Considerations As noted previously, when the pre-packaged control file is executed, the integrated install program places the files in a directory structure under C:\Program Files\WallData\… If this directory structure does not exist, the install program creates it. Non-English versions of Windows will use the appropriate local-language version of “Program Files”. The pre- packaged control install will not recognize one of these existing directories and will create a new one using the English-language words “Program Files”.
The pre-packaged controls currently include ASCII-to-EBCDIC (A to E) and EBCDIC- to-ASCII (E to A) tables for English only. These tables (CONVTBLS.USA, CONVTBLS.US1, and CONVTBLS.US2 in the directory \..\WallData\Mframe\Charsets) control the presentation of the host characters on the Windows desktop and depend on the host’s code page as well as the Windows language. Non-English host applications on non-English Windows systems will not show correctly.
The only keyboard supported in the pre-packaged controls is US English through the KBDINFO.USA file in the directory \..\WallData\Mframe\Kbdinfo. If you are going to use the pre-packaged controls you must place the specific CONVTBLS.xxx and KBDINFO.xxx tables in the directories described above following the installation of the controls on the client machine. The files for each country are provided with any RUMBA host product.
Identifying Language-Specific Files The following table lists the CONVTBLS.xxx and KBDINFO.xxx files for the mainframe and AS/400 environments. A blank space in the table means that NetManage has not created a customized file for that country. Country AS/400 AS/400 Mainframe Mainframe CONVTBLS KBDINFO CONVTBLS KBDINFO File File File File Arabic-speaking countries convtbls.420 kbdinfo.arb Australia convtbls.37 convtbls.usa Austria convtbls.273 kbdinfo.grm convtbls.ger Belgium convtbls.500 kbdinfo.bgm convtbls.sws kbdinfo.bgm Brazil convtbls.37 kbdinfo.brp convtbls.usa kbdinfo.brp kbdinfo.brz Canada (AS/400) convtbls.500 kbdinfo.cnd convtbls.usa kbdinfo.cnd Chinese (simplified) convtbls.836 kbdinfo.sch Chinese (traditional) kbdinfo.tch Croatia convtbls.870 Czech convtbls.870 kbdinfo.cze Denmark convtbls.277 kbdinfo.dmk convtbls.dan kbdinfo.dmk
3653.DOC Page 5
Technical Bulletin
Country AS/400 AS/400 Mainframe Mainframe CONVTBLS KBDINFO CONVTBLS KBDINFO File File File File Finland convtbls.278 kbdinfo.fin convtbls.fin kbdinfo.fin France convtbls.297 kbdinfo.frn convtbls.frn kbdinfo.frn Germany convtbls.273 kbdinfo.grm convtbls.ger kbdinfo.grm Greece convtbls.875 kbdinfo.grk Hungary convtbls.870 kbdinfo.hgr convtbls.hgr kbdinfo.hgr Iceland convtbls.871 kbdinfo.ice convtbls.ice kbdinfo.ice Israel (Hebrew) convtbls.424 kbdinfo.heb Italy convtbls.280 kbdinfo.ity convtbls.ity kbdinfo.ity Japanese Katakana convtbls.290 kbdinfo.jpn Korea convtbls.833 kbdinfo.kra Latin America (Spanish) convtbls.284 kbdinfo.ltn convtbls.spn kbdinfo.ltn Netherlands convtbls.37 kbdinfo.ntl convtbls.usa kbdinfo.ntl New Zealand convtbls.37 convtbls.usa Norway convtbls.277 kbdinfo.nwy convtbls.dan kbdinfo.nwy Poland convtbls.870 kbdinfo.pol Portugal convtbls.37 kbdinfo.ptg kbdinfo.ptg Romania convtbls.870 Russia (Cyrillic) convtbls.025 kbdinfo.rus Serbia (Cyrillic) convtbls.025 Serbia (Latin) convtbls.870 Slovakia convtbls.870 kbdinfo.slv Slovania convtbls.870 kbdinfo.sln Spain convtbls.284 kbdinfo.spn convtbls.spn kbdinfo.spn Sweden convtbls.278 kbdinfo.swd convtbls.fin kbdinfo.swd Switzerland convtbls.500 kbdinfo.sfr convtbls.sws kbdinfo.sfr kbdinfo.sgr kbdinfo.sgr Thailand convtbls.838 kbdinfo.thi Turkey convtbls.026 kbdinfo.tky convtbls.trk kbdinfo.tky United Kingdom convtbls.285 kbdinfo.uk convtbls.uk kbdinfo.uk USA convtbls.37 kbdinfo.usa convtbls.usa kbdinfo.usa Control Persistence in Internet Explorer All of the NetManage Display controls are “persistent” in Internet Explorer 3.xx—that is, they remain active and connected even though they may not be visible in the active browser window. This is a challenge for a control-based application, since Internet Explorer 3.xx marks a control for discard if it is not in the active window. NetManage developed a method for keeping the Display controls active even when they are not the active window. This is particularly important in a multi-session environment. NetManage has applied for a US patent on this unique method. The following code sample shows how to activate the persistence control.
3653.DOC Page 6
Technical Bulletin
NOTE: The persistence control needs to appear before the control to which it applies.
The persistence control is embedded in each display control and has the same CLSID for all display controls.
3653.DOC Page 7
Technical Bulletin
Interface Parameter Non-Persistence The pre-packaged controls in the ODK contain the primary functional controls for Display or Printing. The pre-packaged controls also contain a family of supporting DLLs and other files. The interfaces themselves are objects that are external to the controls, but that are managed by the controls in terms of setting their properties and initiating connect and disconnect actions.
The interface properties MUST be set, usually in an initialization section of the application (see the sample HTML applications). The parameters will NOT retain old settings if the browser is closed and then restarted, nor if Windows is restarted.
This non-persistence of interface parameters is different from other RUMBA 95/NT software, where interface parameters can be saved as part of a session profile and then remain set until changed. It is important to note that RUMBA 95/NT software uses an application to drive the controls, reading profile information and setting interface properties during the startup process. In the case of the OBJECTX controls, there is no standard application provided. Focus Considerations The browser is a non-intelligent container. It does not automatically give focus back to an application. Other containers, such as those created using Visual Basic or C++ are better at this focus management.
NetManage added another method (“SetFocus”) to the display controls to address this browser shortcoming, although there are still limitations.
If you use the sample HTML applications referenced in this technical bulletin, you will notice the following behaviors:
A. You will have proper focus in the display applications when you first start them. This is possible because the browser executes a “Window_OnLoad()” event on startup, which the application uses to invoke the “object.SetFocus” method. The example use of this sequence is shown in the VBScript snippet below: Sub Window_OnLoad() MFrame.SetFocus End Sub Where Mframe is the name assigned to the control in the
3653.DOC Page 8
Technical Bulletin
B. If you change focus to another Windows application and then return it to the browser by clicking it or using Alt-Tab to get to it, you will regain focus properly with the AS/400 display control (if you use SetFocus as noted above). However, you need to set the focus manually for the Mainframe Display Control by positioning the mouse cursor where you want and then left-button clicking. C. When you read the sample HTML applications, you will notice the use of the SetFocus method throughout the application—specifically in the button-click subprograms. This is required to return focus to where it was (including the cursor position) when the subprogram is finished. This use of SetFocus is not only useful in the types of applications where you are using the display controls as emulator windows (where cursor position is important), but also in other applications that provide their own presentation services. Using the Microsoft Control Pad Utility Microsoft provides a utility called the ActiveX Control Pad which you can use to create sample application shells for ActiveX controls. It queries the control and presents a list of the control’s Properties.
The ActiveX Control Pad also sets the Properties for the control to the default values. This works fine for those properties that represent the control itself. However, it does not work for those properties that represent another object that is managed by the control; for example, the Display control includes other objects and collections such as the Interface Object, the HostFields Collection, and the Attributes Object. In order to work with these objects and collections, you must use the methodologies documented in the reference material in the OBJECTX 1.1 SDK or this technical bulletin and refer to the sample HTML applications for examples of working applications. Licensing The OBJECTX 1.1 SDK includes a license to use the NetManage OBJECTX controls on the developer’s desktop only. There is NO license to distribute these controls to other desktops. The controls are not licensed individually; a customer must have a license for a RUMBA 95/NT software product that contains the required controls in order to legally use a developer application that uses those controls.
Any sample applications that are included with the OBJECTX 1.1 Development Kit are provided on an “as is” basis in both executable and source-code form. A developer is free to take these applications, modify them to suit their purposes, and distribute them as they choose with a zero dollar ($0) license fee. However, the customer who then uses that
3653.DOC Page 9
Technical Bulletin
application must have purchased RUMBA 95/NT software in order to legally use the application. Interface Parameters–Mainframe NetWare SAA You can control the NetWare SAA interface parameters using Visual Basic script within an HTML application. The following code snippet is an example showing how to set parameters for the SAA Server for a TCP/IP connection with User Name and Password specified.
In general, the Methods, Properties, and Events are the same for the mainframe and AS/400. You will see this as you read the source code for the various applications referred to in this technical bulletin.
The following section provides additional details on the parameter options. The above snippet is only a subset.
Novell SAA for the Mainframe • LogonOptions option 0 = Use Logon User Name 1 = Prompt for User Name and Password 2 = Specify User Name and Password • UserName username - used if option 2 is selected from LogonOptions • Password password- used if option 2 is selected from LogonOptions • ServerIdentifier option 0 = Use server name when connecting over IPX/SPX 1 = Use network address when connecting over IPX/SPX 2 = Use TCP/IP • ServerName name - used if option 0 is selected from ServerIdentifier • ServerNetworkAddress address - used if option 1 is selected from ServerIdentifier • ServiceName name - same as “Service Name” • LUCategory option 0 = Public 1 = Any 2 = Group 3 = Dedicated • GroupOrLUName name - same as “Group / LU Name” (used if option 2 or 3 is selected from LUCategory) • LoadBalancing true/false
3653.DOC Page 11
Technical Bulletin
0 = off 1 = on • HotStandBy true/false 0 = off 1 = on • TCPIPTimeout timeout • Add address/name - adds an address to the top of the address list • Remove index - removes an address at the specified index from the address list VBScript Examples IPX/SPX MFrame.HostInterface.Name = "WallData.SAALink" MFrame.HostInterface.Interface.LogonOptions = 2 'wdSpecifyUserName MFrame.HostInterface.Interface.UserName = "GUEST" MFrame.HostInterface.Interface.Password = "" MFrame.HostInterface.Interface.ServerIdentifier = 0 'wdIPXSPXServerName MFrame.HostInterface.Interface.ServerName = “BEAVIS” MFrame.HostInterface.Interface.LUCategory = 1 'wdAnyLU MFrame.HostInterface.Interface.LoadBalancing = 0 MFrame.HostInterface.Interface.HotStandBy = 0 MFrame.HostInterface.Commit MFrame.Connect TCP/IP MFrame.HostInterface.Name = "WallData.SAALink" MFrame.HostInterface.Interface.LogonOptions = 2 'wdSpecifyUserName MFrame.HostInterface.Interface.UserName = "GUEST" MFrame.HostInterface.Interface.Password = "" MFrame.HostInterface.Interface.ServerIdentifier = 2 'wdTCPIP MFrame.HostInterface.Interface.LUCategory = 2 'Group MFrame.HostInterface.Interface.GroupOrLuName = "pool" MFrame.HostInterface.Interface.Add "198.252.70.104" MFrame.HostInterface.Interface.LoadBalancing = 0 MFrame.HostInterface.Interface.HotStandBy = 0 MFrame.HostInterface.Commit MFrame.Connect
3653.DOC Page 12
Technical Bulletin
Interface Parameters–Mainframe MS SNA Server As with the NetWare SAA interface, you are able to control the MS SNA Server interface parameters using VBScript within your HTML application. In general, the Methods, Properties, and Events are the same for the mainframe and AS/400. You will see this as you read the source code for the various applications attached to this technical bulletin.
MS SNA Server for the Mainframe • LUSelection option 0 = System Defined 1 = Select LU from LU/Pool List 2 = Specify Other • LUName LUname - used if option 1 or 2 is selected from LUSelection • LUIndex index- used if option 1 is selected from LUSelection (0-based) • AutoReconnect true/false 0 = off 1 = on • AssignedProfile – returns the User name • NumSessions – returns the maximum number of sessions for this user • Item index – returns the LU/Pool name at the specified index from the list (0- based) • Count – returns the number of items in the LU/Pool list • StartupError – must be the first method called – returns the result of the client load and initialization as follows: 0 = "No Error" 1 = "Cannot find the file SNADMOD.DLL in the current path. This file is provided with your Microsoft SNA Server Software." 2 = "Memory allocation failure" 3 = "Cannot lock memory" 4 = "Configuration Server Not Found" 5 = "User name is not configured to access Server" 6 = "Network not started" 7 = "User not logged on to the network" 8 = "Cannot read configuration file" 9 = "NAP not started" 10 = "Maximum number of applications are running" 11 = "Network not started or NAP not started"
3653.DOC Page 13
Technical Bulletin
VBScript Examples System Defined MFrame.HostInterface.Name = "WallData.SNAServer" Retcode = MFrame.HostInterface.Interface.StartupError If Retcode = 0 Then MFrame.HostInterface.Interface.LUSelection = 0 ‘wdSystemDefined MFrame.HostInterface.Interface.AutoReconnect = 0 MFrame.HostInterface.Commit MFrame.Connect Else MsgBox(“Initialization failure”) End If User Defined from List MFrame.HostInterface.Name = "WallData.SNAServer" Retcode = MFrame.HostInterface.Interface.StartupError If Retcode = 0 Then MFrame.HostInterface.Interface.LUSelection = 1 ‘wdLUPoolList MFrame.HostInterface.Interface.LUIndex = 4 ‘5th item in the list (0-based) MFrame.HostInterface.Interface.AutoReconnect= 0 MFrame.HostInterface.Commit MFrame.Connect Else MsgBox(“Initialization failure”) End If SpecifyOther MFrame.HostInterface.Name = "WallData.SNAServer" Retcode = MFrame.HostInterface.Interface.StartupError If Retcode = 0 Then MFrame.HostInterface.Interface.LUSelection = 2 ‘wdSpecifyOther MFrame.HostInterface.Interface.LUName = “TEST” MFrame.HostInterface.Interface.AutoReconnect= 0 MFrame.HostInterface.Commit MFrame.Connect Else MsgBox(“Initialization failure”) End If
3653.DOC Page 14
Technical Bulletin
© 2004 NetManage, Inc., its subsidiaries, and its affiliates. NetManage, OnWeb, RUMBA, OneStep and the Chameleon logos are registered trademarks, registered service marks, trademarks or service marks of NetManage, Inc., its subsidiaries and its affiliates in the United States and/or other countries. IBM, AS/400, DOS, SNA, and PC are registered trademarks of International Business Machines Corporation. Novell and NetWare are registered trademarks of Novell, Inc. Microsoft, Windows and Windows NT are registered trademarks of Microsoft Corporation in the United States and/or other countries. Certain other marks are the property of their respective owners.
The information in this technical bulletin is subject to change without notice. NetManage, Inc. provides this information “as is” without warranty of any kind, either expressed or implied, but not limited to the implied warranty of merchantability and fitness for a particular purpose. NetManage, Inc. may improve or change the product at any time without further notice. This document does not represent a commitment on the part of NetManage, Inc. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used only in accordance with the terms of the licensing agreement.
3653.DOC Page 15