The Translator provides support both for traditional terminal input and output (I/O) and for the major file organizations: terminal-format, sequential, relative, and indexed.

5.1 File Input/Output Strategies

The Translator supports two different file I/O strategies: remote file access and local file access.

• Remote --- In the remote file access method, the existing RMS data files remain on an OpenVMS server system. You install the Translator RMS Server component on each OpenVMS server system containing an RMS data file to be accessed over the network. Your program's VAX BASIC or DEC BASIC RMS I/O statements are translated into calls to lower-level routines, which in turn send and receive I/O commands and data between the Windows system running the translated application and the remote OpenVMS server system containing the RMS files.
  This remote file access method using the Translator RMS Server works with files opened with organization sequential, relative, and indexed (it is not for terminal-format files). Only existing remote RMS files can be opened and accessed using this method.
  If you have RMS indexed files (as opposed to sequential or relative files), the remote file access method is the only file access that is available for the Translator, because no native support for emulating RMS indexed files is available in Visual Basic on the Windows system.
  An alternative approach to remote file access is to use the Translator's open-ended architecture to call various Microsoft and third-party APIs (for example, ODBC API calls, RDO classes, and so on) to utilize the ODBC API. The Translator provides partial implementation of this approach; you can also use Visual Basic to develop your own classes that use these APIs.
• Local --- The local file access method works for terminal-format, sequential, and relative files. The data files are created and maintained on a Windows system. The Windows system that is running the translated application can contain the file on one of its own disks, or the file can be contained on a mapped network drive; in either case, it is considered a "local" file for the purposes of the Translator.
  With local file I/O, your program's VAX BASIC or DEC BASIC I/O statements are translated into calls to lower-level routines, which in turn call Visual Basic file I/O functions to emulate a subset of the appropriate terminal-format, sequential, and relative file I/O operations.
  This local file access method does not provide as much flexibility or as many features as the RMS remote file access method, and there is no indexed file support. One advantage of the local file access method is that you can create new files as well as opening existing files.

The Translator provides a terminal emulation window on your Windows display. This window remains on the display until you close it. Traditional VAX BASIC or DEC BASIC terminal I/O is performed on this channel #0 terminal emulator without any special action on your part.

If you wish, you can also assign other terminals to the channel #0 emulator. To do this, open another channel with a nonzero channel number and use one of the standard terminal names as the file specification, for example, SYS$INPUT, SYS$OUTPUT, SYS$ERROR. TT:, or KB:.

You can also open one or more additional virtual terminals, separate and distinct from the channel #0 terminal. To do this, open a file on a different channel and specify the LOCATION parameter in the translated DECBAS_OPEN call to be DECBAS_ LOCATION_TERMINAL.

The Translator supports the following VAX BASIC or DEC BASIC statements in the terminal emulator:

BUFSIZ
CCPOS
CLOSE
CTRLC
ECHO
INKEY
INPUT
INPUT LINE
LINPUT
MAR
MARGIN
MAT INPUT
MAT LINPUT
MAT PRINT
NOECHO
NOMARGIN
NUM
NUM2
OPEN
PRINT
PRINT USING
RCTRLC
RCTRLO
RECOUNT
SETNOPROMPT
SETPROMPT
SLEEP
WAIT

For a list of the supported terminal emulator functions, refer to Appendix C.

5.3 File Organizations

The Translator supports the following file organizations:

• Terminal-format (local)
• Sequential (local or remote)
• Relative (local or remote)
• Indexed (remote)

If you do not specify a file organization when opening a file, the organization defaults to terminal-format. This is consistent with VAX BASIC and DEC BASIC.

5.3.1 Terminal-Format Files

If your VAX BASIC or DEC BASIC OPEN statement does not specify ORGANIZATION, the Translator uses local file I/O to emulate VAX BASIC or DEC BASIC terminal-format I/O. The terminal-format file is resident on the Windows system.

The Translator supports the following VAX BASIC or DEC BASIC statements for terminal-format files:

BUFSIZ
CCPOS
CLOSE
INPUT
INPUT LINE
LINPUT
MAR
MARGIN
MAT INPUT
MAT LINPUT
MAT PRINT
NOMARGIN
NUM
NUM2
OPEN
PRINT
PRINT USING
RECOUNT

