Defining DVPC 32bit Emulation and Attachmate Extra! HLLAPI Configurations

Document ID : KB000107159
Last Modified Date : 02/08/2018
Show Technical Document Details
Introduction:
Let’s start with what it is that we’re doing here. We’re talking about how to get reports from a mainframe repository and onto a PC. You can more easily achieve this result using CA’s cooperative processing technology, but this discussion is confined to the older method of accessing mainframe based reports from the PC that several of our larger customers still employ.
Background:
In order for you to be able to get your mainframe based reports into DocView/PC (DVPC) and onto your PC in this way, you have to be connected to the mainframe with an emulator (Attachmate Extra! for the purpose of this document) and DVPC must be able to interface with that emulator. HLLAPI (High Level Language Application Programming Interface) is the link between Extra! and DVPC. That is what this document is all about – how to configure these component applications so they can appropriately communicate with one another and transmit reports
Instructions:
.Begin in Attachmate Extra! by making note of the session name of the mainframe session which you intend that DocView will use. The name is displayed in the application title bar between the little picture of the PC and the hyphen before the application name.
Image of Extra Emulator screen

It should be noted that the Attachmate window panes are remarkably similar regardless of the version of Extra! employed.

You must now find the session file for the session name you identified above and associate it with Extra!’s hllapi and a hllapi short session name (usually a single alpha character between “A” and “E.”  Do this by clicking on Options in the menu bar and then select Global Preferences. Click the Advanced tab. Click the Short name (in this case “A”) you want to assign to this emulation session and then click the Browse button. You should now be able to find and Open the session named at the top of your primary Extra! emulation window. Please note that these session definition files have “.EDP” extensions, so if our emulation session name is 3270SES1, we need to find and Open the file named 3270ses1.EDP.
Find and Open the file named 3270ses1.EDP

It is this HLLAPI short session name  (often “A”) that will be used to coordinate which session will be used between the two products – DVPC 32bit Emulation and Extra!
 
Having Opened the 3270ses1.EDP file, the next step is save this HLLAPI short session name definition/association by clicking first on the Apply and then on the OK buttons.

save this HLLAPI short session name

You are now ready to begin the second half of the configuration process which is the process of pointing DVPC to the same HLLAPI session that you just configured and saved in Extra! You do this by Opening the DVPC 32bit Emulator and clicking on Remote from the menu bar, then on Configure Connection, and finally on HLLAPI (which should be checked).

Configure DVPC emulator

In the resulting dialogue box, you select the appropriate HLLAPI Type and enter the Session ID (aka. the HLLAPI short name) that you just defined in Extra! You should not have to change the HLLAPI DLL Filename. The correct name is shown in the example below. Click OK to save your DVPC 32bit Emulator configuration. It’s often wise to close both the Extra! And DVPC 32bit Emulators and then start them back up again. You should check to make sure the setting changes you just made have been retained

Make sure settings are retained

If they were, you should be able to click the Connect button in the DVPC 32bit Emulator and see the display mirror the mainframe session you see in the Extra! emulator. If the screens match, you are appropriately configured and you should now be able to affect your reports download. You should do this by logging into the mainframe application (usually CA-View/SAR) and marking your reports for download from the Extra! emulation session. After your reports are queued for download, you should return to the DVPC 32bit Emulator and click the download button.  

If your downloads are still failing (often it’s an E9 Mainframe communications error 6 and/or -1 ) you should continue with the rest of this document.
 
At this point, it’s time for another explanation. When the Attachmate Extra! application and its HLLAPI is installed, that install should also modify the MS-Windows environment variable, system Path. That way, when DVPC goes to look for an emulation session with which to connect, it will find a copy of HLLAPI32.DLL in the roadmap that is the Path statement, and utilize that interface to connect with the intended short session name/Extra! emulation session. If the fully qualified path to the folder which contains the appropriate HLLAPI32.DLL (e.g. C:\Program Files\EXTRA!\ ) is not in the system Path statement, it’s rather like trying to navigate to a town whose location is not shown on the map. Also, the earlier in the Path that the HLLAPI32.DLL folder is found, the more likely it is that DVPC is picking up the appropriate HLLAPI.
  
When you need to check whether the system Path to your HLLAPI is appropriately defined, you can do so by clicking your Start button, then onto Search, and then click For Files or Folders. You want to Look in My Computer for HLLAPI32.DLL with Advanced Options to Search system folders, Search hidden files and folders and Search subfolders. 

Check system path  
 
You may well find multiple HLLAPI32.DLL files, especially if Extra! was installed multiple times, upgraded or backed up. The key to having DVPC start the correct HLLAPI in such cases to include the “In Folder” location (as above) that specifies the same location as does the Windows shortcut you use to start the Extra! emulator.
 
Next comes the tricky part. Once you’ve established location you need to include in your MS-Windows environment variable, system Path, you must very carefully insert that location by editing the variable and inserting the path into a small and not very friendly window.    
 
Right click on My Computer from your Desktop or Start Menu, and then select Properties. Click the Advanced tab. Now click the Environment Variables button.
User-added image

Next you will need to select from the Environment Variables Panel, the Path variable from the bottom or System variables pane by clicking it. Now click the Edit button and you will get the very small Edit System Variable window for the Variable name, Path. You may edit the Variable value by clicking in white area above the buttons. You are now editing at your cursor location. Control your cursor in the window with your right and left arrow keys to move the cursor one character at a time and your Home and End keys to send the cursor to the very beginning or end of the Variable Value string. If the folder location of your Extra! HLLAPI32.DLL is missing from, or too far back in your System Variable/Path, you will have to insert or move it.
 
For example, if your Path begins something like:
C:\Program_Files\CA\SharedComponents\pec\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\CA_APPSW;C:\PROGRA~1\CA\SHARED~1\CAM\bin;C:\CA_AP...
 
You want to change it to be more like:
 
C:\Program_Files\CA\SharedComponents\pec\bin;C:\Program_Files\Extra!\;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\CA_APPSW;C:\PROGRA~1\CA\SHARED~1\CAM\bin;C:\CA_AP...
 
Please note that the semicolon (;) is the delimiter used to separate the different folder locations specified in the Path statement. Also, cut, copy and paste will function when editing the Variable Value string.
 
Though usually not necessary, rebooting the PC will insure that the change to the path is picked up the next time you attempt to access the Attachmate Extra! emulation session through HLLAPI from DVPC.
 
The preceding constitutes a solution to 95+% of the issues raised with E9 or E15 DVPC errors where Attachmate Extra! is the emulator being used. In those few remaining cases, the recommendation is to remove the Attachmate Extra! application, reboot, then install Extra! anew while making sure that the Extra! 32bit HLLAPI is a part of that install.  If DVPC is also reinstalled,  perform the DVPC reinstall only after the Extra! reinstall is completed.