Compaq BASIC Translator
User Manual
Previous Contents Index

1.3 The Translation Process

This section summarizes and discusses the inputs used in a translation and the outputs produced.

1.3.1 Translator Inputs

The Translator needs the following inputs:

VAX BASIC or DEC BASIC source code
DECBAS_ support routine library

VAX BASIC or DEC BASIC Source Code

This is the original source code that you plan to port to the Windows NT or Windows 95 platform from the OpenVMS platform.

DECBAS_ Support Routine Library

The DECBAS_ support routines, which handle differences between VAX BASIC or DEC BASIC and Visual Basic, are shipped in a library file
(DB2VB$LIBRARY.TLB), which is copied to SYS$LIBRARY when the Translator is installed. When a DECBAS_ support routine is referenced, the containing module is pulled from the text library into the same directory as the generated Visual Basic project. This module is in the form of a .BAS file prefixed with DBRTL. See Section 1.3.2 for more information on the support routines.

1.3.2 Translator Outputs

The Translator produces the following:

Visual Program Directory File
Translated source code in Visual Basic
Global definitions file
DECBAS_ support routine modules
COMMON, MAP, RECORD, and GROUP classes
Visual Basic Project File

Visual Program Directory File

The Visual Program Directory (.VPD) file lists the names of all files generated by the Translator. The purpose of the file is to make it easy to write an automated procedure to move the translated application to your Windows platform.

Translated Source Code

This consists of translations of VAX BASIC or DEC BASIC statements and routines into Visual Basic statements and routines. (See Chapter 7 for an alphabetic reference section of statements and routines.)

Global Definitions File

For each translated project, the Translator produces a global definitions file, named with a _GBLS.VB suffix. This file contains items such as constant definitions, declarations of external routines, and declarations for RECORD, MAP, and COMMON statements.

Support Routines

The Translator provides a set of DECBAS_ support routines written in Visual Basic for many VAX BASIC or DEC BASIC elements that do not have an exact corresponding native equivalent language construct in Visual Basic. In many cases, they implement a VAX BASIC or DEC BASIC feature that is similar to, but not exactly the equivalent of, a feature in Visual Basic.

These routines, in the form of files with the DBRTL prefix and the .BAS file type, are extracted by the Translator from the DB2VB$LIBRARY.TLB library file in SYS$LIBRARY and put into the user's directory.

Common, Map, Record, and Group Classes

The Translator converts COMMON and MAP statements and records into Visual Basic common, map, record, and group classes. These are critical program-generated files that should generally not be modified.

Visual Basic Project File

Along with the translated code and support routines, the Translator generates a Visual Basic Project file (.VBP) that contains the information necessary to load the project and expedites bringing the translated application into the Visual Basic Integrated Development Environment (IDE). The file pulls together the following items necessary for migration:

1.3.3 Run-Time Libraries

Because of language and operating system differences in areas such as file I/O, string and array handling, and the display environment (character cell to Windows, for example), emulation of these VAX BASIC or DEC BASIC features is done by run-time libraries. These .DLL run-time libraries are installed (as a single run-time kit) on each Windows system running a translated program. The actual use of these libraries is contained within the DECBAS_ support routines, and you do not need to access them directly.

See Appendix B for more information on the run-time libraries.

See Table 3-8 in Chapter 3 for an alphabetized summary of translated elements of the VAX BASIC or DEC BASIC language. <recto_head>(cancel_h) <verso_head>(cancel_h)

Chapter 2
Using the Translator

This chapter describes how to invoke the Translator on an OpenVMS VAX or OpenVMS Alpha platform, how to transfer translated applications to a Windows system, and how to avoid some problems associated with multimodule applications. Other hints for translating and running applications are also listed.

2.1 Invoking the Translator

To invoke the Translator, use the DCL command BASIC/TRANSLATE. With this command, you can specify command qualifiers. This section discusses the BASIC/TRANSLATE command in detail as well as the command qualifiers available.

2.1.1 BASIC/TRANSLATE Command

When you translate your source program, use the BASIC/TRANSLATE command, which has the following format:

BASIC/TRANSLATE [/qualifier...] file specification [/qualifier...]],...

file specification

Indicates the directory, file name, and file type for each input source file of the program or module to be translated. You are not required to specify a file type; the Translator assumes the default file type .BAS.

/qualifier