If your VAX BASIC or DEC BASIC OPEN statement specifies ORGANIZATION SEQUENTIAL, by default the Translator uses local file I/O in Visual Basic in which the files are resident on the Windows system. This default can be overridden to specify remote files using a method described in Section 5.3.5.

For local sequential files, VAX BASIC or DEC BASIC sequential file I/O is emulated with Visual Basic random file I/O. What Visual Basic refers to as its own "sequential" file I/O more closely resembles VAX BASIC or DEC BASIC terminal-format file I/O, so the Translator uses random file I/O to better emulate RMS sequential file operations. The fixed-length file format is the only one supported within Visual Basic for local sequential files.

The Translator supports the following VAX BASIC or DEC BASIC I/O statements for sequential files:

BUFSIZ
CLOSE
DELETE
FIND
FREE
GET
GETRFA
MAP
MOVE FROM
MOVE TO
OPEN
PUT
RECOUNT
RESTORE
SCRATCH
UNLOCK
UPDATE

If your VAX BASIC or DEC BASIC OPEN statement specifies ORGANIZATION RELATIVE, by default the Translator uses local file I/O in Visual Basic, with the files resident on the Windows system. You can override this default and specify remote files using a method described in Section 5.3.5.

For local relative files, VAX BASIC or DEC BASIC sequential file I/O is emulated with Visual Basic random file I/O. The fixed-length file format is the only one supported within Visual Basic for local relative files.

The Translator supports the following VAX BASIC or DEC BASIC I/O statements for relative files:

BUFSIZ
CLOSE
DELETE
FIND
FREE
GET
GETRFA
MAP
MOVE FROM
MOVE TO
OPEN
PUT
RESTORE
UNLOCK
UPDATE

If your VAX BASIC or DEC BASIC OPEN statement specifies ORGANIZATION INDEXED, the Translator must use remote file I/O to access the file on an OpenVMS system. Because certain parameters necessary for remote file I/O are not normally contained in your original VAX BASIC or DEC BASIC source program, it will be necessary for you to perform some one-time post-translation modifications to your translated program to specify these parameters, using a method described in Section 5.3.5.

The Translator supports the following VAX BASIC or DEC BASIC statements for indexed files:

BUFSIZ
CLOSE
DELETE
FIND
FREE
GET
GETRFA
MAP
MOVE FROM
MOVE TO
OPEN
PUT
RESTORE
UNLOCK
UPDATE

OPEN statements are translated into calls to the DECBAS_OPEN procedure, a run-time component that calls lower-level methods in the RTL DLL. The default file access method for sequential and relative files is local file I/O, with the files resident on the Windows system as opposed to being resident on a remote OpenVMS system. The default access method for indexed files is remote file I/O, because indexed files must always be resident on a remote OpenVMS system.

Remote data files must already exist on the remote OpenVMS file server system. The translated program cannot create new RMS files across the network.

If you access remote indexed files in your program, or if you access sequential or relative files that you plan to keep on an OpenVMS system, and you have installed the Translator RMS Server component on the OpenVMS system, you will need to perform some one-time post-translation modifications to your translated program to specify remote file I/O parameters.

To specify remote file access in your translated program, locate the appropriate DECBAS_OPEN procedure call in the translated code and change the following three parameters as follows:

• FILESPEC --- The FILESPEC parameter is the first parameter of the translated DECBAS_OPEN procedure call. You must ensure that the FILESPEC parameter of the DECBAS_OPEN call specifies the full disk and directory path to the file, as well as the file name. Logical names can be used if the logical names are defined during the remote login process, for example in the LOGIN.COM file of the host account.
• DEFAULTNAME --- The DEFAULTNAME parameter is the seventh parameter of the translated DECBAS_OPEN procedure call. The DEFAULTNAME clause is not supported for remote file I/O. Because of this, its parameter becomes available for a different purpose, specifically to establish a "connect string" with which you log in to the remote OpenVMS system containing the RMS files. This is a string parameter whose value after translation might initially specify

  DECBAS_STRING_ARG_DEFAULT

  
  Or perhaps it specifies some other string from your original VAX BASIC or DEC BASIC source program. To specify the connect string values, change this parameter to a string containing the host system address, followed by a semicolon, followed by the host account username, followed by another semicolon, followed by the host account password. An example of the contents of a properly formatted connect string might be:

  poiuyt.servu.com;myacct;mypasswd

  
  One way to construct this connect string in the translated program is either to prompt the user for these three connect values, or to read them from a local file, and then construct the string prior to the DECBAS_OPEN call as follows:

  ConnectString = HostAddress & ";" & _ HostUserName & ";" & _ HostPassword

  
  Then, replace the seventh parameter of the translated DECBAS_OPEN call with the prepared ConnectString variable.

