Board index » delphi » Delphi *.hlp files still not done

Delphi *.hlp files still not done

Borland has officially released the latest versions of the following
*.hlp files for Delphi 2.0:

Cwg.hlp, Dbexplor.hlp, Delphi.hlp, Ibctrls.hlp, Imagedit.hlp,
Obpascal.hlp,  Vcl.hlp,  and Win32.hlp

They can be downloaded from Borland's WWW site at
http://www.borland.com/TechInfo/delphi/index.html by clicking the
"What's New" button.

There's one major problem, however. The Win32.hlp file shows all the
Win32 API calls in C, not Object Pascal. If Borland had stuck to an
exact translation of the C calls to Object Pascal, that would not be a
problem. However, Borland decided to implement some API calls differently
than is documented in C, and not let anyone in the developer community
know about it!

Here's an example.

The Delphi Win32.hlp file describes the ReadFile function as:

"The ReadFile function reads data from a file, starting at the
position indicated by the file pointer. After the read operation has
been completed, the file pointer is adjusted by the number of bytes
actually read, unless the file handle is created with the overlapped
attribute. If the file handle is created for overlapped input and
output (I/O), the application must adjust the position of the file
pointer after the read operation.

BOOL ReadFile(
    HANDLE  hFile,      // handle of file to read
    LPVOID  lpBuffer,   // address of buffer that receives data  
    DWORD  nNumberOfBytesToRead,        // number of bytes to read
    LPDWORD  lpNumberOfBytesRead, // address of number of bytes read
    LPOVERLAPPED  lpOverlapped  // address of structure for data
   );  

Parameters

hFile - Identifies the file to be read. The file handle must have been
created with GENERIC_READ access to the file.

lpBuffer - Points to the buffer that receives the data read from the
file.

nNumberOfBytesToRead - Specifies the number of bytes to be read from
the file.

lpNumberOfBytesRead - Points to the number of bytes read.  

lpOverlapped - Points to an OVERLAPPED structure."

If one were to look at this documentation, one would assume that the
following code would work:

PROCEDURE ReadTheFile;
VAR
   hFile       : THANDLE ;
   Buffer      : Array [0..127] of CHAR ;
   pBuffer     : PCHAR ;
   BytesMoved  : DWORD ;
   pBytesMoved : PDWORD ;
BEGIN
   hfile :=  CreateFile( FileName,GENERIC_READ,0,
                         NULL,OPEN_EXISTING,
                         FILE_ATTRIBUTE_NORMAL,NULL )

  { Next line results in a compile error }
   ReadFile( hFile,@Buffer,sizeof(Buffer),@BytesMoved,nil ) ;

  { Next lines compile ok, but yields access violations at run time }
  pBuffer := @Buffer ;
  pBytesMoved := @BytesMoved;
  ReadFile( hFile,pBuffer,sizeof(Buffer),pBytesMoved,nil ) ;

  { Next line is what must be used to work correctly }
  ReadFile( hFile,Buffer,sizeof(Buffer),BytesMoved,nil ) ;
END ;

Buffer itself must be passed as the second parameter, and BytesMoved
itself must be passed as the fourth parameter, in direct contradiction to
the Win32.hlp file that documents this call. The documentation states that
the second and fourth parameters are both pointers.

Yesterday, I spoke with Tim, a technician at Borland's Delphi help
line, and he told me that Borland was aware that many functions do not
behave exactly as documented, and suggested that if in doubt, a
developer should consult the Windows.PAS source file.

Unfortunately, when we were working on named pipes under Windows NT
3.51, and had problems with access violations, we did not consult the
Windows.PAS file for help. Instead, we called Borland's tech support
line, and acutally faxed them source code that we were having problems
with. We implemented the ReadFile function as in example 2 above. No
one at Borland ever called back to say "oh, your ReadFile function
needs the buffer, not a pointer to the buffer." No one called back
EVER!!!!

We decided to write a C++ DLL to implement named pipes, and leave it
at that. We never would have discovered that our problem was in the
way we implemented ReadFile except for the fact that we tried to open
and read a file on disk, and ran into similar access violations. It
was then that we looked at the Windows.PAS file and saw that Borland's
implementation of ReadFile looked like this:

