Previous | Contents | Index |
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
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.
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.)
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.
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.
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:
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)
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.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.
The BASIC/TRANSLATE command has three positional qualifiers1:
- /DIAGNOSTICS
- /LISTING
- /OUTPUT
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:
- If the positional qualifier is located directly following the command name, it affects all the specified files.
- If the file specifications are separated by commas, then any positional qualifier directly following a file specification affects only that file.
- The rightmost qualifier overrides any conflicting qualifier previously specified in the command line.
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:
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.
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
|
/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
|
/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. |
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 |