Order Number: AA--R5WVC--TE

This manual describes the Compaq BASIC Translator (formerly known as the DIGITAL BASIC Translator), which is used to translate VAX BASIC and DEC BASIC programs to Visual Basic programs.

Revision/Update Information: This revised manual supersedes the DIGITAL BASIC Translator User Manual, Version 1.1.

Operating System and Version: OpenVMS VAX Version 6.2 through 7.2 or OpenVMS Alpha Version 6.2 through 7.2

Software Version: Compaq BASIC Translator Version 1.2

Compatible Systems: Microsoft Windows NT Versions 3.5
and 4.0
Microsoft Windows 95 and Windows 98

Compatible Software: Visual Basic Version 6.0
VAX BASIC Versions 3.8 and higher
DEC BASIC Versions 1.2 and higher <COMPANY_INFO>(Compaq Computer Corporation\Houston, Texas)

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor.

Copyright ©1998, 1999

Compaq and the Compaq logo are registered in the United States Patent and Trademark Office. <trademark_para>(intro\Alpha, DEC, DEC BASIC, DECforms, DIGITAL, OpenVMS, VAX, VAX BASIC, VAX DOCUMENT, VAX RMS, VMS, VT, VT100, and the DIGITAL logo.)

The following are third party trademarks:

BASIC is a registered trademark of the Trustees of Dartmouth College, (Dartmouth Structured Basic) D.B.A. Dartmouth College.

IEEE is a registered trademark of The Institute of Electrical and Electronics Engineers, Inc.

Intel is a registered trademark of Intel Corporation.

Microsoft, MS-DOS, WIN32, Windows, and Windows NT are registered trademarks and MICROSOFT WINDOWS NT, NT, Visual Basic, and Windows 95 are trademarks of Microsoft Corporation.

Motif is a registered trademark of the Open Software Foundation, Inc.

Oracle is a registered trademark and Oracle CDD/Administrator, Oracle CDD/Repository, Oracle CODASYL DBMS, Oracle DBA Workcenter, Oracle Expert, Oracle Graphical Scema Editor, Oracle InstantSQL, Oracle Module Language, Oracle RALLY, Oracle Rdb, Oracle RMU, Oracle RMUwin, Oracle SQL/Services, Oracle TRACE, and Oracle TRACE Collector are trademarks of Oracle Corporation.

All other trademarks and registered trademarks are the property of their respective holders. <cdrom_acknowledgment>(This document is available on CD-ROM.)

This document was prepared using VAX DOCUMENT, Version V3.3-1b.

Contents

Index

This manual describes the use of the Compaq BASIC Translator (also referred to as the Translator, and formerly known as the DIGITAL BASIC Translator), which translates VAX BASIC and DEC BASIC programs to Visual Basic programs.

This manual is in two parts. Part I provides conceptual, general user information on the Compaq BASIC Translator. Topics such as elements of the Translator, the translation process, input/output (I/O), data types, and error handling are covered.

Part II is the alphabetized reference section. The translation or handling of each VAX BASIC and DEC BASIC statement, function, and language construct is provided, with specific migration information and examples where appropriate.

Intended Audience

This manual is intended for application developers who compile, link, and execute their VAX BASIC or DEC BASIC programs on OpenVMS VAX or OpenVMS Alpha systems and who want to migrate to a Windows NT, Windows 95, or Windows 98 environment.

Users will need a working knowledge of VAX BASIC or DEC BASIC and the DIGITAL Command Language (DCL). A working knowledge of Visual Basic and the Windows NT, Windows 95, or Windows 98 platform is also recommended.

Associated Documents

Please read the following documents, which contain important information:

• Compaq BASIC Translator Installation Guide
  This guide has instructions for installing the Compaq BASIC Translator on VAX or Alpha processors running the OpenVMS operating system.
• Compaq BASIC Translator RTL Version 1.2 for Windows NT, Windows 95, and Windows 98 Systems
  This document describes the run-time library installation.
• Read Before Installing or Using the Compaq BASIC Translator Version 1.2 for OpenVMS Systems
• Read Before Installing or Using the Compaq BASIC Translator RTL Version 1.2 for Windows NT, Windows 95, or Windows 98 Systems
• Compaq BASIC Translator Version 1.2 Release Notes

For more information about language element syntax and reference information, see the DEC BASIC and VAX BASIC for OpenVMS Systems Reference Manual.

For more information about Visual Basic, see the Microsoft documentation for Visual Basic.