function ReadFile(hFile: THandle;
                            var Buffer;
                            nNumberOfBytesToRead: DWORD;
                            var lpNumberOfBytesRead: DWORD;
                            lpOverlapped: POverlapped): BOOL; stdcall;

Note the second and fourth parameters. Neither is a pointer as stated
in the online documentation.

I am an experienced C developer and have only been working with Delphi for
the last 8 months or so, and I am willing to concede the fact that my
Pascal is more than a little rusty. I depend on documenation to ease the
learning curve. If I read in the online docs that a function is
implemented in a certain way, then that function should be implemented
that way. If the docs are wrong, then Borland must fix the docs.

Tim, the Borland guy I talked to, told me that when Delphi 3.0 ships,
things are going to be great! I don't have time to wait. My client is
shipping product built with Delphi 2.0 now!

One thing that amazes me is that Borland can post lawyer jokes on the WWW
page, yet cannot find the time nor resources to maintain proper
documentation for their flagship product. Is this what happens when
Borland ousts Phillipe?

When my current contract is up, and my next client asks for a
recommendation for a development platform, I certainly will NOT recommend
Delphi 2.0. I'll tell them to wait until 3.0 ships.

Mike Lastort
Software Engineer/Computer Consultant
mlast...@csti-md.com

 

Re:Delphi *.hlp files still not done


Quote
Jan Lastort (janl...@access.digex.net) wrote:

<snip>

: Yesterday, I spoke with Tim, a technician at Borland's Delphi help
: line, and he told me that Borland was aware that many functions do not
: behave exactly as documented, and suggested that if in doubt, a
: developer should consult the Windows.PAS source file.

Seems like good sense to me. Using all the tools at your disposal.
You paid for the source, after all, why not use it.

<snip>

: Note the second and fourth parameters. Neither is a pointer as stated
: in the online documentation.

: I am an experienced C developer and have only been working with Delphi for
: the last 8 months or so, and I am willing to concede the fact that my
: Pascal is more than a little rusty. I depend on documenation to ease the
: learning curve. If I read in the online docs that a function is
: implemented in a certain way, then that function should be implemented
: that way. If the docs are wrong, then Borland must fix the docs.

If you have the source, why didn't you just check windows.pas in the
first place? Not to excuse Borland's mistakes, but the answer
was right there all the time. On the other hand, the source *is*
sort of 'out-of-the-way'.

Actually, I think this points out the undesirable separation between
docs and source. Souce code is often superior to documentation, since
documentation can easily get far out of sync with the code. Docs
are useful for elaboration, but the source is more useful as a
canonical source of information. It'd be great if F1 searching
could search through WinHelp *and* source code files. Problems
like Jan's would be solved in much less time if the source code
were rapidly searchable.

Re:Delphi *.hlp files still not done


I do this simple trick to get around:  I load the windows.pas source
code and see how the procedures and functions are defined.

Benson
ben...@primenet.com

On Tue, 21 May 1996 13:32:12 -0400, Jan Lastort

Quote
<janl...@access.digex.net> wrote:
>Borland has officially released the latest versions of the following
>*.hlp files for Delphi 2.0:

>Cwg.hlp, Dbexplor.hlp, Delphi.hlp, Ibctrls.hlp, Imagedit.hlp,
>Obpascal.hlp,  Vcl.hlp,  and Win32.hlp

>They can be downloaded from Borland's WWW site at
>http://www.borland.com/TechInfo/delphi/index.html by clicking the
>"What's New" button.

>There's one major problem, however. The Win32.hlp file shows all the
>Win32 API calls in C, not Object Pascal. If Borland had stuck to an
>exact translation of the C calls to Object Pascal, that would not be a
>problem. However, Borland decided to implement some API calls differently
>than is documented in C, and not let anyone in the developer community
>know about it!

>Here's an example.

>The Delphi Win32.hlp file describes the ReadFile function as:

>"The ReadFile function reads data from a file, starting at the
>position indicated by the file pointer. After the read operation has
>been completed, the file pointer is adjusted by the number of bytes
>actually read, unless the file handle is created with the overlapped
>attribute. If the file handle is created for overlapped input and
>output (I/O), the application must adjust the position of the file
>pointer after the read operation.

