home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Devil's Doorknob BBS Capture (1996-2003)
/
devilsdoorknobbbscapture1996-2003.iso
/
Dloads
/
PROGRAMM
/
BUILDER.ZIP
/
TECHNOTE.TXT
< prev
next >
Wrap
Text File
|
1992-11-17
|
31KB
|
923 lines
Additional BUILDER 2.0 programming tips and information. Please
print out this file for your future reference.
This file deals with several BUILDER 2.0 programming issues. In order
of appearence, they are:
1) The TOOLS menu of the BUILDER 2.0
Integrated Development Environment
(and the programs that relate to
that menu).
2) The BUILDER 2.0 Help Compiler.
3) Linking multiple .OBJs with BUILDER
2.0.
4) Subroutines passing and returning
values.
Tools Menu - BUILDER 2.0 Integrated Development Environment
The Tools menu is represented by the three
horizontal lines on the far left of the
LightBar menu at the top of the screen. You
may activate this menu choice by either
pressing {Ctrl Space}, or by clicking on it
with your mouse.
Once you've selected the Tools main menu
option, a DropDown menu will appear
presenting more choices. We will concern
ourselves in this text with IG - the
Installation Generator, ONLINE - the BUILDER
telecommunication interface, and MG - the
Menu Generator. (A discussion of the Tools
menu ASCII chart and its operation is
included in Chapter 5 of the BUILDER 2.0
manual).
What is a tool?
Simply put, a tool is something that helps
you do your job. In the case of a
programming tool, a tool helps you to develop
faster, better, or more flexible programs
than you could without it.
As you know, BUILDER is a language. But not
just any language, it's a compiled language.
As a compiled language, it is comprised of
many tools. The tools you use when you fire
up BUILDER are:
1) Text editor (BUILDER.EXE, the IDE)
2) Compiler (BLD.EXE)
3) Linker (MLINK.EXE)
4) Runtime library (BLD.LIB)
In BUILDERs case, all of these tools work
together to allow you to create, compile and
link a program. Sometimes tools work on
their own, other times they work in tandem.
The code generators and communications
interface that are available to you under the
Tools menu also fall into the general
category of programming tools.
Code generators
Code generators allow you to create the
native language script that is then compiled
to create a running program. Code generators
work in various ways to accomplish this task.
The code generators that are provided with
BUILDER 2.0 will help you to quickly create
bullet-proof installation scripts or slick
front-end menus.
The BUILDER code generators create scripts
that compile into Installation programs or
Menu front-ends. By making a series of menu
choices, the code generators can determine
how you want something to look, and how you
would like it to behave. With that
clarified, the code generator can then go
about its work of assembling the correct
commands in the proper order to accomplish
the task. The result is a source code or
native language script that, once compiled,
will perform as you have instructed it to.
The native language script that is created by
the code generator can be edited and modified
before compiling. The source code can be
modified further after compiling in order to
continue to enhance the compiled program.
ONLINE
The remaining Tools menu option is the
BUILDER ONLINE interface. This tool allows
you to access our electronic Bulletin Board
Service (BBS), through your modem, from
within the BUILDER IDE.
The best user-based feed back on hyperkinetix
programming tools is our proprietary BBS.
The hyper BBS, hyperactivity, receives visits
24 hours a day from programmers all over the
world. Through hyperactivity you have access
to thousands of lines of BUILDER code,
thousands of BUILDER users, and the entire
hyperkinetix support and development staff.
If you have any problems on your first
connection to the BBS please call. You'll
find that direct electronic access to us will
increase your productivity and reduce your
downtime.
IG - the Installation Generator
IG.EXE is the installation script code
generator that is activated from the Tools
menu by pressing {I}. This chapter will
familiarize you the operation of BUILDER's
IG.EXE. By the end of this section you'll
understand what an installation program is,
how IG.EXE works, and why IG.EXE is the only
way to go if you're looking for an effective
tool to quickly create bullet proof
installation scripts.
What's an installation program?
An installation program is distributed with
most software in order to copy or "install"
the program from a removeable, or floppy
diskette onto a fixed disk, or hard drive.
By this definition, it's hard to understand
why a good installation program is so highly
regarded. It would be fair to say that
although the definition given above
accurately describes the objective of an
installation program, it doesn't begin to
explain the problems encountered when you
develop a program that is supposed to be
flexible, fast, and fool-proof.
One of the most used abilities of BUILDER is
that of installation script creation. We
write the installation scripts for all of our
commercial software in BUILDER! We do so for
many reasons:
1) Small compiled code size
2) Bullet-proof .EXE files
3) Easily maintained code
4) We can brag about it!
We think you'll brag about your experience
with BUILDERs IG.EXE, too!
IG.EXE unveiled
When creating an installation program, you
must consider several factors which are not
in your control, but by which your program
will have to abide. Because of this, a good
installation script will allow the user to
make choices, and the program itself will
only execute those choices if they are valid,
and possible.
Some considerations:
Source drive- Will your software ship on
dual media. Should the user have a choice of
installing from A drive, B drive, etc?
Target drive- Where should this program be
copied to? C drive is common, but should
there be a choice?
Target directory- Where on the drive should
these files reside, does that matter, is it
an update to a series of files already on the
users machine?
Along with these decisions are a series of
equally important questions. Is there enough
free disk space to hold the installation?
Should you compress the distribution files?
Will the user have the utility to uncompress?
When the installation is complete should the
user be informed, and how?
You can begin to see why just copying the
files from A: to C: without a smart
installation or any user interaction can be
dangerous.
IG.EXE is not designed to create the most
powerful installation you can get from
BUILDER. IG.EXE is designed to create an
installation that will save your user from
making a huge mistake, but save you from
spending any more than 10 minutes on your
install. Obviously you can tweak and
customize the code that IG.EXE creates. We
encourage you to do so. But we also know
that a solid, consistent installation is the
best first impression you can make with
users. That is the goal of IG.EXE.
Your options
In preparing to use IG.EXE you should assure
that the following is true:
1) IG.EXE, BLD.EXE, BLD.LIB, and
MLINK.EXE are on the PATH.
2) All of the files you want included
in the installation are in a
directory, and appropriate sub-
directories, that is named exactly
as it should be on the end users
machine after the installation is
complete.
3) You are in that directory.
Type IG at the DOS prompt and ENTER through
the opening dialogue box. A LightBar menu
will appear that allows the following
choices, File, BUILD, and Options. Select
these options by pressing {Alt} and the
hotkey {F}, {B}, or {O}, or click on the item
with your mouse.
File menu
The File menu allows you to shell out to DOS.
You can also accomplish this with the hotkey
combination {Alt S}. From the Files menu you
can also re-display the sign-on box by
selecting About. Quit by selecting Quit.
You may also exit IG.EXE with the hotkey
combination {Alt X}.
BUILD menu
You should complete the Options menu before
entering the BUILD menu. The Options menu
contains many critical choices regarding the
BUILDing of your distribution diskettes.
This menu allows you to BUILD the actual
installation, and distribution disks. The
only selection given is to BUILD your disks.
Selecting it will open a dialogue box that
queries you as to what files to use in
building the installation. The default is
*.* because your resident directory should
include any and all files to be used in your
installation. Your last decision in this
menu is whether or not to search sub-
directories for files to build your
installation disk(s). Move between input
fields in the menus with the {Tab} key.
Select OK when you have made your choices,
and IG.EXE will go to work.
IG.EXE will eventually ask you for the
location of your install disks. This is the
drive location holding the diskettes that you
want the installation program and all of the
intended install files copied to. Use {Tab}
to highlight your choice and press {Enter}.
A success box is displayed when this process
is completed successfully, otherwise you will
receive an error message to act upon.
Options menu
The Options menu contains the following
choice sub-menus:
Compress toggle
Do you want your distribution disks built
with compressed (BCF) files? Yes or no are
your selectable answers.
Disk size
What size disk would you like the
installation written for. IG.EXE will
automatically customize some of it parameters
to take maximum advantage of the disk size
you choose. 360k, 720k, 1.2M, and 1.4M are
your selectable answers.
Disk fit method
Do you want IG.EXE to build the distribution
disks in the most space efficient manner, or
by the order they appear in the resident
directory. You choose one or the other.
Banner text
This information will appear when the
installation program starts up. We recommend
that you use the first dialogue line for the
name of the program you are installing, and
the second line for you company name.
Change README name
A README file designation must be made.
IG.EXE will place the file named here on the
first diskette. We recommend that you use
this option for any file that you want the
user to have access to prior to the
installation.
Default destination path
This option allows you to name the default
installation destination. List the
destination by Drive:\Directory\Subdirectory
(if any).
Needed drive space
Enter the amount of disk space, in bytes,
that the installation will require. This
cannot be done dynamically by the
installation program if you are distributing
compressed files. Enter the needed space in
bytes, not K. 100,000 would represent less
than 100K; remember there are 1024 bytes in a
K.
Load configuration
If you have built and saved a set of options
for an installation before, you can load it
back into IG.EXE with this option.
Save configuration
Before exiting you may want to save the
configuration for future use and reference.
There will be no prompt by IG.EXE to save a
configuration.
The INSTALL.OBJ, .BLD files
As IG.EXE did its job of write, compile, and
build it created some other files that you
may find useful. A .OBJ file was created
that you could link into other applications.
A .BLD file was created for your further
editing and compiling.
Astonishingly, that's it! In ten minutes you
have an installation program that does
everything you need it to, and allows for you
to add more to it if you like. Slick!
MG - the Menu Generator
MG.EXE is the front-end menu code generator
tool, a menu front-end is nothing more than a
shield most users stand behind to avoid
operating their computers from a DOS prompt.
It should be very easy to use, and of small
size in order to use as little RAM as
possible.
MG.EXE unveiled
MG.EXE is a menu script generator. Type MG
at a DOS prompt to activate the code
generator. An environment will load
displaying a LightBar with the following
options File, Write, Colors, and Options.
Along the bottom of the editor box you will
also notice that {Alt X} will exit the
program. Along that bottom line you also
find the Ins and Del options.
Select an option by pressing {Alt} and the
items hotkey. The following option
descriptions are in order of appearance.
File menu
The File menu allows you to shell out to DOS.
You can also accomplish this with the hotkey
combination {Alt S}. From the Files menu you
can also re-display the sign-on box by
selecting About. Quit by selecting Quit.
You may also exit MG.EXE with the hotkey
combination {Alt X}.
Write menu
This menu is used to activate the generator.
You will be asked to name the menu you are
creating, and then the generator will get
right to work. It will not compile the code
it writes because you will need to customize
the program statements that you want the
selected item to execute. But it will use
all of your other choices to display a look
alike menu prior to writing the code.
Colors menu
This menu consists of four color setting
routines.
set Item color
will bring up a dialogue box filled with
optional colors for your Foreground and
Background colors. Select choices, using the
{Tab} key to navigate, and press OK.
set hotkey color
will bring up a dialogue box filled with
optional colors for your Foreground and
Background colors. Select choices, using the
{Tab} key to navigate, and press OK.
set Highlight colors
will bring up a dialogue box filled with
optional colors for your Foreground and
Background colors. Select choices, using the
{Tab} key to navigate, and press OK.
set Box colors
will bring up a dialogue box filled with
optional colors for your Foreground and
Background colors. Select choices, using the
{Tab} key to navigate, and press OK.
Options menu
The Options menu gives you more customizing
choices for your menu.
Title string
allows you to name the menu that you are
creating. This string will appear
immediately above the menu box.
Box style
allows you to toggle between a single or
double lined box that will serve as a border
for your menu.
First key
allows you to choose Y if the first letter in
each menu item is to serve as the hotkey, or
N if you are going to designate specific
hotkeys in the Item listing using the &
character.
Immediate trigger
another Y / N choice to determine if the
hotkey should activate the item, or merely
move the highlight to that menu choice.
Shadow toggle
gives you the Y / N option to have drop
shadows appear under the menu box, or not.
Creating menu items
Press {Ins} to insert an item into your menu.
The items will begin to appear on screen
using the Color and Options choices you have
made. Press {Del} to delete an item from you
menu.
You will be able to see what your menu will
look like before your choices are cast into
an .EXE file. Neat!
You will need to load the .BLD file created
by MG.EXE into a text editor for final
modifications. When you've got everything
just the way you want it, Compile and Run it.
Don't feel bad if you make couple of changes
once you see how your color sections work
out. We don't want to see your name on the
"Mr. Blackwell's 10 Worst Dressed Computers"
lists.
ONLINE - the BUILDER Telecommunications Interface;
ONLINE is the telecommunications interface
that is provided with BUILDER 2.0. It allows
you to call into our BBS from within the
BUILDER IDE (even if you are right in the
middle of coding). This means that tech
support is just an {Alt, Space} {O} away.
The benefit to this special tool is that you
can easily log on to our BBS and upload or
download files that may be helpful to you or
to others. (Of course, ONLINE does require
you to have an operation modem properly
installed in your machine, and that the modem
is connected to an operating telephone line.)
What's ONLINE ACCESS?
By definition it is a telecommunications
interface that is integrated into the BUILDER
2.0 development environment. The existence
of this tools allows you to gain immediate
electronic entry to our BBS for tech support,
latest version downloading, example file
uploading and downloading, and anything else
you can think of. We've also provided you
with the ability to enter a telephone number
on the fly and call any other BBS' you see
fit.
As far as we know, BUILDER 2.0 is the only
programming language to offer this feature.
(We believe this will start a trend, NOT!)
ONLINE ACCESS unveiled
The use of ONLINE ACCESS is terribly simple.
Once you have selected {O} from the Tools
menu you will want to check your
configuration settings before actually
attempting to execute any of the other menu
options.
The default configuration settings will
appear when you activate the Configuration
option. They are:
Port - This refers to the com port
where your modem is installed. We
have defaulted to com port 1, but
your modem may be installed on com
port 2, 3, or 4. Please refer to
your modem documentation for
verification. (Note: a "failure to
initialize" error may indicate that
this setting is wrong)
Speed - This refers to your modem
speed. We have defaulted to 2400,
but you may choose 1200 or 9600
(please choose based on your
hardware).
BBS Number - This entry box is
sensitive to the keyboard, and
defaults to our current BBS
telephone number. It can be
changed with the Dial option, or
from this menu.
Save - Selecting Save will save all
of your other options to the CONFIG
file and redefine your defaults.
If you modify a setting and don't
Save before exiting, then the
defaults will be reset at exit from
the BUILDER IDE.
Having verified your Configuration, you now
operate this tool by selecting one of the
other menu choices.
Your options
There are no questions to answer, just
functions to execute. Let's take a look at
each of them:
Send
Selected if you desire to Send a file via
your modem to our BBS. The Send option will
open an input box and await keystroke entry.
When you have entered the file name (complete
with drive, directory, and extension
specifications) press {PageUp} to send the
file.
Receive
Selected if you desire to Receive (or get) a
file via your modem from our BBS. The
Receive option will open an input box and
await keystroke entry. When you have entered
the file name (complete with drive,
directory, and extension specifications)
press {PageDown).
Dial
Selected if you wish to override the default
telephone number that will be sent to the
modem for dialing. An input box will appear
and await keystroke entry. Upon completion,
press {Return} and the number will be dialed.
HangUp
Pressing {Alt, H} will immediately interrupt
your call by disconnecting the modem.
ShelltoDOS
Pressing {Alt S} will drop you to your DOS
prompt. This feature is only available
OFFLINE. This is helpful if you are
attempting to find or move a file, etc.
Configuration
Discussed above.
That's all there is to it. Handy, neat, and
clean. We hope that you'll use the ONLINE
ACCESS tool to gain more BUILDER programming
experience by downloading sample files,
sharing your ideas with other users, and
getting the electronic tech support you need.
HELPCOMP.EXE - the Help System compiler
Another unique feature of the BUILDER
compiled language is the ability to create a
help system for your BUILDER (or other)
applications. This help system is comprised
of a .HLP file containing the help data that
will be displayed when the help system is
activated from your application. The help
system you create will be accessible to your
user by pressing a developer defined hotkey.
{F1} is recommended as the help hotkey, as
most programs adhere to it as a standard.
The help system operates from a menu of
selectable items. For this reason, the help
system is easiest to use inside of BUILDER
created menu programs.
This is a two step development process with
specific technical applications. The first
step is to create the .HLP file, the second
step is to construct your BUILDER created
.EXE in such a way that it can call your .HLP
file.
Creating .HLP files
To create your .HLP system you must write the
screen displays that you want activated when
help items are chosen. The format for this
.TXT file (that will become the .HLP file) is
very stringent. It is:
#BEGIN Topic
Screen text of help topic.
More screen text.
Up to 50 lines of displayed text.
#END
Each topic you want available to your help
system must have a #BEGIN Topic, and a #END.
You may include as few as one, or as many
lines of text to display as will fit in the
Help boundries. The Help boundries you
establish when you compile your application
cannot exceed your screen size. These lines
should appear EXACTLY as you want them
displayed.
You needn't separate your Topic blocks with
blank lines. Each #BEGIN will clue the
HELPCOMP.EXE compiler that you are beginning
a new Topic. If HELPCOMP reads more than 50
lines without finding #END, it will assume
you made an error and halt operation telling
you that the error has occurred.
Below is a sample help text file that we will
compile together as a tutorial:
#BEGIN LOAD
LOAD:
Load any file from disk to memory.
This allows for editing and viewing.
#END
#BEGIN SAVE
SAVE:
Save the file in memory to diskette
for permanent storage. Remember to
do this often so your hard work will
not be lost!
#END
#BEGIN QUIT
QUIT:
Quit the world's greatest application
and return to the boring, but effective
DOS prompt.
#END
This help system is obviously for a menu that
allows for the choices LOAD, SAVE, or QUIT.
Larger systems would be formatted the same,
but include more Topics. The order of Topics
doesn't need to comply with the order that
those Topics appear on the help menu.
Creating HELP.HLPs
To run the data file that contains our screen
displays we need to add the Help command to
our executable program. HELPCOMP.EXE creates
.HLP files for this purpose. We recommend
that your .EXE and .HLP filenames contain the
same first eight characters, and differ only
by extension.
Let's look at the source code for the BUILDER
created .EXE that will run the help system
shown above. This is a simple implementation
of the .HLP file MENUHELP.HLP:
USE DIRECT
Help " Help System ","Menuhelp.hlp",{F1},16,60 @ 4, 10
Menu Style Blue,White,Red,White,White,Black,Black,White,0,0,1,1
cls Black on Cyan
' Keep displaying the menu until user presses
{Esc}
While not cancelled
' Run the subroutine Main
Main
end
'
Sub Main
DropDown "Simple Title" @ 10,35
Item "&LOAD"
Item "&SAVE"
Item "&QUIT"
Exit
end
end
This code is self explanatory. While this
file is active, moving the highlight (cursor)
to any selectable item and pressing the
designated hotkey, {F1} in this case, will
display a help window, titled "Help System"
in this case, and use MENUHELP.HLP as its
data file for screen display. Note that the
call to Help in our sample code designates
the size and placement of the help window.
Integrating into a HELP system
Type the following at the command line to
compile your help text file (MENUHELP.TXT)
into a help system data file:
HELPCOMP MENUHELP.TXT MENUHELP.HLP
Type the following at the command line to
compile your BUILDER source code file into an
executable profram:
BLD MENUHELP.BLD
Now run MENUHELP.EXE and move through your
menu choices pressing {F1} to view help on
the highlighted topic.
Linking multiple .OBJs
BUILDER 2.0 allows you to link multiple .OBJs
together into one .EXE. Some of the benefits
of this are:
1) Larger finished programs - instead
of the 64K .OBJ limit, you can
create .EXEs up to 1 megabyte.
2) Reusable .OBJs from one project to
the next.
3) Multiple language program creation.
For our purpose here, we'll illustrate the
linking of two BUILDER created .OBJs, FOO.OBJ
and FOO1.OBJ. The code for these files is
below:
'FOO.BLD
EXTERNAL SUB SAYHELLO
CLS
SayHello
Say "Back from the other obj"
'FOO1.BLD
SUB SayHello
Say "Hello from foo1"
end
Compile them from the commandline like this:
BLD -c FOO
BLD -c FOO1
Compiling with the -c switch will stop the
process after the creation of .OBJ files.
Link them together with MLINK.EXE from the
commandline like this:
MLINK FOO+FOO1,,,BLD.LIB
This will create FOO.EXE. Run it by typing
FOO at the commandline. Your screen should
clear and then display the following:
Hello from foo1
Back from the other obj
Congratulations, you can now create for
powerful and flexible BUILDER .EXEs!
SUBROUTINE value passing
BUILDER 2.0 allows values to be passed to and
returned from Subroutines. Let's modify the
previous example slightly to pass a string
for FOO1 to display:
'new improved FOO.BLD
EXTERNAL SUB SAYHELLO
CLS
SayHello "Hello from foo1"
Say "here we are back in foo"
' new improved FOO1.BLD
SUB SayHello string str1
Say str1
end
Compile FOO.BLD and FOO1.BLD from the
commandline as before, using the -c switch.
Link them again as before. Run FOO.EXE by
typing FOO at the commandline. Your screen
should clear and then the following should be
displayed:
Hello from foo1
here we are back in foo
The example above demonstrated passing a
value to a subroutine. Let's return a value
from a subroutine. Using the FOO files from
above make these changes:
' latest new improved FOO.BLD
EXTERNAL SUB SAYHELLO
Integer int1
CLS
int1 := SayHello "Hello from foo1"
Say "here we are back in foo"
Say "the returned value was ";int1
' latest new improved FOO1.BLD
SUB SayHello string str1
Say str1
Return 45
end
Compile and link these files as you have
before. Running FOO.EXE should now clear
your screen and display:
Hello from foo1
here we are back in foo
the returned value was 45
That does it for passing values to and from
subroutines. This feature can benefit your
applications dramatically, but requires you
to adhere strictly to the syntax and formats
that have been presented.
A more extensive discussion of linking
BUILDER .OBJs into other languages will be
available soon on hyperactivity, the
hyperkinetix BBS.
