                             *** DPFLOAT 1.0 ***

                         by Detlef Pleiss and others

               Internet:   det@goliath.de
               Compuserve: 74101.755

This package is based on source code posted by Ronny Brodin, thanks Ronny!
Visual Basic 4.0 example provided by Stan Sainte-Rose, thanks Stan!

====================================================================
Files included in package:

DPFLT.TXT       - This Text
DPFLT_C.TXT     - Using DPFLOAT with C
DPFLT_VB.TXT    - Using DPFLOAT with Visual Basic
DPSOFT.TXT      - Information about DP Software Products
FILE_ID.DIZ     - Description of the Software

DLL\DPFLT.DLL   - 16bit Version of the DLL
DLL\DPFLT32.DLL - 32bit Version of the DLL

SRC\DPFLT.C     - C Source Code of the DLL

C\              - Source Code for Example Program in C
C\DPFLT.H       - Header File for DLL Functions
C\USERS.H       - Header File for PowerBBS USERS File Structure
C\DPFLT.LIB     - Link Library for the 16bit DLL
C\DPFLT32.LIB   - Link Library for the 32bit DLL
C\DPFLTTST.C    - Example Program Main Source

VB\             - Source Code for Example Program in Visual Basic
VB\DPFLT.BAS    - Function Definitions for the 16bit DLL
VB\DPFLT32.BAS  - Function Definitions for the 32bit DLL
VB\USERS.BAS    - PowerBBS USERS File Structure Definition
VB\DPFLTTST.FRM - Example Program Main Source
VB\DPFLTTST.VBP - Example Program Project File

====================================================================

Basics

PowerBBS data files contain some floating point values in a non-standard
format, which makes it hard for 3rd party developers to work with them.
DPFLOAT overcomes this problem as it offers functions to convert these values
to and from floating point values in IEEE format and to and from integer
format.

The floating point values used in PowerBBS data files are in particular:
(definitions taken from POWRDLL.H by Russel Frey as distributed with PowerBBS)

as part of "typedef struct _tagPowrUserRecord", the definition for one entry
in the USERS file:

    double        Today_Bytes;      // {Bytes downloaded TODAY}
    double        Download_Bytes;   // {Total bytes downloaded}
    double        Upload_Bytes;     // {Total bytes uploaded}
and
    double        downbytes_month;  // {total bytes downloaded/month}

Those "double" values are 8 bytes each, the (0 based, decimal) offsets into
the user record are:

Today_Bytes:     from  137 to  144
Download_Bytes:  from  145 to  152
Upload_Bytes:    from  153 to  160
downbytes_month: from 1175 to 1182

as part of "typedef struct _tagforum_data_options_record" which in turn is
part of the "typedef struct _tagPowrUser_Record_Extension" which defines the
structure of the entries in the USERS.2 file:

    float         Message_Pointer;

This "float" type has a size of 4 byte.

It looks like we would have to deal with two different floating point data
formats / sizes, but further investigation reveals that this is not the case.
It turns out that the last 4 bytes of a PBBS "double" have the same format
like a PBBS "float" while the first 4 bytes just add precision to the value.
The way PowerBBS uses the "double"s, this extra precision is not really
needed, so this DLL deals only with the "float" format, using just the last 4
bytes in case of a "double" value. In order to do so, you need to change your
programming language counterpart of POWRDLL.H so that the 8 byte "double"
values are split into two 4 byte values. In my C header file I have done so
like this:

  float         Dummy_Today_Bytes;      /* 137      originally 8 bytes double          */
  float         Today_Bytes;            /*    -144  Bytes downloaded TODAY             */

Whatever the types in your programming language are, the important point is
that both parts of the definition have a size of 4 bytes each, summing up to 8
bytes of the original definition. Repeat the same procedure for all four
"double" values in your header file.

When working with this definition, we do not really work with
"Dummy_Today_Bytes". When reading a value from the USERS file, we ignore the
"Dummy_Today_Bytes" part and only feed the last 4 bytes, "Today_Bytes" to
the conversion functions (which are explained below). When writing the result
of a conversion to the USERS file, we write it to the 4 byte "Today_Bytes"
variable as defined above and set the first 4 bytes, "Dummy_Today_Bytes" to
zero.

This way the conversion task is reduced to one format, the 4 byte "float"
format.

Note: When working with PowrBBS structure definitions, do *not* have your
compiler align them to word or long boundaries, by eventually adding pad bytes
between structure entries. This will not work as these pad bytes are not
really there in the files we work with. PowerBBS data / file structures *do*
have word or long values on uneven offsets, so any structure aligning /
padding optimization will break your program. One user entry in the USERS file
has a size of 1375 bytes. Check that the structure as you defined it in your
programming language results in this size, otherwise there is something wrong
with your definition and your program will not work.

====================================================================

Functions in the DLL

All functions in the DLL work with 4 byte values, so whatever the data types
involved may be called in your programming language, they have to be 4 byte
types to get things working. There are 4 functions in the DLL. 2 of them
convert PowerBBS "float" values into IEEE 4 byte floating point values and
vice versa. The other 2 functions convert PowerBBS "float" values into 4 byte
long integer values and vice versa. As PowerBBS uses the floating point format
for values that do not really have decimals, you will most likely want to use
the integer functions.
There is some loss of information involved in these conversion, but in
practice I think that doesn't matter, as how PowerBBS uses these values they
will most likely (hopefully <g>) never grow past the range of a long integer.

DPFLT_PBBSTOSINGLE
accepts a 4 byte "float" value in PBBS format as argument and returns a 4 byte
floating point value in IEEE format.

DPFLT_SINGLETOPBBS
accepts a 4 byte floating point value in IEEE format as argument and returns a
4 byte "float" value in PBBS format.

DPFLT_PBBSTOINT
accepts a 4 byte "float" value in PBBS format as argument and returns a 4 byte
long integer value.

DPFLT_INTTOPBBS
accepts a 4 byte long integer value as argument and returns a 4 byte "float"
value in PBBS format.

====================================================================

Calling Conventions

The 16bit version DPFLT.DLL exports the routines with names exactly as given
above. The 32bit version DPFLT32.DLL exports them with "Stdcall Name
Decoration", which is the standard for calling 32bit Windows API functions.
Whatever this may look like in your programming language, in both cases you
should be able to use function declarations similar to those that call Windows
API functions. In case the names as given above do not work in 32bit Windows,
these are the exact names that the 32bit DLL exports:
_DPFLT_PBBSTOSINGLE@4
_DPFLT_SINGLETOPBBS@4
_DPFLT_PBBSTOINT@4
_DPFLT_INTTOPBBS@4

====================================================================

License and Disclaimer

DPFLT is Freeware. You can use it as you see fit. You are allowed to use it in
commercial products without having to pay a fee to or mention the authors
(though it would be nice).
This package may be distributed freely as long as it remains in its unaltered
form. You may however distribute the DLL(s) as part of your product without
including other files from this package. If you do so, you must preserve the
names DPFLT.DLL and / or DPFLT32.DLL.
This software is provided as is. Detlef Pleiss and all other parties involved
disclaim all warranties, either expressed or implied, including but not
limited to implied warranties of merchantability, fitness for a particular
purpose. In no event will the authors be liable to you for damages, including
any loss of data, profits, lost savings, or other incidental or consequential
damages arising out of your use or inability to use the software. Use at your
own risk.
And backup your USERS and USERS.2 files!
