<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