• LOCATION --- The LOCATION parameter is the thirteenth parameter of the translated DECBAS_OPEN procedure call. After translation, the value of this parameter would most likely specify

  DECBAS_LOCATION_UNSPECIFIED

  
  Or perhaps

  DECBAS_LOCATION_LOCAL

  
  To specify that the file resides on a remote OpenVMS server, change this parameter to:

  DECBAS_LOCATION_REMOTE

After making the above one-time modifications to the translated DECBAS_OPEN procedure call, the remote RMS file will be accessed over the network at run-time without any further changes, transparently to the users of the translated program.

A translated program running on Windows can be connected to many different remote OpenVMS systems at one time, performing remote I/O operations independently on each system over the network. Conversely, translated applications running on many different Windows systems can be simultaneously connected to the same OpenVMS server and file (assuming the OPEN statement specified the proper sharing characteristics).

5.4 File and Record Operations

The Translator supports some file and record operations in all access modes, while other operations are supported by only some of the modes. Refer to Chapter 7 for more detail on the individual operations.

5.4.1 Opening Files

This section discusses some considerations regarding opening files: code differences, file location, and keys.

Code Differences

Some of the VAX BASIC or DEC BASIC OPEN clauses work differently in Visual Basic, and some of the clauses are not supported. Where there are differences, it is typically because there is no reasonable corresponding Visual Basic or Win32 mechanism, or because the clause conflicts with some underlying feature or architectural construct of Visual Basic or the Windows system.

For example, RMS is not available as a native API on Windows systems. Although the Translator provides access to RMS files via the Translator RMS Server component, there are some VAX BASIC or DEC BASIC I/O clauses that are not currently supported by the Translator.

The following VAX BASIC or DEC BASIC OPEN clauses are not currently supported:

BLOCKSIZE
BUCKETSIZE
BUFFER
CONTIGUOUS
DEFAULTNAME
EXTENDSIZE
FILESIZE
NOREWIND
NOSPAN
ORGANIZATION UNDEFINED
ORGANIZATION VIRTUAL
ORGANIZATION [any format] STREAM
RECORDTYPE
SPAN
USEROPEN
WINDOWSIZE

As with most of the other Translator statements and functions, use caution when dealing with explicit VAX BASIC or DEC BASIC error codes, which may be different from those in Visual Basic. The Translator attempts to map between VAX BASIC or DEC BASIC and Visual Basic error codes, but some codes do not convey equivalent meanings, so it is best to check and test each usage of error codes.

FILE Location

The Translator attempts to determine whether the file that you are opening is a terminal (the terminal itself, not a terminal-format file), a locally resident sequential or relative file, or a remotely resident indexed file. There may be occasions when the Translator is unable to make the correct determination. In those cases, you must modify the DECBAS_OPEN procedure call in the translated code to change the LOCATION parameter (the thirteenth parameter in the DECBAS_OPEN call).

The Translator always provides a channel-zero terminal emulator window for the usual console terminal I/O operations (PRINT, INPUT, and so forth). If you are opening a separate terminal window on another channel, using one of the standard designations such as SYS$INPUT, SYS$OUTPUT, SYS$ERROR, KB: or TT:, the Translator recognizes that you are opening the terminal. Otherwise, you must change the LOCATION parameter of the DECBAS_OPEN call, to be DECBAS_LOCATION_TERMINAL.

Refer to Section 5.3.5 for information on how to modify the LOCATION parameter and other parameters for the various file organizations.

Keys

If you are making use of a large number of alternate keys or segmented keys, it is possible to exceed the Visual Basic maximum number of continuation lines per statement in the translated Visual Basic DECBAS_OPEN call. If this happens, you may need to shorten the length of your key variable names or perhaps even reduce the number of segments or alternate keys.

5.5 Unsupported File Input and Output

The Translator does not support the following types of file I/O:

• RMS I/O to ANSI magnetic tapes
• Device-specific I/O to magnetic tapes, disks, and unit record devices
• I/O to mailboxes
• Network I/O