Global Technical Support wIntegrate Troubleshooting Guide Version 1.0
September 24, 2013
Table of Contents
Introduction ...... 1 Communications ...... 1 Connection closed by host/Connection aborted ...... 1 Host programs ...... 1 File transfer and case inversion on UniVerse...... 2 Debug recordings ...... 2 Record ...... 2 Documentation ...... 4 How do you install the documentation? ...... 4 File Transfers ...... 5 Missing file transfer options ...... 5 Problems using Reformat mode ...... 7 Unable to import more than 10mb of data ...... 8 Checksum errors ...... 9 General Features ...... 9 Double quotes ' " ' are converted to “?” when pasted into a wIntegrate session from Microsoft Word 9 Remapping characters that paste as “?” ...... 10 Special character
'Invalid fields' error when using BEFORE or AFTER boxes in Query Builder ...... 17
wIntegrate Troubleshooting Guide ii September 24, 2013
Introduction wIntegrate is a connectivity tool which integrates host-based applications with the Windows desktop. The graphical user interface lets you emulate a terminal and customize your workspace environment. wIntegrate lets you share data with other Windows applications including Microsoft Word and Excel. Additionally, it imports and exports data between the PC and server, and from server to server.
This Troubleshooting Guide describes problems that have been reported when using wIntegrate and the solutions to those problems. Our intention is that this Guide provides a one-stop reference that you can use to resolve most of the problems you may encounter using wIntegrate.
Communications
Connection closed by host/Connection aborted wIntegrate uses Windows Sockets to communicate to a server using the Telnet protocol. Windows Sockets manages the connection and notifies wIntegrate when the connection has been closed, but not why or whether the server or the network closed the connection. When the connection to a UNIX server has been closed, wIntegrate displays “Connection closed by host”. When the connection to a Windows server has been closed, wIntegrate displays “Connection aborted”.
If you are receiving one of these errors, use the Windows Telnet tool to confirm the problem is not within wIntegrate. Open a Command Prompt window then enter “telnet
You can check the server is reachable by entering “ping
Host programs
When you install an updated version of wIntegrate it’s always a good idea to install the new host programs that came with it. These will support any new features, and occasionally have performance improvements. We take great care to ensure new versions of the host programs are fully backward compatible with previous versions of the client program. So if you have multiple versions of wIntegrate installed at your site, always install the latest version of the host programs.
wIntegrate Troubleshooting Guide 1 September 24, 2013
To install the host programs, select Run | Script from the wIntegrate main menu, then select \Program Files (x86)\wIntegrate\Host\inst_pgm.wis. Complete instructions can be found in the Using wIntegrate manual.
File transfer and case inversion on UniVerse
By default, a new install of UniVerse inverts the case, so when you think you’re typing “A” the letter “a” appears, and vice versa. This case inversion can corrupt the file transfer and other host-to-PC operations. This can affect the host routine installation.
To prevent the case inversion and revert to expected behavior, at the TCL prompt, enter PTERM –CASE NOINVERT.
You might consider adding this line to your LOGIN paragraph in the VOC.
Debug recordings wIntegrate has powerful debug recording features that are used to capture the two-way conversation between wIntegrate and the server it’s connected to. Generally, you’d send any recordings to your Support personnel or U2 Support for review.
Record
The basic recording is enabled using the Edit | Record option from the main menu. There are three options that are useful to Support when diagnosing a problem - Raw data, Control codes, and Two-Way.
wIntegrate Troubleshooting Guide 2 September 24, 2013
Raw data
Records characters sent by the host to the PC, including terminal command sequences. This is essentially an illegible format. It can be replayed (in Edit | Play with the Local option turned on) to reproduce any terminal emulation issues.
Control codes
Records characters sent by the host to the PC. Data is shown in a legible format analyzing how wIntegrate has interpreted the host characters in relation to the current terminal emulation. Use this option to document a sequence of actions that result in a failure or problem. You can use the recorded file to analyze and resolve problems.
For example, if you see obvious escape sequences jumbled together, and/or described as “Text” it probably means that that a sequence has not been recognized as a terminal escape sequence. So some adjustment is needed to the emulation definitions, which are user-definable.
Two-Way
Records characters sent by the host to the PC and received from the server. Data is shown in a legible format analyzing how wIntegrate has interpreted the host characters in relation to the current terminal emulation.
wIntegrate Troubleshooting Guide 3 September 24, 2013
Documentation
How do you install the documentation?
The wIntegrate Autorun program starts when you insert the wIntegrate CD in the drive. Select Manuals Menu. You can view or install the manuals.
Select Install Manual(s). The “Using wIntegrate” manual is the only manual installed with the Default option. Select Custom to install all of the manuals. The Custom Setup dialog is displayed. Select “This feature will be installed on local drive” for each manual you wish to install.
wIntegrate Troubleshooting Guide 4 September 24, 2013
File Transfers
Missing file transfer options
The wIntegrate file transfer options are found on the Run menu along with a few advanced features. These should be enabled at installation.
wIntegrate Troubleshooting Guide 5 September 24, 2013
If these options are not visible on the Run menu:
1. Select Setup | Application. 2. Select the Scripts tab. 3. Add “wIntSys\Script\NewSess.wis” in the Pre-session open: field:
4. Click OK. wIntegrate Troubleshooting Guide 6 September 24, 2013
This updates the Registry and applies to all sessions opened on the PC. You don’t need to save the session after making the change.
Problems using Reformat mode when importing files
Reformat mode uses the database REFORMAT command to create a temporary file in the account. That temporary file is then imported. The temporary file name is WIN.RFMT
Because a server file is being created, you need to be sure there is enough disk space on the drive to accommodate the potential size of the temp file. If you will be transferring a large amount of data, you could run out of disk space and the transfer fail. When this occurs, the temporary file is not deleted so you will need to manually remove it.
The default timeout in wIntegrate is 10 seconds. If the file being transferred is very large, it may take a while for the temporary file to be populated. You may need to increase the timeout on the Import File dialog if you find the connection is timing out before the transfer begins. wIntegrate Troubleshooting Guide 7 September 24, 2013
Unable to import more than 10mb of data
The wIntegrate file transfer process imposes a restriction on the size of the file that can be imported from the host to the PC. On older types of system (Adds Mentor, Ultimate, and IN2) the largest file you can transfer is 32K. This is due to a limit on the maximum record size imposed by those operating systems. On Prime, the maximum file size that can be transferred is 1MB, and on all other machine types it's 10MB.
Increasing the Maximum File Size
If your host doesn't impose a limit on the maximum record size, you may increase this parameter in by editing the appropriate wIntegrate BASIC subroutine.
WIN.PARAM.xx
The various file transfer parameters are stored in the host routine WIN.PARAM.xx, where 'xx' is the machine type you used when you installed the host routines. For example, if using UniData 'U' flavor, the parameters would be in WIN.PARAM.UD.
(You can see the current machine type by looking at item MACHINE.TYPE in WIN.PROGS.)
Edit WIN.PROGS WIN.PARAM.xx using the appropriate editor for your database. Locate the following section of code: wIntegrate Troubleshooting Guide 8 September 24, 2013
* R.PARAM = '' R.PARAM = 9999999 ;* Max record size
Change the value of R.PARAM to a size that allows you to transfer your file. If, in the above example, we wish to increase the maximum record size from 10MB to 100MB, the changed line would be:
* R.PARAM = '' R.PARAM = 99999999 ;* Max record size
Save the file and be sure to compile and catalog it. Remember to make this change again whenever you upgrade the host routines.
Checksum errors
Checksum errors aren’t very frequent anymore. The most common cause of checksum errors is mismatched host routines and client versions. The version of the host routines must be the same version as the client, or later. You cannot use older host routines with later clients.
General Features
Double quotes ' " ' are converted to “?” when pasted into a wIntegrate session from Microsoft Word
Text can be copied to the Windows Clipboard then pasted into other applications, including wIntegrate. Problems can arise when copying certain characters, such as Microsoft Word’s smart quotes where regular quotes (“ “) are automatically converted into begin/end quotes (“ ”) When pasted into wIntegrate, these characters can be displayed as question marks in the terminal screen.
To disable the automatic conversion of straight quotes to smart quotes by Word, select Tools | AutoCorrect Options from the MS Word menu, then the AutoFormat As You Type tab. Uncheck the first option, "Straight quotes" with "smart quotes". This will allow the straight quotes to be pasted into a wIntegrate session correctly.
wIntegrate Troubleshooting Guide 9 September 24, 2013
Remapping characters that paste as “?”
The previous discussion addressed preventing special characters in Word from displaying as “?” by changing settings in Word. You can also create a map in wIntegrate to replace any special character that is being displayed as a “?”.
Inputmap.txt, found in \Program Files (x86)\wIntegrate, is used to map a special character to one that can be displayed. Its default contents are:
“ " Smart left quote to normal double quote ” " Smart right quote to normal double quote ™ TM Trade mark … ... Ellipses ‘ ' Single left quote to normal single quote ’ ' Single right quote to normal single quote
Use any text editor to modify inputmap.txt. The two required fields are:
Special character
After saving inputmap.txt, enable Smart Input Conversion on the Setup | Terminal dialog.
wIntegrate Troubleshooting Guide 10 September 24, 2013
When copying special characters from Microsoft Word, then pasting into UniVerse in a wIntegrate session, the characters are displayed as “^?”.
Unicode support was implemented at wIntegrate version 5.2. Beginning at that version, when you copy special characters from Microsoft Word then paste them into UniVerse running in a wIntegrate session those characters display as question marks (?) or carats and question marks (^?).
Special characters that don't display properly include the degree sign and fractions.
To resolve this, use the following PTERM setting:
PTERM ECHO NOCTRL
wIntegrate Troubleshooting Guide 11 September 24, 2013
Installation and Startup
Unable to find the wIntegrate Editor
The wIntegrate Editor is part of the Developer additions. When installing wIntegrate, select Custom Installation, then select the Developer Additions and then, “This feature, and all subdirectories, will be installed on local hard drive.”
Disabling the startup splash screen
When the wIntegrate instance is first started a splash screen is displayed. This can be disabled by changing the Target: entry in the Properties for the wIntegrate icon. By default, it will be similar to:
"C:\Program Files\wIntegrate\wInteg.exe"
Add –nobanner to the end of the string:
"C:\Program Files\wIntegrate\wInteg.exe" –nobanner
Changing the license information
License information is stored in \ProgramData\Rocket Software\wIntegrate License\LICENSE.WIL. To change only the serial number or key, you can select Start | wIntegrate Troubleshooting Guide 12 September 24, 2013
Programs | wIntegrate, then select Licensing, or simply run \Program Files (x86)\wIntegrate\wlicense.exe to display the licensing dialog. Your serial number will be displayed and the key will indicate ‘VALID’. User and organization will be grayed out. You can change the serial number and authorization key on this dialog.
Replacing the License information
If you wish to change the User Name or Organization, you must replace the license file then re-enter all of the license information. Delete \ProgramData\Rocket Software\wIntegrate License\LICENSE.WIL, and then follow the procedures described previously to enter the new license information.
wIntegrate Troubleshooting Guide 13 September 24, 2013
Legal number of users exceeded
If the first session you start determines that all available licenses for its serial number are in use, it displays a warning message asking you to inform the system administrator that insufficient licenses are deployed. The program then terminates the session.
If this message appears frequently, you will need to purchase additional licenses to accommodate the number of clients using wIntegrate.
Keyboard configuration
Changing the break key
In a standard wIntegrate installation
wIntegrate Troubleshooting Guide 14 September 24, 2013
VTxxx numeric keys don’t retain new settings
Each type of terminal emulation maps the numeric keys in a specific way. VT emulations map these keys to functions on a server running VMS. wIntegrate does the same to be consistent with the VT emulation. On non-VMS servers, the numeric keys likely won’t be compatible. Because the key mapping is done with scripts, you can easily disable the VT mapping of the numeric keys.
Select Setup | Terminal. In the Extensions dropdown box, select vtnumoff, and then save the session configuration. Vtnumoff prevents the numeric keys from being mapped as they would be with a true VT emulation.
wIntegrate Troubleshooting Guide 15 September 24, 2013
Query Builder
Query Builder Hangs
On rare occasions, customers have reported using Query Builder to transfer files to the PC, only to find it hangs at the ‘MEX F Q’ command on the PC/Mac Server, the ‘blue box’. There are, presently, 4 known causes for this behavior.
Host ignores Ctrl-B wIntegrate uses CHAR(2), a Ctrl-B, to delimit data sent to the host. If the host is ignoring CHAR(2), it doesn’t know how to handle the data it receives. If your host operating system is UNIX, even if you’re running Pick on top of it, check your stty settings to be sure CHAR(2) isn’t being ignored. Also, if you’re using UniData, check that you don’t have a CONTROLCHARS IGNORE statement in your VOC LOGIN paragraph.
PC/Mac Server doesn’t start in time
When the PC/Mac server is started, the first command it receives is ‘HOST’. This enables the server to receive commands, such as MEX F Q. Because the script which runs the server has built-in pauses, the server is normally ready to accept commands by the time the MEX F Q is sent. However, it’s possible your host takes longer to get the server process running so needs more time after the HOST command than usual before the MEX F Q can be processed.
Edit \WINTEG\WINTSYS\LIB\SERVER.WIS using a text editor. In this file are numerous occurrences of the line ‘Wait Delay 20’. For every such line, change the ‘20’ to ‘100’. If this resolves the problem, Query Builder will operate more slowly. You can test values lower than 100 to find the point at which Query Builder hangs and use the smallest one that still allows the process to work.
Mismatched host routines
Most of the host routines are machine type dependent. If you have the wrong type installed for your database, file transfers and Query Builder may not work properly. For example, if you are using UniData in its native ‘U’ flavor, but installed the host routines for UniData in ‘P’ flavor, you can expect to have problems.
To verify what version of the host routines are installed, as well as the machine type in use:
1. At the ECL/TCL prompt, type WIN.TRANSFER . You should get a response, 868ConnectOK. At this point you won’t see what you type echoed, but that’s OK. wIntegrate Troubleshooting Guide 16 September 24, 2013
2. Type 742Version. Remember, you won’t see what you type. You should see a line similar to the following:
304PVER3.0.01 10/12/96 (UD)
This line shows you the version of the host routines in use and the machine type, in parentheses. If the machine type shown is not correct for your host, you will need to re- install the host routines using the correct machine type.
Type 215END to return to the ECL/TCL prompt.
New host routines were installed tape but not cataloged
Frequently, new host routines are distributed by VARs on tape. Once loaded into WIN.PROGS, these routines need to be compiled and cataloged globally before they can be used. If you have received a tape with updated host routines, be sure to compile and catalog them.
Query Builder has two command boxes that can be used to run a TCL statement before or after the execution of the query. There are restrictions on the types of commands that may be entered. When using the PC/Process option, an invalid command will result in a "Query Import to PC failed, Invalid items" error.
'Invalid fields' error when using BEFORE or AFTER boxes in Query Builder
The Before and After boxes on the Query Builder dialog run TCL commands before and after the Query Builder command is run. If the query result is being displayed on the terminal screen, any TCL command may be entered. If the command is invalid, there will likely be an error displayed on the screen before or after the actual query runs, depending on whether Before or After is being used.
If PC/Process has been selected, and the Before or After command is invalid, a message box will be displayed:
wIntegrate Troubleshooting Guide 17 September 24, 2013
Acceptable Before and After commands
When you are directing output to the terminal screen, any valid TCL command may be used, including any query commands, paragraph's, catalogued programs, etc.
If the output is being directed to a PC file, you may only use commands in the Before box that result in a SELECT list - SELECT, SSELECT, GET.LIST, and GET-LIST. You may use any valid TCL command in the After box, however, within the context of how you are using Query Builder the command may not be relevant, for example, LIST
wIntegrate Troubleshooting Guide 18 September 24, 2013