Indicates a specific action to be performed by the Translator on all files or specific files listed. See Section 2.1.2 for a table of qualifiers and the level of support available for each.

Global Qualifiers

Most of the command qualifiers (all but three; see Positional Qualifiers) to the BASIC/TRANSLATE command affect all files specified in the command line, no matter where the qualifiers are placed. These command qualifiers are called global qualifiers.

If two qualifiers conflict, the rightmost qualifier overrides the other.

Positional Qualifiers

The BASIC/TRANSLATE command has three positional qualifiers1:

Depending on their position in the command line, positional qualifiers affect all or only some of the specified files. The rules for positional qualifiers are as follows:

The placement of the positional qualifiers causes the Translator to produce or not produce diagnostics, listing, and output files. For example: 


$ BASIC/TRANSLATE/LIST/OUT PROG1/NOOUT/DIAG,PROG2+PROG3/NOLIST

This example accomplishes the following:

BASIC/TRANSLATE does not require line numbers in any of the source files. The plus operator (+) is treated as an OpenVMS append operator. The Translator appends and translates the separate files as if they were a single source file. For the typical large existing application, it is usually preferable to use commas instead of plus operators. See Section 2.4.

2.1.1.1 Use of /ID_CHARACTER and /ID_SUFFIX Characters to Control Spelling

Two qualifiers, /ID_CHARACTER and /ID_SUFFIX, control spelling in translations of identifiers that contain special characters unsupported by Visual Basic or that have suffixes disregarded by Visual Basic.

Background and Default Behavior

VAX BASIC or DEC BASIC allows the use of the period (.) and the dollar sign ($) as characters in identifiers, but Visual Basic does not. Hence by default, to provide legal, unique identifiers in the translated output, the Translator replaces these characters with three underscores (___) and two underscores (__), respectively.

VAX BASIC or DEC BASIC treats identifiers with the suffixes dollar sign ($) and percent sign (%) as unique, whereas Visual Basic does not. (Visual Basic, for example, would treat X and X$ as the same identifier.) Hence the Translator by default translates these suffixes to underscore dollar sign (_$) and underscore underscore percent sign (__%), respectively.

The Translator issues an informational message for each instance of a substitution, sometimes resulting in an excessive number of informational messages. You can suppress these messages with the /NOWARN=INFO qualifier. The problem that remains is that the translated program may be cluttered with underscores.

To avoid this situation, use the /ID_CHARACTER and /ID_SUFFIX qualifiers to control the translation of the appropriate characters in identifiers.

Format and Description of the /ID_CHARACTER and /ID_SUFFIX Qualifiers

The qualifiers have the following format: 


/ID_CHARACTER = (DOLLAR_SIGN=string1,        Default:  "__" 
                 PERIOD=string2)             Default:  "___" 
 
/ID_SUFFIX = (DOLLAR_SIGN=string3,           Default:  "_$" 
              PERCENT_SIGN=string4)          Default:  "__%"

