Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive   : BLI201.ZIP
Filename : READ.ME

READ.ME BLINKER 2.01 Update notes 92.07.24
------- ------------------------- --------


This maintenance update to Blinker 2.01 consists of this file READ.ME,
the EXE file BLIUPD.EXE, a UMB and XMS memory tester BLINKMEM.EXE and
a ZIP file of updated include files and example programs. The complete
set may be freely distributed on BBS's, disks or in any other form
(please include this READ.ME with it).

WHEN UNZIPPING THE SOURCE FILES PLEASE USE THE -D PARAMETER TO ENSURE
THAT THE FILES ARE PLACED IN THE CORRECT DIRECTORIES.

PLEASE READ THIS FILE IN ITS ENTIRETY AS IT WILL SAVE YOU TIME AND
EFFORT INSTALLING AND USING THE UPDATE.

Installing the update
---------------------

To install the update please change directory to the Blinker
directory, copy these files into the directory and then run BLIUPD by
typing BLIUPD at the DOS prompt.

Please ensure that the BLINKER.EXE present in this directory is
version 2.00, the program will NOT update any previous version of
BLINKER.

The program will display a message explaining that a the existing
file BLINKER.EXE will be renamed to BLIOLD.EXE and the new 2.01 file
BLINKER.EXE will be created in its place.

THIS PROGRAM WILL NOT UPDATE DEMONSTRATION OR BETA VERSIONS !!

This READ.ME contains IMPORTANT INFORMATION which is not available in
the manual. Please read this document before calling for technical
support. It describes last minute changes and additions to the BLINKER
manual and product made since the manual was printed. Where
differences occur, the information contained herein supersedes the
Norton Guide, which in turn supersedes the printed manual.

You may find it worthwhile to print and study this file before using
the product. There is a completely updated Norton Guide file which
contains the new commands, but we have repeated them below for the
benefit of those people who do not have a Norton Guide Reader.


General
-------

In addition to a number of bug fixes to the original release, this
maintenance release contains a number of new features detailed below.

The bug fixes include :

1. Running under MS Windows with EMS caching and OVERLAY PAGEFRAME
enabled.
2. Occasional problems returning from a SWPRUNCMD giving a 1220 error
(unable to allocate same segment).
3. CodeView was not working with BASIC PDS 7.1.
4. CHAIN and SPAWN commands were not working correctly.
5. Overlay manager no longer pulled in with Clipper 5.01 if no
non-Clipper code is overlaid.
6. Various small fixes.

DOS 5.0 UMBs are now fully supported in addition to XMS UMBs.

C files from Microsoft C versions prior to 7.0 may be recompiled with
Microsoft C/C++ 7.0 and linked with Blinker, but the new C++
extensions to the OBJ format are not yet supported and will be added
in Blinker 2.1 to be released as a free update when completed.

It should be noted that to use BASIC with Blinker the final program
must run as a separate EXE file, i.e. all modules must be compiled
with the /O option. When linking BASIC please compile the BASIC error
handler BAS\BLERRPRG.BAS for the appropriate string model (Near or
Far) and link it into the ROOT of the program.

Three new functions BLIDEMDTEFOR (), BLIERRPRMFOR (), BLISERNUMFOR ()
have been added to support the Blinker functions which return strings
to FORCE.


Swap system additions
---------------------

There are five additional swap system functions which are not mentioned
in the manual.

SWPSETENV()

Function: Set environment variables

Syntax: lsuccess = SWPSETENV(cString)

Return: True if cString < 512 bytes long, false otherwise

SWPSETENV() allows the parent process to Add / Amend / Delete
environment strings. The parameter to SWPSETENV() is a single string
containing all the variables to be set. Each variable is separated
from the next by a delimiter character CHR(255), rather than NULLs
which could cause a problem for C programmers. You do not need a
CHR(255) at the end of the string. If you need a CHR(255) in the
string, specify two in a row.

example:

str := "PROMPT=<$p$g"+CHR(255)+"SWAPPED=TRUE"
SWPSETENV(str)

this example will change the prompt, and add (or change) the 'SWAPPED'
environment variable.

str := "CLIPPER="+CHR(255)+"BLINKER=/OP1"
SWPSETENV(str)

this example will DELETE the 'CLIPPER' environment variable, and
change / add the 'BLINKER' variable.

Note that these environment changes are only set at the time the swap
is executed, and apply only to the child's environment, NOT the
parent's copy.

YOU DO NOT NEED TO USE SWPADDENV() TO INCREASE THE ENVIRONMENT SIZE OF
THE CHILD PROCESS TO ACCOMODATE THE NEW STRINGS SET WITH SWPSETENV(),
IT IS DONE AUTOMATICALLY FOR YOU.