For information on ODBC installation and setup, see the Microsoft ODBC Programmer's Reference and SDK Guide.

Conventions

Table 1 shows the conventions used in this manual.

Table 1 Conventions Used in This Manual

Convention	Description
$	A dollar sign ($) represents the OpenVMS DCL system prompt.
[Return]	In interactive examples, a label enclosed in a box indicates that you press that key on the terminal, for example, the Return key.
Example format	Examples are sometimes edited for readability, with line breaks occurring at places other than what you see on your screen.
[Ctrl/] x	The key combination Ctrl/ x indicates that you must press the key labeled Ctrl while you simultaneously press another key, for example Ctrl/Y or Ctrl/Z.
[KP] n	The phrase KP n indicates that you must press the key labeled with the number or character n on the numeric keypad; for example, KP3.
[PF1 ] x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1, then press and release another key.
n	A lowercase italic n indicates the generic use of a number.
...	A horizontal ellipsis in an example indicates that the preceding element can be repeated one or more times.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format. The items are omitted because they are not important to the topic being discussed.
( )	In format descriptions, if you choose more than one option, parentheses indicate that you must enclose the choices in parentheses.
[ ]	In format descriptions, brackets indicate that whatever is enclosed is optional; you can select none, one, any, or all of the choices.
{ }	In format descriptions, braces surround a required choice of options. You must choose one and only one of the options listed.
boldface text	Boldface text denotes user input in online versions of the manual. Visual Basic statement and routine names are bolded and in mixed case.
italic text	Italic text represents parameters, arguments, and information that can vary in system messages (for example, Internal error number). Italic text is also used for full manual titles and sometimes for product names.
UPPERCASE	Uppercase text indicates the name of a command, a routine, the name of a file, the name of a file protection code, or the abbreviation for a system privilege. Many trademarks are in uppercase, in whole or in part. VAX BASIC or DEC BASIC statements and routines are in uppercase text, for example, ABS. Visual Basic statements and routines are in mixed case and bolded, for example, Abs.

References

The following table shows certain references and their respective meanings in this manual:

Reference	Meaning
Translator or DIGITAL BASIC Translator	Compaq BASIC Translator (new name as of Version 1.2)
OpenVMS	Both the OpenVMS VAX and the OpenVMS Alpha operating systems, unless otherwise specified
Windows	Microsoft Windows NT system, Version 3.5 or Version 4.0, or Microsoft Windows 95 or Windows 98 system
Windows NT	Microsoft Windows NT system, Version 3.5 or Version 4.0
CDD or CDD/Repository	The Oracle CDD/Repository software, a product of Oracle Corporation

Sending Compaq Your Comments on This Manual

Compaq welcomes your comments on this or any other DEC BASIC manual. You can send comments in the following ways:

• Internet electronic mail: basic@tle.enet.dec.com
• FAX: 603--884--0120 Attn: Languages Documentation, ZKO2--3/K35
• A letter addressed to:

  Compaq Computer Corporation
  Languages Documentation, ZK02--3/K35
  110 Spit Brook Road
  Nashua, NH 03062--2698
  USA

If you have suggestions for improving a particular section or find any errors, please indicate the title, order number, and section (if available).

Compaq also welcomes general comments.

How to Order Additional Documentation

Use Table 2 to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800--DIGITAL (800--344--4825).

Table 2 Telephone and Direct Mail Orders

Location	Call/Fax	Write
U.S.A.	DECdirect 800--DIGITAL 800--344--4825 Fax: 800--234--2298	Compaq Computer Corporation P.O. Box CS2008 Nashua, NH 03061
Puerto Rico	809--781--0505 Fax: 809--749--8300	Compaq Computer Caribbean, Inc. 3 Digital Plaza, 1st Street, Suite 200 P.O. Box 11038 Metro Office Park San Juan, Puerto Rico 00910--2138
Canada	800--267--6215 Fax: 613--592--1946	Compaq Computer of Canada, Ltd. Box 1300 100 Herzberg Road Kanata, Ontario, Canada K2K 2A6 Attn: DECdirect Sales
International	---	Local Compaq subsidiary or approved distributor
Internal Orders	DTN: 264--4446 603--884--4446 Fax: 603--884--3960	U.S. Software Supply Business Compaq Computer Corporation 8 Cotton Road Nashua, NH 03063--1260