>BOOL ReadFile(
>    HANDLE  hFile,  // handle of file to read
>    LPVOID  lpBuffer,       // address of buffer that receives data  
>    DWORD  nNumberOfBytesToRead,    // number of bytes to read
>    LPDWORD  lpNumberOfBytesRead, // address of number of bytes read
>    LPOVERLAPPED  lpOverlapped      // address of structure for data
>   );      

>Parameters

>hFile - Identifies the file to be read. The file handle must have been
>created with GENERIC_READ access to the file.

>lpBuffer - Points to the buffer that receives the data read from the
>file.

>nNumberOfBytesToRead - Specifies the number of bytes to be read from
>the file.

>lpNumberOfBytesRead - Points to the number of bytes read.  

>lpOverlapped - Points to an OVERLAPPED structure."

>If one were to look at this documentation, one would assume that the
>following code would work:

>PROCEDURE ReadTheFile;
>VAR
>   hFile       : THANDLE ;
>   Buffer      : Array [0..127] of CHAR ;
>   pBuffer     : PCHAR ;
>   BytesMoved  : DWORD ;
>   pBytesMoved : PDWORD ;
>BEGIN
>   hfile :=  CreateFile( FileName,GENERIC_READ,0,
>                         NULL,OPEN_EXISTING,
>                         FILE_ATTRIBUTE_NORMAL,NULL )

>  { Next line results in a compile error }
>   ReadFile( hFile,@Buffer,sizeof(Buffer),@BytesMoved,nil ) ;

>  { Next lines compile ok, but yields access violations at run time }
>  pBuffer := @Buffer ;
>  pBytesMoved := @BytesMoved;
>  ReadFile( hFile,pBuffer,sizeof(Buffer),pBytesMoved,nil ) ;

>  { Next line is what must be used to work correctly }
>  ReadFile( hFile,Buffer,sizeof(Buffer),BytesMoved,nil ) ;
>END ;

>Buffer itself must be passed as the second parameter, and BytesMoved
>itself must be passed as the fourth parameter, in direct contradiction to
>the Win32.hlp file that documents this call. The documentation states that
>the second and fourth parameters are both pointers.

>Yesterday, I spoke with Tim, a technician at Borland's Delphi help
>line, and he told me that Borland was aware that many functions do not
>behave exactly as documented, and suggested that if in doubt, a
>developer should consult the Windows.PAS source file.

>Unfortunately, when we were working on named pipes under Windows NT
>3.51, and had problems with access violations, we did not consult the
>Windows.PAS file for help. Instead, we called Borland's tech support
>line, and acutally faxed them source code that we were having problems
>with. We implemented the ReadFile function as in example 2 above. No
>one at Borland ever called back to say "oh, your ReadFile function
>needs the buffer, not a pointer to the buffer." No one called back
>EVER!!!!

>We decided to write a C++ DLL to implement named pipes, and leave it
>at that. We never would have discovered that our problem was in the
>way we implemented ReadFile except for the fact that we tried to open
>and read a file on disk, and ran into similar access violations. It
>was then that we looked at the Windows.PAS file and saw that Borland's
>implementation of ReadFile looked like this:

>function ReadFile(hFile: THandle;
>                            var Buffer;
>                            nNumberOfBytesToRead: DWORD;
>                            var lpNumberOfBytesRead: DWORD;
>                            lpOverlapped: POverlapped): BOOL; stdcall;

>Note the second and fourth parameters. Neither is a pointer as stated
>in the online documentation.

>I am an experienced C developer and have only been working with Delphi for
>the last 8 months or so, and I am willing to concede the fact that my
>Pascal is more than a little rusty. I depend on documenation to ease the
>learning curve. If I read in the online docs that a function is
>implemented in a certain way, then that function should be implemented
>that way. If the docs are wrong, then Borland must fix the docs.

>Tim, the Borland guy I talked to, told me that when Delphi 3.0 ships,
>things are going to be great! I don't have time to wait. My client is
>shipping product built with Delphi 2.0 now!

>One thing that amazes me is that Borland can post lawyer jokes on the WWW
>page, yet cannot find the time nor resources to maintain proper
>documentation for their flagship product. Is this what happens when
>Borland ousts Phillipe?