Where string1, string2, string3, string4 can be any character strings, including an empty string (specified by two quotes with no space), or the same as another one of the strings. The strings need only be enclosed in quotes (") if they contain special characters. If a quote character is desired within a replacement string, it must be doubled.

For example:

Input source: 


X.inches% = Y$INCH (56) + 2

Command line: 


$ BASIC/TRANSLATE/NOWARN=INFO - 
        /ID_CHAR=(DOLLAR="", PERIOD="_") - 
        /ID_SUFF=PERCENT="%" - 
                SOURCE.BAS

Resulting translated output: 


X_inches% = YINCH (56) + 2

Resulting translated output without the /ID_CHARACTER and /ID_SUFFIX qualifiers: 


X___inches__% = Y__INCH (56) + 2

In the example, the % suffix of the original is specified also to be % in the translated output. This makes sense when there is no problem of uniqueness; in this case, if the user knows that there is no identifier named either X.inches or X_inches in the source program.

If the /ID_CHARACTER and /ID_SUFFIX qualifiers are used, the Translator does not issue informational messages for the substitutions.

The maximum length of a replacement string is 30 characters. If it exceeds 30 characters, the following warning message is issued:

%DB2VB-W-QUASTRTOOLON, The /ID_xxx=yyy qualifier value is too long and is truncated

Where xxx is either CHARACTER or SUFFIX; and yyy is either PERIOD, DOLLAR_SIGN, or PERCENT_SIGN.

If a respelled name could possibly exceed Visual Basic's maximum identifier length, the following warning message is issued:

%DB2VB-W-VBNAMTOOLON, Length of respelled name exceeds Visual Basic's limit and is truncated

This message is issued whenever the respelling of a name is longer than 256 characters, which is Visual Basic's limit for most names.

It is suggested that short replacement strings be used, and that they not contain special characters other than the underscore (_). Note that Visual Basic uses the at sign (@), ampersand (&), exclamation point (!), and pound sign (#) as data type suffixes, so these should be avoided. Finally, of course, be sure to avoid the period (.) and the dollar sign ($) as values for the /ID_CHARACTER qualifier, as these characters are not allowed by Visual Basic.

Suggested Use of /OUTPUT for File Naming

The translated output file is by default named with a .VB file type, to identify it as a Visual Basic program and to differentiate it from the VAX BASIC or DEC BASIC source, which usually has the .BAS file type. This renaming of the file type prevents confusion and guards against loss of the original source file by inadvertent purging.

The Windows system expects a Visual Basic file to be named with .BAS, not .VB. Hence it is necessary to rename the .VB files to .BAS before or after transferring them to the PC. A convenient way to avoid this task is to specify on the Translator command line that the output file should both:

Note
The directory must be different if you are to specify .BAS, to safeguard your source files.

For example: 


$ BASIC/TRANSLATE/OUT=[different-directory].BAS PROG1

This command translates the VAX BASIC or DEC BASIC program file PROG1.BAS and produces a Visual Basic program in a file also named PROG1.BAS, which is put into a different directory that you specify.

Using /OUTPUT to specify the directory and the .BAS file type also produces *_GBLS.BAS files, which are placed (along with all the secondary files) into the new output directory.

If you will be using the Windows Explorer to transfer your files to the Windows system, your file transfer mechanism may have the "eight-dot-three" limitation on file-name length and an eight-character limit on a directory name. If so, you can specify a short directory name and a shortened file name if necessary with /OUTPUT. See Section 2.2.3.

2.1.2 Translator Command Qualifiers

Table 2-1 shows the BASIC command qualifiers and the Translator's level of support for each.

Table 2-1 Command Qualifiers and Support Levels
Command Qualifier Level of Support
/ANALYSIS_DATA Not supported.

Message: DB2VB-I-QUALNOTSUP, The /ANALYSIS_DATA qualifier is not supported

/ANSI_STANDARD Not supported.

Message: DB2VB-I-QUALNOTSUP, The /ANSI_STANDARD qualifier is not supported

/AUDIT Not supported.

Message: DB2VB-I-QUALNOTSUP, The /AUDIT qualifier is not supported

/CHECK Not supported.

Message: DB2VB-I-QUALNOTSUP, The /CHECK qualifier is not supported

/CROSS_REFERENCE Not supported.

Message: DB2VB-I-QUALNOTSUP, The /CROSS_REFERENCE qualifier is not supported

/DEBUG Not supported.

Message: DB2VB-I-QUALNOTSUP, The /DEBUG qualifier is not supported

/DECIMAL_SIZE Not supported.

Message: DB2VB-I-QUALNOTSUP, The /DECIMAL_SIZE qualifier is not supported

/DEPENDENCY_DATA Not supported.

Message: DB2VB-I-QUALNOTSUP, The /DEPENDENCY_DATA qualifier is not supported

/DESIGN Not supported.

Message. DB2VB-I-QUALNOTSUP, The /DESIGN qualifier is not supported

/DIAGNOSTICS Supported by the Translator to the same level as VAX BASIC or DEC BASIC support for this qualifier.
/DOUBLE 3 Obsolete. Supported by the Translator to the same level as VAX BASIC or DEC BASIC support for this qualifier. Sets default data type for real variables. See Chapter 4.
/FLAG Not supported.

Message: DB2VB-I-QUALNOTSUP, The /FLAG qualifier is not supported

/INTEGER_SIZE Supported by the Translator to the same level as VAX BASIC or DEC BASIC support for this qualifier. Sets default data type for integer variables. See Chapter 4.
/ID_CHARACTER Supported by the Translator; not in VAX BASIC or DEC BASIC. See the section on /ID_CHARACTER and /ID_SUFFIX in this chapter.
/ID_SUFFIX Supported by the Translator; not in VAX BASIC or DEC BASIC. See the section on /ID_CHARACTER and /ID_SUFFIX in this chapter.
/LINES Not supported.

Message: DB2VB-I-QUALNOTSUP, The /LINE qualifier is not supported

/LISTING Supported by the Translator to the same level as VAX BASIC or DEC BASIC support for this qualifier.
/LONG 3 Obsolete. Supported by the Translator to the same level as VAX BASIC and DEC BASIC support for this qualifier. Sets default data type for integer variables. See Chapter 4.
/MACHINE_CODE Not supported.

Message: DB2VB-I-QUALNOTSUP, The /MACHINE_CODE qualifier is not supported

/OBJECT Not supported. See /OUTPUT, which is similar.

Message: DB2VB-I-QUALNOTSUP, The /OBJECT qualifier is not supported

/OLD_VERSION Not supported.

Message: DB2VB-I-QUALNOTSUP, The /OLD_VERSION qualifier is not supported

/OPTIMIZE Not supported.

Message: DB2VB-I-QUALNOTSUP, The /OPTIMIZE qualifier is not supported

/OUTPUT Similar to the /OBJECT qualifier in VAX BASIC or DEC BASIC. /OUTPUT= file specification produces an output file with an explicit file specification. Omitting file specification causes the compiler to produce an output file having the same name as its corresponding source file and file type .VB. The secondary files (.VPD, .VBP, .CLS, _GBLS.VB, DBRTL*.BAS) produced by the Translator will be placed in the same directory as the output file. If you specify a different directory for output files, and specify the .BAS file type, both the main output program file and the _GBLS file will have the .BAS file type. See Suggested Use of /OUTPUT for File Naming in this chapter.
/REAL_SIZE Supported by the Translator to the same level as VAX BASIC or DEC BASIC support for this qualifier. Sets default data type for real variables. See Chapter 4.
/ROUND_DECIMAL Not supported.

Message: DB2VB-I-QUALNOTSUP, The
/ROUND_DECIMAL qualifier is not supported

/SCALE Not supported.

Message: DB2VB-I-QUALNOTSUP, The /SCALE qualifier is not supported

/SEPARATE_COMPILATION 1 Not supported.

Message: DB2VB-I-QUALNOTSUP, The /SEPARATE_COMPILATION qualifier is not supported

/SHOW The values [NO]CDD_DEFINITIONS and [NO]MAP are not supported. All other values are supported by the Translator to the same level as VAX BASIC or DEC BASIC support for this qualifier.
/SINGLE 3 Obsolete. Supported by the Translator to the same level as VAX BASIC and DEC BASIC support for this qualifier. Sets default data type for real variables. See Chapter 4.
/SYNCHRONOUS_EXCEPTIONS 1 Not supported.

Message: DB2VB-I-QUALNOTSUP, The
/SYNCHRONOUS_EXCEPTIONS qualifier is not supported.

/SYNTAX_CHECK 2 Not supported.

Message: DB2VB-I-QUALNOTSUP, The /SYNTAX_CHECK qualifier is not supported

/TIE 1 Not supported.

Message: DB2VB-I-QUALNOTSUP, The /TIE qualifier is not supported

/TYPE_DEFAULT Supported by the Translator to the same level as VAX BASIC or DEC BASIC support for this qualifier. Sets default data type for variables. See Chapter 4.
/VARIANT Supported by the Translator to the same level as VAX BASIC or DEC BASIC support for this qualifier.
/WARNINGS Supported by the Translator to the same level as VAX BASIC or DEC BASIC support for this qualifier.
/WORD 3 Obsolete. Supported by the Translator to the same level as VAX BASIC and DEC BASIC support for this qualifier. Sets default data type for integer variables. See Chapter 4.

1Alpha platform only (DEC BASIC)
2VAX platform only (VAX BASIC)
3The /SINGLE, /DOUBLE, /WORD, and /LONG qualifiers are supported for compatibility with previous versions of VAX BASIC or DEC BASIC. However, Compaq recommends that you use the /TYPE_DEFAULT, /INTEGER_SIZE, and /REAL_SIZE qualifiers to set the default data type and size.

Note

1 /TRANSLATE itself is positional in that it must immediately follow BASIC, but BASIC/TRANSLATE as a unit is regarded as the command name.

Previous Next Contents Index