D3 C Functions – Part 1: Confusing docs?

Isn’t the need for dm,bp,unix.h in Windows code "confusing"?

The %functions used for sockets make use of this statement:

include dm,bp,unix.h socket.h

That’s not confusing Unix and NT. All of the documentation for sockets originates from *nix / POSIX environments. Barring the exceptions noted above and a few others, the constants found in the socket.h item are exactly the same for NT and *nix, and many Windows (COM) developers use BSD / POSIX documentation to get syntax details. (Yes, I also refer to BSD docs for details on %functions used in D3NT.) This shouldn’t be surprising because there are obvious other similarities between DOS/Windows and its *nix ancestor, and if you’re doing inter-system communications it only makes sense that things need to be the same on both sides in order for everything to work.

For historical purposes the unix.h file can’t be changed to a more generic functions.h file – the change would break existing code, which is generally considered a sin that library providers "shalt not commit". It also makes no sense to duplicate the socket.h code item in a new winnt.h file – the redundant code would just be a maintenance hassle. A developer could easily create their own winnt.h file and copy the socket.h item there. But then there would be two code sets, one for each OS, and in most cases that’s not really necessary, even given the various details we’ve seen in this article. My socket code, for example, is exactly the same between OS platforms. I just check a WIN32 flag to see if I should execute the Windows code, otherwise I execute *nix code. Thankfully all %functions compile on all D3 platforms.

After all of that, if you still feel a need for RD to create a winnt.h file, then you probably don’t understand this code in the first place and probably shouldn’t be complaining that it’s *ix specific. Again, I don’t think this is the part labelled as "confused".

Inaccuracy results in confusion … but I’ll buy that only so far…

OK, the beginning of the C function section (this is the %function section) says "C functions can be called from a FlashBASIC program or subroutine in D3 UNIX implementations using a syntax similar to that of normal C." The very first page of that section doesn’t mention Windows at all which leads one to wonder where NT fits in – though the second page does mention NT. So slap that man at RD who writes their docs (he’d enjoy it), but if you haven’t read beyond the first page of the chapter then slap yourself too. Remember that this section of the doc hasn’t gone through a major overhaul since D3NT came out. The underlined text above was intended to separate Unix functionality from AP/Pro and AP/Native – that was long before D3NT was created.

On the topic of old text, you’ll find a lot of other notes in the "D3 v7.5" reference manual that haven’t been valid since AP/Native or AP/DOS v5.2. Is it confusing? I dunno, do you really need someone to tell you that User Exit u0039, which reads an absolute disk sector, probably won’t work on any current D3 system? For a new developer, I’d say this should be documented as a deprecated feature, for historical information purposes only. But for the people have been working with this system for 20 years, we just know better – and we should know better than to make a fuss about some %functions too.

In a wonderful bit of irony here, D3 v7.5 introduced two new functions: %shell and %shellcapture, and the documentation for %shell begins "For Windows: Not Supported … The %shell() function executes the MS-DOS command, command, and returns the exit code of the command." It’s tough to execute a DOS command from an NT-based product using a brand new feature that isn’t supported. This was obviously a typo and they intended this to say it wasn’t supported for Unix. I’m sorry, but if you’re confused by this and somehow expect a DOS command to work on Linux, then you really really shouldn’t even be looking at this documentation.

Since we’re here, I have v7.5 Beta notes that say "FlashBASIC runtime now supports controlling COM objects through OLE automation." But I don’t see that anywhere in the production docs. It would be helpful to have info on this, maybe to avoid the need to use %functions at all. If you can find info on this on-line, please post a link as a comment.