Using HLLAPI Adapters to Migrate Legacy Programs

By migrating traditional terminal emulation programs to Host Integrator's powerful integration platform, you make them available to Web applications, mobile apps, and SOA Web services. Centralized server based solutions mean that you no longer have to install terminal emulation programs on individual desktops.

The two Host Integrator HLLAPI (High Level Language Application Program Interface) Adapters provide a simple migration path:

Host Integrator contains a .NET class library, EXTRA! COM, that is also accessible through a COM interface and provides you with the ability to migrate programs from EXTRA! Extreme 9.3. The EXTRA! COM library currently supports only 3270 terminal type sessions.
Enterprise Access Objects provide a migration path from the e-Vantage SDK, using Visual Basic, to Host Integrator.

Migrating EXTRA! Extreme Applications

By migrating EXTRA! terminal emulation applications to Host Integrator's powerful integration platform, you make them available to Web applications, mobile apps, and SOA Web services. Host Integrator contains a .NET class library, EXTRA! COM, that is also accessible through a COM interface and provides you with the ability to do just that.

The EXTRA! COM library currently supports only 3270 terminal type sessions.

How does it work?

The EXTRA! COM library is a .NET class library that contains methods and properties that closely resemble the EXTRA COM API. Your VB.NET or C# programs use the EXTRA API to make.NET to COM calls to invoke methods provided by EXTRA. Since the EXTRA! COM library does not cache, both EXTRA! COM and VHI connector calls work together seamlessly and provide a smooth transition from EXTRA to VHI.

You can migrate VB.NET, C#, or Microsoft Office Visual Basic for Applications (VBA) programs.

How to migrate EXTRA! programs

The classes, methods, and properties that comprise the EXTRA! COM HLLAPI Adapter are documented in a MSDN-style compiled help system that is included with Verastream Host Integrator.

Migrating VB.NET or C# Programs

In your .NET EXTRA program, remove the reference to the EXTRA! library, and add a reference to both the EXTRA! COM library and the .NET connector:
```
  %VHI_ROOT%\lib\dotnet\Attachmate.Verastream.HostIntegrator.E2V.dll
  %VHI_ROOT%\lib\dotnet\WRQ.Verastream.HostIntegrator.dll
```

In your code, add using directives for these classes. The type "Screen" exists in both connectors. To remedy this confusion, use an using alias directive:

 using Attachmate.Verastream.HostIntegrator.E2V;
 using Screen = Attachmate.Verastream.HostIntegrator.E2V.Screen;
 using WRQ.Verastream.HostIntegrator;

In the VHI Design Tool, create a model that connects to the same host and port as the EXTRA! program. Leave the model empty (no entities) to get started.
Deploy the model.
Change your program to call Sessions.open with the model name.
Compile and debug your code.

Migrating Microsoft Office Visual Basic for Applications (VBA) Programs

The COM interface to the EXTRA! COM library is not based on the Verastream Host Integrator COM connector. It is a .NET class library. While it is possible to use both the EXTRA! COM interface and the Host Integrator COM connector in your VBA program, these two connectors are unrelated; you cannot share sessions between the two. Microsoft Office VBA interfaces use COM; if you are not using Microsoft Office VBA, we recommend the use of .NET because it offers more flexibility.

In your Microsoft Office VBA program, remove the reference to the EXTRA! library, and add a reference to the EXTRA! COM library:

   %VHI_ROOT%\lib\dotnet\Attachmate.Verastream.HostIntegrator.E2V.tlb

2. In the VHI Design Tool, create a model that connects to the same host and port as the EXTRA! program. Leave the model empty (no entities) to get started. 3. Deploy the model. 4. Change your program to call Sessions.open with the model name. 5. Compile and debug your code.

Troubleshooting your migration

Depending on the situation, there may be additional changes that you will have to make to the EXTRA! client. The following points may be helpful in successfully migrating your EXTRA! programs to Verastream Host Integrator.

Sessions: The EXTRA! method Sessions.Open() takes a string which is a file name, typically a .EDP file. VHI cannot read the EDP file. To navigate in VHI, you create and deploy a model. The EXTRA! COM library offers two Open() methods, one that takes a string (either "model" or "model@sesssrvr"), and another that takes a HostIntegratorRejuvenationSession. When you use the HostIntegratorRejuvenationSession method you have access to all VHI features: model variables, security configuration, session pools and domains. You must add a reference to the VHI connector.
Timing: Every call is a round trip to the server, that includes simple calls such as getting the current cursor position. You may notice that the change in timing causes functional problems or causes the application to run slower than expected. Errors: There may be differences in error conditions between EXTRA! and VHI. For example, if you place the cursor in a protected area of the screen and write some text, EXTRA! may flag this error when you write the text, but VHI may flag the error when you move the cursor.
Exceptions: VHI uses different exceptions than EXTRA! and your code may not catch them all. Uncaught exceptions can cause a program to terminate.
Scaling: After migration, the EXTRA! client still creates the same number of sessions as it did prior to migration. To get the same scalability in Host Integrator, you may need to create session pools.

Migrating e-Vantage SDK Programs