Part I provides an overview and a context for using the Compaq BASIC Translator. It also discusses ways to ease the use of the Translator. Topics include concepts and elements of the Translator, its features and limitations, data definition, input and output, and exception handling. <recto_head>(cancel_h) <verso_head>(cancel_h)

Visual Basic is a successful and widely used PC-based development environment. Because of its popularity and the popularity of the Microsoft Windows NT, Windows 95, and Windows 98 platforms (collectively referred to in this manual as "Windows"), Compaq offers the Compaq BASIC Translator (hereafter referred to as "the Translator") for migrating established VAX BASIC or DEC BASIC applications to those PC platforms. The Translator takes VAX BASIC or DEC BASIC source code as input and generates Visual Basic source code that, in combination with the Translator's run-time library (RTL), compiles and executes on Windows.

The Translator runs on the OpenVMS VAX or Alpha platform. It can accurately parse the full set of VAX BASIC and DEC BASIC language constructs because it shares sources (specifically, the lexical analyzer and parser) with these compilers. This avoids misinterpretation of the language. The Translator has its own code generator, which does the translation to Visual Basic code.

1.1 Features of the Translator

In support of the migration process, the Translator:

• Transforms behavior of the original application as little as possible.
  If the output of the Translator is message free, the behavior of the resulting application should be logically equivalent to the original application. When differences exist, the Translator flags them appropriately.
• Maintains the code structure of the original module.
  Where possible, the generated Visual Basic code maintains the same physical structure as the original VAX BASIC or DEC BASIC code. This means that if it is necessary to search for a piece of code, that code will be found in the same relative location as in the original source program. Also, where possible, comment lines and white space are preserved.
• Translates as much of the original VAX BASIC or DEC BASIC application as possible, using the prepackaged DECBAS_ support routines (discussed in Section 1.3.1 and Section 1.3.2).
  A direct translation from VAX BASIC or DEC BASIC code to Visual Basic code is ideal for simplicity and performance. The Translator accomplishes this for virtually all of the compatible language features. Many are incompatible to some degree. The DECBAS_ support routines significantly lessen the impact of incompatibilities, but cannot work around all of them. The Translator calls the appropriate DECBAS_ support routine when a corresponding Visual Basic language feature does not exist or when there are important differences in program behavior between Visual Basic and the source language.
  Inevitably, the DECBAS_ routines add complexity to the translated program, and they can slow performance somewhat. They are essential, however, providing powerful features, extensive flexibility, and a much more complete translation than would otherwise be possible.
• Supports OpenVMS RMS file access.
  Your translated application running on a Windows system can remotely access RMS files that are resident on OpenVMS server systems. Using this access mode, the Translator converts file access statements into calls to the Translator RMS Server component, which resides on the remote OpenVMS server along with the RMS files.
  Alternatively, your translated application can create and maintain local emulated-RMS sequential or relative files that are resident on Windows systems. Using this access mode, the Translator converts file access statements into native Visual Basic file I/O operations.
  Local Windows resident terminal-format file operations are also supported.
• Provides complete documentation for all VAX BASIC and DEC BASIC language statements, functions, and language constructs that do not translate or that translate in a way that results in differing behavior.
  Because some statements and functions cannot be translated, for lack of Visual Basic equivalents (even with the help of the support routines), this manual assists by discussing issues specific to individual statements and functions. It discusses other differences, such as data type definition and input/output (I/O).

Visual Basic is not entirely compatible with VAX BASIC or DEC BASIC, but the Translator and the DECBAS_ support routines together can translate most of the VAX BASIC or DEC BASIC source language. The degree of completeness of the translation depends on the statements, functions, and language constructs used in a specific VAX BASIC or DEC BASIC application.

The Translator issues messages to flag features that are not translatable.

The Translator is compatible with applications written in VAX BASIC Version 3.8 or higher, or DEC BASIC Version 1.2 or higher. The Translator output is compatible with Visual Basic Version 6.0.

Untranslatable Language Features

Many VAX BASIC and DEC BASIC statements, functions, and data types are directly translatable to Visual Basic. The following are not. They require the assistance of the support routines, classes, or additional reworking by hand (see Chapter 3 and Chapter 7 for detail).

• All terminal and file I/O
• Error handling
• MAP and COMMON statements, and complex records that include VARIANT blocks
• Decimal arithmetic
• MAT statements
• Some string functions
• A number of other statements and functions described in Chapter 7 (such as READ, DATA, RESTORE, and FIELD)
• Multitarget assignments, in a few cases
• Virtual arrays

