Whereas the BASIC compiler encountering a syntax error would emit an error message and continue to process the rest of the file for errors, the Translator may issue a "Can't continue" message and exit.

The Translator is designed to translate working DEC BASIC and VAX BASIC programs to Visual Basic. It is a migration tool, not a development tool. Therefore, the parser has been simplified somewhat, and it does not recover from severe syntax errors. It is intended only to translate programs that are acceptable to the BASIC compiler.

2.2 Transferring Translated Applications

Once a VAX BASIC or DEC BASIC application has been translated, it must be transferred from the OpenVMS system to a Windows system. You can use one of the following for the transfer:

• FTP
• A supplied Visual Basic Add-In
• Windows Explorer
• Command procedures

This section describes various unsupported ways to transfer the application.

2.2.1 Transferring Files with the FTP Utility

You can use FTP if TCP/IP is running on both the OpenVMS machine and your target Windows system. FTP is the recommended method, as it is generally the easiest and simplest way to copy the Translator-generated files. It avoids the use of a network mapped drive.

First prepare a Windows local directory for the project. Then invoke the FTP utility from the MS-DOS prompt by typing FTP. At this point you can request further FTP help. Follow these steps to complete the transfer:

1. Create a connection using OPEN openvms_node_name.
2. Log in, supplying user name and password as needed.
3. Set Image mode using the BINARY command. This is optional, but helps to ensure that all the bits get copied.
4. Set your default directory, using the CD command, to that of the generated files.
5. Copy the files over to the prepared local directory using either the GET or MGET command.
6. Close the connection using the CLOSE command.
7. Exit FTP using the BYE command.

A .ZIP file named DB2VBADD.ZIP can be found on your run-time library (RTL) media, in the Tools folder. The .ZIP file includes an installation kit for installing a Visual Basic Add-In called the DB2VB Project Add-In. This Add-In uses the .VPD file generated by the Translator during translation to help automate the process of bringing translated VAX BASIC and DEC BASIC applications into the Visual Basic environment. It has the following features:

• Automatically copies all Translator output files, eliminating the possibility of missing files
• Automatically renames files if necessary (that is, each occurrence of the .VB file type is changed to .BAS, which the Windows system expects)
• Avoids the use of network copy utilities
• Handles long file names if the FTP option is selected
• Allows easy merging of multiple projects into a single project
• Allows for the ad hoc addition of single files into the current project from across the network

This section describes how to install and use the DB2VB Add-In.

2.2.2.1 Installing the Add-In

The DB2VB Project Add-In must be decompressed and installed before it can be used. Complete the following steps to install the kit:

1. Copy the DB2VBADD.ZIP file to an empty directory on the Windows system where you intend to install it.
2. Unzip the archive file using an Unzip utility. During the unzip process, files are created in your current directory.
3. Run the SETUP.EXE file that was created during the unzip process.
4. Follow the instructions shown on the screen.
5. After SETUP.EXE has completed, run the newly added file DB2VB.EXE located in the system directory under your windows directory. This file runs for only a second.
6. At this point, the DB2VB Add-In is installed on your system and appears within the Visual Basic Add-In Manager.

Once the DB2VB Project Add-In is installed on your system, you must tell Visual Basic that you want to use it. Go into the Visual Basic Add-In Manager and click on the DB2VB Project Add-In box. When you exit the Add-In Manager, Visual Basic adds the new Add-In to the bottom of the Add-Ins menu.

When you want to remove it from the Add-Ins menu, go into the Add-In Manager and deselect the DB2VB Add-In.

2.2.2.3 Using the Add-In

To use the DB2VB Project Add-In, first go to the Add-Ins menu and select DB2VB Project Include.... This brings up a form from which you can include different projects in various ways.

The form is divided into a left side, from which you select items, and a right side, which you use to specify where the selection is going.

