836.TXT
======================================================================
Writing a Cross-Platform Application
======================================================================
PRODUCT: R:BASE VERSION: 5.5
======================================================================
CATALOG: Programming in R:BASE AREA: Other
======================================================================
The different R:BASE 5.5 products_R:BASE 5.5 for DOS, R:BASE 5.5 for
Windows, and R:BASE 5.5 for OS/2_provide true cross-platform
compatibility in the PC environment. You can run the R:BASE 5.5
program in DOS, Windows 3.1 or 3.11, Windows 95, Windows NT, or OS/2.
Each product can access the same database on a network server and
provides the same functionality. You can even write one application
that can be run by users on any of these platforms; you don't need to
write a separate application or special code for each of the
different operating systems. You can even have users accessing the
database across the Internet using R:WEB.
To develop a cross-platform application, you need R:BASE 5.5 for DOS
to develop the character based forms and reports, and either R:BASE
5.5 for Windows or R:BASE 5.5 for OS/2 to develop the graphical user
interface (GUI) forms and reports. For all intents and purposes,
R:BASE 5.5 for Windows and R:BASE 5.5 for OS/2 can be considered as
one product for application development. A single PC can run both the
DOS version of R:BASE and the Windows or OS/2 version of R:BASE
connecting to a database on a network server.
The following sections provide some tips for writing an application
that runs across different operating systems. For convenience, both
the Windows and OS/2 versions are usually referred to as the Windows
version.
Checking the Operating System
In most cases you can use the same command in R:BASE in any operating
system. Sometimes, however, you may want to use a syntax supported in
one version (either DOS or Windows) but not the other. For example
the CHOOSE command has different options in character mode as opposed
to GUI mode. In many cases the non-supported options are ignored, but
there will be situations where you want to run a different command
depending on the operating system. You can use the CVAL function to
find the version and operating system of R:BASE that is being run on
a particular machine. In the OS/2 product, two new CVAL options, BITS
and SYSTEM, have been added to allow a developer to easily determine
the product being used. These options will be added to the DOS and
Windows versions as new releases are made available.
For example, use the command:
SET VAR vversion = (CVAL('VERSION'))
In R:BASE 5.5 for Windows, this sets the variable vversion to the
string: R:BASE 5.5, U.S. Version, Build: 1.320x025M. In R:BASE 5.5
for DOS, the variable is set to the string: R:BASE 5.5 DOS (32-bit),
U.S. Version, Build: 5.5x027G. Notice that the DOS version returns
the bits and the system even though the new CVAL keywords are not yet
available. Use R:BASE string manipulation functions to parse the
build number, bits, and system from the version string. Then, you can
execute different commands based on the operating system.
The keyword version in the CVAL function will always return the full
version identifier string. The new keywords BITS and SYSTEM return
just a portion of the string. Here's the syntax for the new keywords:
SET VAR vversion = (CVAL('VERSION BITS'))
SET VAR vversion = (CVAL('VERSION SYSTEM'))
The keyword version bits returns 16 or 32. The keyword version system
returns DOS, OS2, or WIN.
You can use the CVAL function to find the version for Runtime. To
find the R:WEB version you need to create a file named ALL.RMD with
the following commands:
-- all.rmd
SET VAR v_version = (CVAL('VERSION'))
DIALOG 'The version of R:WEB is:', v_version, vkey, 1
EXIT
Then, run RWEB.EXE using the file ALL.RMD; the version displays in
the dialog box.
The current build numbers for the different versions of R:BASE 5.5
are:
R:BASE 5.5 for DOS 5.5x027G
R:BASE 5.5 for Windows 1.320x025M
R:BASE 5.5 for OS/2 26J** fill in after release to production
4/19
RWEB 1.347x027G
If you do not have the current version for a product, you can
download a patch to the current version from the Microrim bulletin
board, 206-649-9836, the Microrim forum on CompuServe, GO MICRORIM,
or Microrim's home page on the Internet, http://www.microrim.com.
The current version of RWEB is available only from the Internet.
Using Forms
Forms for the character-based version of R:BASE, R:BASE 5.5 for DOS,
and the GUI versions, R:BASE 5.5 for Windows and R:BASE 5.5 for OS/2,
are stored in different system tables. The DOS character based forms
are stored in the system table SYS_FORMS, the GUI forms are stored in
the system table SYS_FORMS2. You do need to create forms for both
character-based and GUI platforms.
You can have forms with the same name as both a character based form
and a Windows form. R:BASE 5.5 for DOS knows to look in the system
table SYS_FORMS for a form, and the Windows versions look for the
form in the system table SYS_FORMS2. Your application uses the same
command, EDIT USING formname WHERE..., for example, to bring up the
form in any platform.
We suggest that you first create the character based form in R:BASE
5.5 for DOS, then in the Windows version, convert the form to a GUI
format and customize it. All of the basic form features such as the
located fields, expressions, EEPS, and settings are automatically
converted. All you need to do is add the customization features, such
as fonts, colors, and 3D boxes, available only in the Windows and
OS/2 versions.
Windows and OS/2 have different fonts and colors available. Not all
Windows fonts are available in OS/2. Some colors translate
differently between Windows and OS/2. When building a database and
application that will be used in both Windows and OS/2 we recommend
choosing the fonts and colors based on OS/2 which has a smaller set
available.
The MDI form syntax is available in the GUI versions only; it is not
available in the DOS version. You can include this option in your
application by using an IF statement to run MDI forms only when a
user is running R:BASE for Windows or R:BASE for OS/2.
Using Reports and Labels
Like forms, the character based reports and labels are stored in
different system tables than the GUI based reports. The DOS reports
are stored in the system table SYS_REPORTS and the Windows and OS/2
reports are stored in the system table SYS_REPORTS2. The DOS labels
are stored in the system table SYS_LABELS and the Windows and OS/2
labels in the system table SYS_LABELS2. You can have DOS and GUI
reports and labels with the same name so your application only needs
one command to print the report or label. Like forms, you don't need
to use a different command to print a report or label for the
different operating system.
Again, we suggest creating the DOS report or label first. Then,
convert the report or label using R:BASE 5.5 for Windows or OS/2.
This preserves the report or label layout, defined expressions, and
any specified settings. Customize the report in R:BASE 5.5 for
Windows or OS/2 using the GUI only features such as colors, fonts,
and properties.
Programming Considerations
There are relatively few command changes between DOS, Windows, and
OS/2. In most cases, non-supported options are ignored and the
command is executed. This makes it easy to run the same application
on different platforms as you don't need to spend time writing
separate applications.
The CHOOSE command is one command with syntax changes between the
versions. There are DOS only options: CASCADE, CLEAR, FOOTING,
FORECOLOR ON BACKCOLOR, RIGHT, LEFT, RESET, NOCHG; and Windows and
OS/2 only options: CAPTION, LINES. The options not supported in a
particular version are ignored. You can run the same command in
either DOS or Windows. However, when you use the CASCADE option in
DOS you will probably want to run a different CHOOSE command in
Windows and OS/2 to position the menus correctly on the screen since
the CASCADE option is ignored in Windows and OS/2 and the menu is
displayed in the upper left hand corner of the screen.
The following list of commands are available in R:BASE 5.5 for DOS
only:
MENU
PROMPT
ZIP RETURN/ROLLOUT
The SET commands:
CGA
EDITOR
EXPLODE
MOUSE
PRINTER
SORT LAST
SORT MAX
SORT MIN
TABSIZE
WALKMENU
The following list of commands are available in R:BASE 5.5 for
Windows or OS/2 only:
Command line GATEWAY (Windows only)
Command line CODELOCK
EDIT/ENTER MDI formname
MINIMIZE
MAXIMIZE
NORMALIZE
SETFOCUS
CLOSEWINDOW
TILE
CASCADE
PRNSETUP
Function keys have changed where necessary so as not to not conflict
with standard Windows and OS/2 function keys. For example, to add a
row in the Data Browser you use [F10] in DOS, but [F2] in Windows and
OS/2. To zoom a TEXT or NOTE field in a form or the Data Browser you
use [Shift]+[F4] in DOS, and [Shift]+[F2] in Windows and OS/2. In
OS/2 only, you use [F2] to add a row in a form instead of [F10].
There are other function key differences in Trace. Press
[Shift]+[F1] when in a particular area of the product to view a list
of the available function keys.
In Windows and OS/2, when you zoom TEXT and NOTE fields, the data is
displayed in the RBEdit viewer. In DOS, you can SET ZOOMEDIT ON to
use RBEdit to display zoomed TEXT and NOTE fields in a form. When
you have ZOOMEDIT set on, the data in the field does not wrap when
displayed in RBEdit. If you press [Enter] to wrap the text, you
actually place a LINEEND character in the data. To display data as
wrapped without LINEEND characters, use the standard DOS zoom feature.
Use DIALOG commands in your applications instead of FILLIN commands.
The DIALOG command will display appropriately in all operating
systems. The FILLIN command is geared to DOS applications. The WRITE
command is also geared to DOS applications, so instead of WRITE, use
the PAUSE command to display messages. When using PAUSE, don't use
the AT option in Windows or OS/2. It currently displays as a DOS-
style box and can cause problems.
PLAYBACK files may need to be different for DOS and Windows as some
keystrokes and menu options are different. Windows and OS/2 provide
parameters for the PLAYBACK command to allow the developer to better
control the speed at which the playback file operates.
You may be using DOS specific functions or procedures in your
application. Remember, DOS and Windows have different user
interfaces. DOS is character based; Windows is not. If you are using
DOS UDF's, read the section User-Defined Functions in the Reference
Manual for information on the Windows-only display options.
EEPs
EEPs are the one area in application development that almost always
require code changes between a DOS application and a Windows or OS/2
application. You can run the same EEP, just have different sections
depending on the users operating system and version. Use the CASE_
SWITCH structure to run the different code sections. For example:
SET VAR vversion = (CVAL(`VERSION SYSTEM'))
SWITCH (.VVERSION)
CASE `dos'
-- execute DOS only code here
BREAK
CASE `os2'
-- execute OS/2 only code here
BREAK
CASE `win'
-- execute Windows only code here
BREAK
ENDSW
Many of the code changes in EEPs are due to differences in the way
data is displayed to the screen in character mode DOS versus GUI
based systems such as Windows and OS/2. In DOS you have a single
screen or pane. All forms are displayed on the single screen and any
other information is written to that single screen. The form and the
R> prompt where command processing occurs occupy the same screen
space. Commands in EEPs that display data to the screen, such as
SELECT, display that data on the same screen as the form. Because you
only have one screen for displaying the form and other information,
there are specific techniques, such as CLS, that are used to make it
appear as if there are more screens, or to differentiate the data
that is displayed. These techniques are not applicable to a Windows
application.
In Windows, a form is displayed in a separate window from the R>
prompt. Commands in EEPs that display data to the screen, such as
SELECT, cannot display that data on the same screen window as the
form. The WRITE and CLS commands also expect an R> prompt type
window. You don't have that type of screen display in Windows. Each
form or R> prompt command is displayed in its own screen window.
Because of the differences in screen display between DOS and Windows,
you can't use the same screen display commands in an EEP for both
platforms. The EEP only commands work across versions as do other
programming commands such as SET VAR, but commands that display data
or messages need to be modified.
For Windows, commands that use the WRITE command to display data to
the screen should be changed to use the PAUSE command. The PAUSE
command displays messages in a screen box in both DOS and Windows.
Another way to display information on a form in Windows is to place a
variable on the form. In the EEP, set the value of the variable as
desired. Use RECALC VARIABLES to display the new variable value on
the form. This works equally well in DOS. To clear the display, set
the variable to NULL.
In Windows, instead of displaying data from a SELECT command, print
a report to the screen. EEPs that generate playback files will also
need to execute different code depending on the platform, as
keystrokes and menu options are different between the DOS and Windows
versions of R:BASE.
Form in form techniques that worked in DOS don't always work well in
Windows. In Windows, use MDI forms to display a "windowed"
form-in-a-form. In Windows, each form displays in its own sizable
window; you can't place a form directly on top of another form in the
same window. Use the CASE_SWITCH structure as shown above to execute
different EEP code depending on the operating system.
Printing
For DOS installations you need a .PRD file for printing reports with
formatting options such as landscape, condensed print, bold, and
underline. The .PRD file should be placed in the program files
directory, usually RBFILES. The .PRD file is an ASCII file of
printer control codes and can be edited to add or modify codes for
specific printers. The .PRD file to be used by R:BASE is identified
by using the SET PRINTER command. When specifying PRINTER as the
output device, R:BASE always prints to the printer connected to or
identified as LPT1. To print to other printers, you must use the
device name with the OUTPUT command, for example, OUTPUT LPT3.
For Windows and OS/2 installations, printers are defined by the
operating system. When specifying PRINTER as the output device,
R:BASE always prints to the printer specified as the default printer
through Print Setup. To print to other printers, you must change the
printer specification through the Print Setup dialog. The PRNSETUP
command can be used to call the Print Setup dialog in a program.
ODBC Connectivity
In R:BASE for Windows 5.5 you can connect to non-R:BASE databases as
well as other R:BASE databases through ODBC connectivity. ODBC is a
Windows only feature. In R:BASE 5.5 for DOS and R:BASE 5.5 for OS/2
the ability to connect to other R:BASE databases is provided.
However, while you can connect to an R:BASE database and attach
tables in each platform, each of the operating system handles the
connectivity slightly differently. You should put separate code in
your application for each platform that connects to the foreign
database and attach tables using alias names that designate in which
platform they were attached. For example:
SWITCH (.VVERSION)
CASE `dos'
SCONNECT otherdb
SATTACH table1 AS DOS_table1
BREAK
CASE `os2'
SCONNECT otherdb
SATTACH table1 AS OS2_table1
BREAK
CASE `win'
SCONNECT otherdb
SATTACH table1 AS WIN_table1
BREAK
ENDSW
Installation and Setup Issues
R:BASE for Windows and R:BASE for OS/2 both have a .INI file
(RBASE.INI and RBGOS2.INI). The RBASE.INI file locates the other
needed files_the RBASE.CFG file, the help file, and the message
files. The .INI file also locates the SERVER.RBG file. R:BASE looks
for the .INI file in the current or working directory first, then
searches the path and search maps, and then the .EXE directory.
R:BASE stops looking with the first .INI file it finds. The file
locations stored in the .INI file are updated through the Utilities:
Preferences menu option. The Windows RBASE.INI file is an ASCII file
and can be edited. The OS/2 RBGOS2.INI file is binary. In addition to
file locations, the .INI file contains designer and other program
defaults.
In DOS, the SERVER.RBG file, the RBASE.CFG file, the help files, and
the message files must be on your PATH or a defined search map. There
is no RBASE.INI file in R:BASE 5.5 for DOS. R:BASE first looks in the
current directory for the RBASE.CFG file and the SERVER.RBG file,
then searches the path and the defined search maps.
All versions of R:BASE use the same SERVER.RBG file. Thus, the LAN
pack creates a multi-user SERVER.RBG file that counts R:BASE users
regardless of operating system.