>When my current contract is up, and my next client asks for a
>recommendation for a development platform, I certainly will NOT recommend
>Delphi 2.0. I'll tell them to wait until 3.0 ships.

>Mike Lastort
>Software Engineer/Computer Consultant
>mlast...@csti-md.com

Re:Delphi *.hlp files still not done


Quote
> If you have looked, it is quite normal for borland to pass the pointers
> automagically via the 'VAR' directive.  Simple rule, when ever the C code
> EXPLICITLY requires an address, the 'VAR' directive is used in pascal.  This
> goes ALL the way back to TP for Windows.

>         I fail to see why borland would cripple itself to use poor C calling
> conventions, nor do I see where you would expect it.

   This "problem" (as you see it) is the basis of Pascal's parameter
conventions - Pascal has 2 options; C has only 1.  This is a strength of
the Pascal language, whereby you can control what a subprogram does to
data values passed to it, and most Pascal programmers consider this an
advantage.  Pascal parameters can be either the address of a _copy_ of
the variable or the address of the variable itself - helping to prevent a
poorly-coded/designed subprogram from altering the program's data.  This
capability is part of Pascal's strong data typing, which most Pascal
users consider better than C's...
   The issue is not that Borland did or didn't do something diferent or
wrong; it's that that Delphi and all Borland Pascal products follow the
Pascal language standard in such areas.

Re:Delphi *.hlp files still not done


If you have looked, it is quite normal for borland to pass the pointers
automagically via the 'VAR' directive.  Simple rule, when ever the C code
EXPLICITLY requires an address, the 'VAR' directive is used in pascal.  This
goes ALL the way back to TP for Windows.

        I fail to see why borland would cripple itself to use poor C calling
conventions, nor do I see where you would expect it.  Truthfully, whenever I
find a discrepency between the help file and reality, I consult THE SOURCE
CODE.  \program files\borland\delphi 2.0\source\rtl\win\Windows.PAS

I admit to being sadly dissapointed by the help files also, but I would have
been a hell of a lot more dissapointed by waiting 4 extra months just becuase
of some help files. If I had known that was why a product was delayed, I would
ask for the compiler first, documentation to follow.  Wouldn't you?  Be glad
they are at least shipping upgrades for the help files.

If you require someone to translate C to Pascal, or assist you in your porting
to Delphi, call me.  Dippy Doo Utilities would be more than willing to provide
assistance under favorable conditions.  We have a 10 year history using
multiple languages, including C, pascal, VB and Delphi.

And on that note : be glad yer not working in VB.  You think that Borland's
documents are lousy?  You should see what MS is *PROUD* to call
documentation.,.,

Have fun!

Good coding!

Clinton R. Johnson
Dippy Doo Utilities
xe...@canuck.com

Re:Delphi *.hlp files still not done


Quote
ben...@primenet.com (Benson Trinh) wrote:
>I do this simple trick to get around:  I load the windows.pas source
>code and see how the procedures and functions are defined.

Where is this file normally installed?  I just searched the drive
where I have Delphi installed and didn't find it.  (I didn't do a full
install on this system so that could be the problem).

Take Care, Zack Jones
z...@hom.net

Re:Delphi *.hlp files still not done


Quote
xe...@canuck.com (xepol) wrote:

| If you have looked, it is quite normal for borland to pass the pointers
| automagically via the 'VAR' directive.  Simple rule, when ever the C code
| EXPLICITLY requires an address, the 'VAR' directive is used in pascal.  This
| goes ALL the way back to TP for Windows.

|       I fail to see why borland would cripple itself to use poor C calling
| conventions, nor do I see where you would expect it.  Truthfully, whenever I
| find a discrepency between the help file and reality, I consult THE SOURCE
| CODE.  \program files\borland\delphi 2.0\source\rtl\win\Windows.PAS

Ok using your technique for calling, could you please tell me the
exact calling for NetAccessGetInfo (please include definitions of all
types used in the call).

C.L.Burke

Re:Delphi *.hlp files still not done


Quote
z...@hom.net (Zack Jones) wrote:
>ben...@primenet.com (Benson Trinh) wrote:

>>I do this simple trick to get around:  I load the windows.pas source
>>code and see how the procedures and functions are defined.