First you specify how you want to access the translated files on the remote OpenVMS machine. Click on the Options menu, then the Network Options menu item, which causes an options box to pop up. In the options box, there are two ways to access your translated files: Network Mapped Disk and FTP. If your OpenVMS system supports FTP access, Compaq recommends that you select this option, filling in all the information required. (Note that the use of proxies is not currently provided.) FTP handles long file names and is usually faster. If you select Network Mapped Disk, then no other information is needed.

Accessing Files with FTP

When you exit the options box, the Windows system attempts an FTP connection to the OpenVMS system using the information that you supplied. If the attempt is successful, a directory tree based on your login directory is built. The disk is shown in the top left box (the disk box), while the directories are displayed in the leftmost box (the directory tree box) just below the disk box. To the right of the directory box is the file list box, which displays the current directory files that match the criteria specified in the selection box below the file list box. The files listed in the selection box default to *.VPD files, which the Translator generates for each translated application. The .VPD file contains a list of the files that make up the translated project.

If you want to search the current directory tree, click on the directory where you would like to go. If you would like to specify a completely different directory tree, such as a project area, you can specify the root of this tree in the disk box. To do this, click on the disk box, delete what is there, and specify the complete OpenVMS directory specification for the new directory root (for example, MYDISK$:[PROJECT1]), then press Return. A new directory tree is built based on this new root.

Once you have found the files or projects that you want to add, select them by using either of the following procedures:

• Double click on the file or project name.
• Highlight the file or project name, then click on the right arrow button.

The file name now appears on the right-hand side of the form. If you do not wish to add it, remove it by using one of the following procedures:

• Double click on the file name within the right-hand side box.
• Highlight the file name within the right-hand side box, then click on the left arrow button.

Before you can add a translated project from across the network, you must specify a local directory for the project and files. This is where all of the files are copied and is considered the project directory. You can specify this by either writing directly into the Local Directory box, or by pressing the ... button and searching for an existing local directory. After you select the files and define a local directory, click on either Apply or OK to begin the project inclusion.

If single source files are selected, they are included in the current project. However, including a project or .VPD file creates a new Visual Basic project by default. You can modify this behavior by checking "Include files(s) into current project." This forces all of the included project's source files to be copied and loaded into the current project. This feature allows you to easily merge multiple translated projects.

Accessing Files with Network Mapped Disk

Using a Network Mapped Disk is exactly like using the FTP method previously described, with these exceptions:

• Disks that are currently mounted on your Windows system are the only ones that can be listed in the disk box. If you mapped a disk after you opened the DB2VB Add-In window, then you must close the DB2VB Add-In window and reopen it to see the newly mapped disk. Disks can be mapped using the Windows Explorer or other tools.
• To navigate through the directory tree box, you must double click on the directory names. There may be a delay, without any busy indicator, before the new directory becomes the current directory.

This section describes how to transfer the translated Visual Basic application with Windows Explorer.

For example, if you have a VAX BASIC or DEC BASIC source file named TFF01.BAS residing in an OpenVMS directory, the following files are present in your directory after you run the Translator:

TFF01.BAS	Original source
TFF01.VB	Translated source
TFF01_GBLS.VB	Global definition file
TFF01.VBP	Visual Basic project file
TFF01.VPD	Program directory file
DBRTLEXC.BAS	File containing support routines
DBRTLIO.BAS	File containing support routines
DBRTLWRP.BAS	File containing support routines

So that they do not conflict with the .BAS file type, the translated Visual Basic source and the associated global definition file are given the .VB file type (unless you specified /OUTPUT with the .BAS file type instead of .VB. See Suggested Use of /OUTPUT for File Naming in this chapter). First you must rename some files to have the correct .BAS extension and the correct names that they need on the Windows system. You can rename the files either on OpenVMS or after transferring them to the Windows system. You may prefer to rename the files on the OpenVMS system, because you can also shorten the file names if necessary to fit the "eight-dot-three" limitations that your file transfer mechanism may have. In the following example the files are renamed on the OpenVMS system.

First, rename the VAX BASIC or DEC BASIC source to make the .BAS file type available:

$ RENAME/LOG TFF01.BAS TFF01.DB

Then, rename the translated Visual Basic source to the .BAS file type. If the file name exceeds eight characters, temporarily shorten the file name if necessary for copying purposes. In this example, there is no need to shorten the name:

$ RENAME/LOG TFF01.VB TFF01.BAS

The global definition file must also be renamed to have the .BAS file type. In the following example, because the file name does exceed eight characters, it must be shortened. Later, after transferring the file to the Windows system, you must restore the original file name (while maintaining the .BAS file type on Windows).

$ RENAME/LOG TFF01_GBLS.VB GBLS.BAS

Set the directory and file protections so that the files can be copied onto Windows. On the Windows system, use Explorer to transfer the files.

Using Windows Explorer, create a new folder to contain the Visual Basic project. For this example, name it Tff01. There are several methods that can be used to transfer the files; in this example we use a mapped network drive (your network must already be set up at both ends to support this). In Windows Explorer, select the Tools menu and click on the Map Network Drive item, pick an available drive letter, and specify the system and account that you want to access (for example, \\node\username).

Once the connection is established, you can access the remote OpenVMS drive and directories using Windows Explorer just like any local Windows drive. The eight-character limit might affect the directory name on your particular system; if the directory cannot be found, check the length of its name. Once you have located the desired OpenVMS directory, click on it, and the names of the project files appear in the right window. In this example, you see all of the file names previously listed.

Select all of the file names, select the Edit menu item, and click on Copy. In the left Explorer window, click on the local Windows destination directory Tff01, and select the Edit menu item and click on Paste. The files should all be copied onto your local Windows destination disk and directory.

Now you can disconnect your network drive if you wish, using the Disconnect Network Drive item in the Tools menu. On the local directory, rename any files whose original names must be restored. In our example, we have to rename the GBLS.BAS file to TFF01_GBLS.BAS. Using the right mouse button, click on the GBLS.BAS name, select Rename from the Pop--Up menu, and type in the new name where the old name appears in the window. If you renamed the translated Visual Basic .BAS file for file name length considerations, you must rename that file to its original name.

2.2.4 Removing Nonprintable Characters That Prevent Execution

After transferring your translated project files from the OpenVMS system to the Windows system, you may notice a line at the very end of the translated file containing some nonprintable characters, usually Ctrl/Zs. The nonprintable characters are an undesirable byproduct of the network file transfer. Visual Basic does not accept these trailing characters and does not allow the program to execute until you delete them. After you delete them, the program will execute properly. Also see Section 2.2.5.

2.2.5 Transferring Files with a Command Procedure

The Translator kit contains an unsupported DCL command procedure named ZIPVPD.COM, which can be used to package and transfer the files that are output by the Translator to the Visual Basic system. The command procedure avoids the trailing Ctrl/Z problem, the long names problem, and the .VB file type problem. It uses the .VPD file to pack all the required files into a .ZIP file, which you can then copy to the target Visual Basic system, and then unpack with an Unzip utility.

2.3 Loading the Project into Visual Basic

To load the project into Visual Basic, either double click on the file name of the .VPD file in the Explorer window, or explicitly start up Visual Basic and open the project from the Open Project item in the File menu.

2.4 Translating Multimodule BASIC Applications

The typical BASIC application consists of more than one module, file, or routine. On an OpenVMS system, the VAX BASIC or DEC BASIC compiler and the OpenVMS Linker perform a number of operations to fit together various modules, reconcile problems of consistency and duplication, and so forth. The Translator, working with and producing only BASIC source code, cannot perform these compiling and linking operations.

The Translator handles each program module separately, and does limited cross-module consistency checking. (See Section 4.2.6.) The resulting Visual Basic program modules might contain incompatibilities. Multiple definition errors are likely in projects with multiple routines and modules. If names are used consistently in declarations throughout the modules and routines, the duplicate definitions can be deleted. If names are not used consistently, then definitions and possibly sections of code must be identified and renamed.