Use of this function will increase the size of the kernel in memory by
an amount equal to the size of the new environment.

The total amount of data that you can pass to this function is 511
bytes.


SWPADDENV()

Function: Increase size of child environment

Syntax : niValue = SWPADDENV(nBytes)

Return: The previous setting

SWPADDENV() allows you to specify how much space should be added to
the child process environment block. This will allow batch files, etc
to create environment variables without running out of environment
space.

example:

lastsetting = SWPADDENV(256)

will make 256 bytes of space available in the child environment. Use
of this function will not result in an increase in the size of the
swap function kernel.


SWPEMS320()

Function: Limit the swapper to using EMS 3.2 calls

Syntax : lValue = SWPEMS320(lvalue)

Return: The previous setting

Some offbeat/OEM EMS emulators have been giving some problems with the
swapper's use of EMS 4.0 level functions that appear to be improperly
implemented in the affected drivers. This function can be used to
force the swapper to only use EMS 3.2 functions.

example:

SWPEMS320(.T.) // use only EMS 3.2 calls.

This function will not be needed in most cases.


SWPFREEMS

Function : Specify amount of EMS to be left free

Syntax : niValue = SWPFREEMS(niValue)

Return : The previous setting

This function can be used to limit the amount of EMS used by the swap
system for program image storage, so that the specified amount can be
left free for the child program.

Example :

SWPUSEEMS(TRUE) // enable use of EMS
SWPFREEMS(512) // but leave at least 512K free


SWPFREXMS

Function : Specify amount of XMS to be left free

Syntax : niValue = SWPFREXMS(niValue)

Return : The previous setting

This function can be used to limit the amount of XMS used by the swap
system for program image storage, so that the specified amount can be
left free for the child program.

Example :

SWPUSEXMS(TRUE) // enable use of XMS
SWPFREXMS(512) // but leave at least 512K free


Swap function error codes

The SWPRUNCMD function returns a numeric result code to the calling
program following the swap. If the error occurs following the
execution of the child process, and the parent program image cannot be
restored correctly, an error message will be displayed detailing the
error and the error number that occurred, and the swap function will
exit to DOS.

Normally such errors are reported through the swap function error
functions SWPERRMAJ() and SWPERRMIN(), however, in the case that the
program cannot be restored to memory, as 1220 error will be output,
and the program will return to DOS.

The following major error codes have the following meanings (and text
messages when fatal):

0 No error
1 Disk full
2 * File Not found
3 * Disk I/O error
4 Change directory error
5 Temporary file creation error
6 Change drive error
7 * EMS error
8 * XMS error
9 SHELL error
10 Handle table too large to save
11 + Top of memory error
12 + MCB chain corrupt
13 Too many MCBs
14 * DOS memory function call error
15 + Unable to allocate same segment
16 Unable to find COMSPEC in enviroment
254 + Swap internal error
255 + Swap internal error

Errors marked with a (+) are always fatal and will result in a 1220
error message. Errors marked (*) may result in a 1220 message, or may
be non-fatal depending on when the error occurs in the swap process.

Errors that are not marked with either (+) or (*) are non fatal (and
will not result in a 1220 message), but the child process will not
have been executed. These errors can be detected through the
SWPERRMAJ() and SWPERRMIN() functions (see Chapter 7).

The explanation for each error is as follows:

0 - No error

A major error of zero indicates that the swap function successfully
executed the command interpreter, and restored the program image.

Normally a minor error code of zero will be returned, however, in the
case that the swap function had to remove a TSR from memory, the minor
error code will be set to 1, purely for informational purposes.