>Where is this file normally installed?  I just searched the drive
>where I have Delphi installed and didn't find it.  (I didn't do a full
>install on this system so that could be the problem).

>Take Care, Zack Jones
>z...@hom.net

You either have Delphi Desktop or you didn't Install the VCL Source
Code if it's not in your "\Program Files\Borland\Delphi
2.0\Source\RTL\WIN" Directory.

Brad Huggins

Re:Delphi *.hlp files still not done


Zack,
        You need to have the source code for Delphi 2.0 (which comes
with Developer version and above).  If you do, it is located in
..\Source\RTL\Win

Benson
ben...@primenet.ocm

Quote
On Thu, 23 May 1996 16:39:22 GMT, z...@hom.net (Zack Jones) wrote:
>ben...@primenet.com (Benson Trinh) wrote:

>>I do this simple trick to get around:  I load the windows.pas source
>>code and see how the procedures and functions are defined.

>Where is this file normally installed?  I just searched the drive
>where I have Delphi installed and didn't find it.  (I didn't do a full
>install on this system so that could be the problem).

>Take Care, Zack Jones
>z...@hom.net

Re:Delphi *.hlp files still not done


Quote
bhugg...@itctel.com (Brad Huggins) wrote:
>You either have Delphi Desktop or you didn't Install the VCL Source
>Code if it's not in your "\Program Files\Borland\Delphi
>2.0\Source\RTL\WIN" Directory.

I have the developer edition -- I don't think I installed the VCL
source.  I'll try that.  Thanks for the info.

Take Care, Zack Jones
z...@hom.net

Re:Delphi *.hlp files still not done


Quote
z...@hom.net (Zack Jones) wrote:
>ben...@primenet.com (Benson Trinh) wrote:

>>I do this simple trick to get around:  I load the windows.pas source
>>code and see how the procedures and functions are defined.

>Where is this file normally installed?  I just searched the drive
>where I have Delphi installed and didn't find it.  (I didn't do a full
>install on this system so that could be the problem).

>Take Care, Zack Jones
>z...@hom.net

You either have Delphi Desktop or you didn't Install the VCL Source
Code if it's not in your "\Program Files\Borland\Delphi
2.0\Source\RTL\WIN" Directory.

Brad Huggins

Re:Delphi *.hlp files still not done


On Fri, 24 May 1996 01:02:53 GMT, bhugg...@itctel.com (Brad Huggins)
wrote:

Quote
>z...@hom.net (Zack Jones) wrote:
>>Where is this file normally installed?  I just searched the drive
>>where I have Delphi installed and didn't find it.  (I didn't do a full
>>install on this system so that could be the problem).
>You either have Delphi Desktop or you didn't Install the VCL Source
>Code if it's not in your "\Program Files\Borland\Delphi
>2.0\Source\RTL\WIN" Directory.

It's on the Desktop CDROM in the

\runimage\delphi20\source\rtl\win

directory.  I don't know if it gets automatically installed or not.

Duncan Murdoch

Re:Delphi *.hlp files still not done


Zack,
        You need to have the source code for Delphi 2.0 (which comes
with Developer version and above).  If you do, it is located in
..\Source\RTL\Win

Benson
ben...@primenet.ocm

Quote
On Thu, 23 May 1996 16:39:22 GMT, z...@hom.net (Zack Jones) wrote:
>ben...@primenet.com (Benson Trinh) wrote:

>>I do this simple trick to get around:  I load the windows.pas source
>>code and see how the procedures and functions are defined.

>Where is this file normally installed?  I just searched the drive
>where I have Delphi installed and didn't find it.  (I didn't do a full
>install on this system so that could be the problem).

>Take Care, Zack Jones
>z...@hom.net

Re:Delphi *.hlp files still not done


Quote
bhugg...@itctel.com (Brad Huggins) wrote:
>You either have Delphi Desktop or you didn't Install the VCL Source
>Code if it's not in your "\Program Files\Borland\Delphi
>2.0\Source\RTL\WIN" Directory.

I have the developer edition -- I don't think I installed the VCL
source.  I'll try that.  Thanks for the info.

Take Care, Zack Jones
z...@hom.net

Other Threads