The e-Vantage SDK HLLAPI Adapter is a .NET class library that contains methods and properties that closely resemble the e-Vantage SDK API. Your VB.NET or C# programs use the e-Vantage SDK API to make.NET to COM calls to invoke methods provided by e-Vantage SDK. Since the e-Vantage SDK library does not cache, both e-Vantage SDK and VHI connector calls work together seamlessly and provide a smooth transition from e-Vantage SDK programs to VHI.

You can migrate VB.NET, C#, or Microsoft Office Visual Basic for Applications (VBA) programs.

The e-Vantage SDK library currently supports only 3270 terminal type sessions.

Migrating VB.NET or C# Programs

In your .NET e-Vantage SDK program, remove the reference to the e-Vantage SDK library, and add a reference to both the EAO2V library and the .NET connector:
```
   %VHI_ROOT%\lib\dotnet\Attachmate.Verastream.HostIntegrator.EAO2V.dll
   %VHI_ROOT%\lib\dotnet\WRQ.Verastream.HostIntegrator.dll
```
2. In your code, add using directives for these classes.
```
 using Attachmate.Verastream.HostIntegrator.EAO2V;
 using WRQ.Verastream.HostIntegrator;
```
3. You do not need to deploy a model as the e-Vantage SDK adapter uses the standard model Terminal3720, which is already deployed. You can use a different model if necessary. To use a different model, In the VHI Design Tool, create a model that connects to the same host and port as the e-Vantage SDK program. Leave the model empty (no entities) to get started. Set the property AtmConTN3270.Name to a string in the form modelname@sesssrvrhostname. 4. Compile and debug your code.

Migrating Microsoft Office Visual Basic for Applications (VBA) Programs

The COM interface to the EAO2V library is not based on the Verastream Host Integrator COM connector. It is a .NET class library. While it is possible to use both the EAO2V COM interface and the Host Integrator COM connector in your VBA program, these two connectors are unrelated; you cannot share sessions between the two. Microsoft Office VBA interfaces use COM; if you are not using Microsoft Office VBA, we recommend the use of .NET because it offers more flexibility.

In your Microsoft Office VBA program, remove the reference to the e-Vantage SDK library, and add a reference to the EAO2V COM library:

%VHI_ROOT%\lib\dotnet\Attachmate.Verastream.HostIntegrator.EAO2V.tlb
You do not need to deploy a model as the e-Vantage SDK adapter uses the standard model Terminal3720, which is already deployed. You can use a different model if necessary.

To use a different model:
- In the VHI Design Tool, create a model that connects to the same host and port as the e-Vantage SDK program. Leave the model empty (no entities) to get started. Set the property AtmConTN3270.Name to a string in the form modelname@sesssrvrhostname
- Clear the properties AtmConTN3270.RemoteHostAddress and AtmConTN3270.DestinationPort in your program. If you do not clear these properties, the values will be used to set model variables "hostName" and "hostPort", respectively.
All e-Vantage SDK programs start with two assignments: assigning both the screen and connection objects to the session. Change your VBA code to use "Set" statements.
- Old:
```
   Sess.Screen = Scr
   Sess.Connection = Conn 
```
- New:
```
  Set Sess.Screen = Scr
  Set Sess.Connection = Conn Compile and debug your code. 
```
Compile and debug your code.

Troubleshooting your e-vantage SDK migration

Depending on the situation, there may be additional changes that you will have to make to the e-Vantage SDK! client. The following points may be helpful in successfully migrating your e-Vantage SDK programs to Verastream Host Integrator.

The e-Vantage SDK COM library currently supports only 3270 terminal type sessions.

Sessions: The e-Vantage SDK method AtmSession.Connect() uses the host name and port you specify. In VHI, these values are passed to the model Terminal3270. You also have the option to create and deploy a model. The EAO2V library offers two options:
- You can use the overloaded AtmSession.Connect() that takes an argument of type HostIntegratorRejuvenationSession. When you use the HostIntegratorRejuvenationSession method you have access to all VHI features: model variables, security configuration, session pools and domains.
- Or you can specify the model name in the AtmConTN3270.Name property using the form model@sesssrvr. If you use this method, you may experience connection errors. The error will be visible in the Model Debug Messages file as Error [VHI 2922] Model variable hostName does not exist in model . In this case, either clear the values of properties AtmConTN3270.RemoteHostAddress and AtmConTN3270.DestinationPort in your program, or add two model variables named hostName and hostPort to your model.
Timing: Every call is a round trip to the server, including trivial calls such as getting the current cursor position. You may notice that the change in timing causes functional problems or causes the application to run slower than expected.
Errors: There may be differences in error conditions between e-Vantage SDK and VHI. For example, if you place the cursor in a protected area of the screen and write some text, e-Vantage SDK may flag this error when you write the text, but VHI may flag the error when you move the cursor.
Exceptions: VHI uses different exceptions than e-Vantage SDK and your code may not catch them all. Uncaught exceptions can cause a program to terminate. Scaling: After migration, the e-Vantage SDK client still creates the same number of sessions as it did prior to migration. To get better scalability in Host Integrator, you may need to create session pools.
Set statement required: If you are using VBA (COM) and see this error, Object variable or With block variable not set, you must change your code to use Set statements. This is described in How to Migrate e-Vantage SDK Programs to VHI.