Unsupported Features of the Environment

The following features of the OpenVMS programming environment are not language features and therefore are outside the scope of the Translator:

• Oracle CDD/Repository
• OpenVMS operating system services (called by LIB$, SYS$, STR$, and so on) and other parts of the OpenVMS language development environment (for example, the OpenVMS Debugger and SCA)
• DECwindows Motif
• DECforms
• Any callable interface from an OpenVMS layered product

Unsupported VAX BASIC Features

A number of VAX BASIC features are not supported, for the most part for the same reasons they were excluded from the DEC BASIC language (being obsolete, little used, or very complex), as follows:

• Graphic statements
• HFLOAT data type
• /ANSI, /FLAG, /LINES, and /SYNTAX qualifiers
• Program Design Facility support
• /FSS$ function
• Sorting line numbers
• The environment

Other Restrictions on the Translator

The following list summarizes other current restrictions on the Translator:

• The VAX BASIC or DEC BASIC DECIMAL data type is not supported for Visual Basic Version 4.0 and only partially supported for Versions 5.0 and 6.0. The specific values for the size and decimal places are ignored, because Visual Basic Version 5.0 or 6.0 provides only fixed values for them. This changes the layout of a map or record. Defined constants of DECIMAL data type are translated to variables. For more information, see Chapter 7.
• You cannot name your application the same as a Visual Basic name. Use unique names. (See Section 2.4.)
• If a MAP member has the same name as a MAP in a routine, and the MAP is specified in a MAP clause of an OPEN statement, the Translator incorrectly identifies the name as the member name and incorrectly qualifies it.
• Duplicate definitions cause Visual Basic errors. (See Section 2.4.)
• Record parameters in source code are not always handled correctly by the Translator.
• The Translator cannot handle arrays of four or more dimensions in MOVE FROM or MOVE TO operations.
• Multitarget assignment is supported. See the LET statement in Chapter 7 for a description and examples of the limited support for multitarget assignment.
• All array dimensions and string sizes used in records and maps that are translated into classes must be specified as simple numeric literals or named constants. Compile-time literal or constant arithmetic is not supported for determining size and offset information. Negative numeric literals are formed using constant arithmetic, and so are not supported in this context.
• The REMAP and MAP DYNAMIC statements are currently unsupported. MAP DYNAMIC is handled as a regular MAP. REMAP is ignored; the Translator comments it out.
• The Translator does not break single statements containing many continuation lines into multiple statements. The number of continuation lines must be within the Visual Basic limit.

Certain VAX BASIC or DEC BASIC statements and functions are translated to code that provides features very similar, but not completely identical, to their VAX BASIC or DEC BASIC counterparts. In these cases, the Translator outputs the following diagnostic message:

%DB2VB-W-FEANOTIDENT, feature not identical to translation, using closest similar word

RTL Restrictions

This section summarizes restrictions in the Translator RTL:

• Running within the Visual Basic environment (as opposed to running a compiled Visual Basic application), a program may encounter the following problem: If the program creates a new local sequential or relative (random) file and the program does not specify a directory path for the file, depending on your Windows program settings for the Visual Basic product, you may find that the created file resides in the following directory (or some other directory other than the one in which your project resides):

  C:\Program Files\Microsoft Visual Basic

  
  If you want to force file creation to the project directory or some other directory, you can modify the translated code to specify a path in the FILESPEC parameter of the DECBAS_OPEN call. Alternatively, you can change the path "globally" in the Windows settings, although this may have undesirable side effects.

• Because Visual Basic has no counterpart to the SCRATCH operation, it is emulated in much the same manner as the DELETE operation, that is, by overwriting the record(s) with zeroes but leaving the record in place. In the case of SCRATCH, the current record and all remaining records in the file are overwritten.
• For the FIND and GET statements, the LOCK and ALLOW clauses are unsupported. Visual Basic does not have any language elements that allow user programs to access "low-level" record locking in this manner.
• Sequential local and relative local file I/O support uses fixed-length records. Variable-length and stream record formats are currently unsupported, and consequently the COUNT clause in the PUT and UPDATE statements is also unsupported.
• A Ctrl/C at a terminal is not asynchronous, and takes effect only when the terminal is performing I/O or waiting for I/O.
• If a translated application being run in the Visual Basic environment is stopped before an open file is closed and then re-run, Visual Basic reports that the file is already open when the OPEN statement is executed.