This section explains the preferred command line for translating multimodule applications, and goes on to discuss how you can resolve problems in the following four areas:

• MAP statements
• COMMON statements
• %INCLUDE files
• Nonunique names

The BASIC/TRANSLATE command syntax provides three primary methods to translate a BASIC application consisting of more than one module. The following examples show commands for a BASIC application with three modules named MOD_A, MOD_B, and MOD_C:

Method 1

$ BASIC/TRANSLATE MOD_A, MOD_B, MOD_C

Method 2

$ BASIC/TRANSLATE MOD_A + MOD_B + MOD_C

Method 3

$ BASIC/TRANSLATE MOD_A $ BASIC/TRANSLATE MOD_B $ BASIC/TRANSLATE MOD_C

Method 1 is recommended for translating a multimodule BASIC application. Method 1 has the following major advantages:

• Method 1 (using commas) generates a single Visual Basic .VBP project file containing the correct references to all of the modules in your project. The other two methods would generate multiple .VBP project files, which you would have to merge painstakingly into a single .VBP file, in what would be at best an error-prone process.
• Method 1 generates a single _GBLS.VB globals file (in this case, named MOD_A_GBLS.VB) containing all the project's global declarations, notably including the variable declarations for the translated MAP buffers from each module. The other two methods would generate multiple globals files that would have to be merged by hand.
• Method 1 recognizes repeated definitions of the same RECORD types and PSECT fields (MAP and COMMON declarations) and does not generate duplicate files for them.
• Method 1 provides for the potential future capability of the Translator to optimize certain module interactions.

Duplicate definitions are likely as a result of %INCLUDE files, causing Visual Basic errors. If your program is structured so that it uses %INCLUDE files to provide common declarations for a number of routines, the Translator processes these multiple definitions, once for each %INCLUDE. Some of these extra definitions survive into the output files and must be manually removed. One approach to reduce the labor involved is to gather together the %INCLUDE files so that duplicates will be easy to find, before translation, and comment out the %INCLUDE files within the routines. Translate the program with the different %INCLUDE files catenated to the beginning, and the identical ones eliminated. For example:

BASIC/TRANSLATE include_file1+include_file2+main_program

A variation is to remove only the identical %INCLUDEs within the routines, leaving them in only the main program. Then translate the program as usual.

As of Version 1.2, the Translator recognizes the duplication of RECORD structures and of PSECT variables (PSECT variables are generated by MAP and COMMON declarations) and reuses the first. See Section 4.2.6.

2.4.3 MAP and COMMON Statements

Both MAP and COMMON statements in VAX BASIC and DEC BASIC specify naming of segments of storage in a PSECT that is shared between modules of a program. The Translator implements this commonality via a Visual Basic Class. The Translator recognizes multiple definitions of the same PSECT and shares or renames elements as needed. For example, consider two routines defining the same common block, each using one of the following lines:

COMMON (ABC) LONG D, LONG E, LONG F

COMMON (ABC) LONG F, LONG E, LONG D

Then, in the second module, E would be shared, but F and D would be renamed as F_1 and D_1, respectively, so that the Translator can emit just one class file for the PSECT that has the interface necessary to implement the correct overlaying of shared storage. F_1 would be synonymous with D, and D_1 would be synonymous with F.

The Translator generates for each MAP or COMMON a Visual Basic class that simulates the storage of the variables in a PSECT shared among the modules. See Section 4.2.6 for more information.

2.4.4 Names

Names in your program that happen to be the same as Visual Basic names that will occur in the translated program (for example, name of a function, object, or property) will cause a Visual Basic error when the application is run. Similarly, naming your application file with a name that is the same as a Visual Basic name causes a Visual Basic error when your application is run. Check for nonunique names, and be sure to use names that do not conflict with names in Visual Basic.

The Translator will give an error message during translation for some of the names, but the Translator does not have a complete dictionary of Visual Basic reserved words, so some of these will have to be detected when the project is loaded into Visual Basic.