In the case that the size of DOS memory increased during the swap (by
executing a program such as Quarterdeck's VIDRAM) the minor error code
returned will be 2. Users should be STRONGLY discouraged from
executing such programs during the swap. Please note that a decrease
in DOS memory through the use of such a utility will result in a fatal
error (code 11).

1 - Disk full

The disk on which the swap function was attempting to save the program
image is full.

The minor error code is the associated DOS error code.

2 - File Not found

DOS returned a 'file not found' error when the swap function attempted
to restore the program image from a disk swap file. The swap file may
have been deleted.

The minor error code is the associated DOS error code.

3 - Disk I/O error

DOS returned an unexpected error while the swap function was either
reading from or writing to the disk file containing the program image.

The minor error code is the associated DOS error code.

4 - Change directory error

The swap function encountered an error either when changing to the
requested directory passed as a parameter to the swap function, or
when restoring the current directory following the swap.

The minor error code is the associated DOS error code.

5 - Temp file create error

DOS returned an error when the swap function attempted to create a
temporary file to store the program image. Check that the path
specified for the temporary file is valid.

The minor error code is the associated DOS error code.

6 - Change drive error

The swap function encountered an error either when changing to the
requested drive passed as a parameter to the swap function, or when
restoring the current drive following the swap.

The minor error code is the associated DOS error code.

7 - EMS error

An unexpected error occurred during an EMS operation.

The minor error code is the EMS function call that failed.

8 - XMS error

An unexpected error occurred during an XMS operation.

The minor error code is the XMS function call that failed.

9 - SHELL error

The swap function was unable to execute the command interpreter. Check
that the COMSPEC environment variable was set to point to the command
interpreter.

The minor error code is the associated DOS error code.

10 - Handle table too large to save

The swap function can only save an expanded handle table that contains
255 (or less) handles.

The minor error code is the number of handles in the current handle table,

11 - Top of memory error

The top of DOS memory was at a lower address following the swap than
it was before the swap. Do not execute programs like Quarterdeck's
VIDRAM utility while a program is swapped out.

The minor error code is the segment address of top of memory.

12 - MCB chain corrupt

The swap funtion detected that the DOS memory control block chain was
corrupted.

The minor error code is the segment address of the corrupted MCB.

13 - Too many MCBs

The swap function can only save programs that own 128 or less DOS
memory control blocks, which is more than sufficient in most cases.

The minor error code is the number of MCBs.

14 - DOS memory function call error

DOS returned an error on a memory related function call. Please
contact technical support with full details of the situation causing
this error.

The minor error code is the associated DOS error code.

15 - Unable to allocate same segment

In order to restore the program image correctly, the swap function
must be able to allocate the same memory blocks that the program
originally owned. This message indicates that DOS returned a block at
a different address than the swap function expected. The program
cannot be correctly restored.

The minor error code is the segment address returned by DOS.

16 - Unable to find COMSPEC in enviroment

The swap function needs to locate the command interpreter (usually
COMMAND.COM) in order to execute the child process. This error
indicates that the COMSPEC environment variable that specifies the
location of the command interpreter could not be found. Make sure you
have a valid COMSPEC settting in the environment.

254 - Swap internal error

Please contact technical support with full details of the situation
causing this error.

255 - Swap internal error

Please contact technical support with full details of the situation
causing this error.


Functions for other swappers
----------------------------

Overlay () and Dr Switch work fine, but with other swappers it is
necessary to unhook the overlay manager before the swap and to rehook
it afterwards. 2.01 now has 2 functions BLIUNHOOK and BLIREINIT (with
preceding underscores for C and ASM etc.) which perform this function
(no parameters).

e.g. or
BLIUNHOOK (); BLIUNHOOK ()
SWAP (....); HOLDEVCL (....)
BLIREINIT (); BLIREINIT ()

Please note that these calls are *NOT* required when using the built
in swap function, SWPRUNCMD().


Error messages
--------------

1220: swap error [major/minor] (text message)

This message indicates that a fatal error has occurred in the
Blinker swap system. The error consists of a major error number and
an associated minor error number [major/minor] and a text message
indicating the type of error that occurred. This error is non
recoverable, and is not processed through the Blinker error handler.

Please review the previous section for a complete list of the swap
system error codes.


Turbo Debugger support
----------------------

Limited support consists of module source code with line
numbers, public data symbols and non-overlaid public code
symbols. We do not currently support overlaid code under
the Turbo Debugger, but plan to in a subsequent release.
TDCONVRT handles non-overlaid programs fine.
If a program contains C or ASM overlays then the -c option
must be used to create an external .TDS file, otherwise a
Blinker 1203 error will occur at run time. This is
because TDCONVRT places the debugging information
directly after the root of the .EXE file. It also creates
unusually large .TDS files with overlaid programs due to
some internal confusion, but they appear to function
correctly for the root part of the program.
Overlaid programs will otherwise run correctly, but
breakpoints on overlaid code will be ignored and display
meaningless code at the symbol addresses.
Turbo Debugger does not currently recognise the _main symbol
as output from Blinker and TDCONVRT, so when running a
program under the debugger select GOTO (Ctl G) and enter
"main" to locate the start of the program.


Stony Brook Compilers
---------------------

The compiler run time libraries, and any libraries produced by the
Stony Brook librarian must be SEARCHed. Use of the LIB command on
these libraries will result in an internal Blinker error 1191: invalid
library number. Alternatively, the libraries may be rebuilt using the
Microsoft librarian (LIB.EXE).

When using overlays, the startup module must be in the root.

Modula 2
--------

When using overlays, compile using the LARGE model:

m2 myprog.mod /CODE:L

Pascal+
-------

When using overlays, compile using the LARGE model, and place
constants in a separate segment:

ppc myprog.pas //CODE:L //CONSTANT:L