D3 C Functions – Part 1: Confusing docs?

Is a %function Supported or Not?

I find no confusion in the doc anymore regarding which %functions work with which OS, though in pre-v7.5 manuals there were few references to OS-specific concerns. All of the %functions now have "For Windows: Not Supported" where appropriate. But let’s consider for a moment what "Not Supported" means.

The %bind and %accept and related socket server functions are "Not Supported" for Windows, but they do work to some extent. If you’re not familiar with what a socket is then check out these pages:

  • link Nebula R&D article "What are Sockets?"
  • link WikiPedia Berkley_sockets

Even if something technically seems to work, a vendor may not be willing to support the feature in production use. Fair enough – they know it’s not suitable for live use so they’re telling us they can’t or won’t support it. That is, they won’t process bug or enhancement requests on unsupported features, at all or perhaps just not with the same priority, because they are already aware of the issues and have made a decision to not change the code.

As to why these functions can’t be used to create a socket server, see Part 2 of this mini series on C Functions. (Coming soon…)

What’s important for this discussion is that at least RD tells us the feature is Not Supported. So again, I personally don’t see confusion here.

What about syntax that’s different between OS platforms?

For functions where the syntax is different between Unix and Windows, the Ref doesn’t even mention the Windows versions, so it’s not "confused", it’s simply incomplete. Examples include these NT vs *nix functions used for socket clients as well as servers:

  • %recv vs %read
  • %send vs %write
  • %closesocket vs %close

Part of the reason for doc information missing in this area is that NT came along after *nix, and quite simply no one at RD got around to writing doc updates for this area. While it miffs me a little that the doc is missing critical information for D3NT developers, the underlying definition of these %functions is that they "should" implement whatever feature is supported by the host OS, except where RD specifically says they won’t support it. If you don’t know what those functions are then you probably shouldn’t use them.

How do you know what they are if they’re not documented in the Ref? You’re dealing with C functions, read C documentation. You aren’t invoking Pick functions, you’re executing instructions in the operating system. Here are some links to C documentation:

  • link Introduction to network functions in C
  • link IPC:Sockets
  • link Developer project A reusable Windows socket server class
    (Yes, we can do complex things like this with MV, and I have)
  • link Microsoft COM Winsock
  • link Microsoft .NET: Same Socket, Different Day
  • link BASIC C Socket Programming In Unix For Newbies

Another reason that we don’t see Windows syntax of some functions is that the difference in OS support for various functions is not merely a matter of syntax. The Windows and *nix operating systems frequently implement similar features in a completely different way, or simply don’t support features found in the other.

For example, none of the semaphore functions or process handlers will work in NT (%semctl, %semget, %semop, %getpid, %kill, etc) because Windows and *nix handle processes very differently. Here are a couple links on this topic of semaphores:

  • link IPC:Semaphores – Intro and some details
  • link Excellent IBM articles for developers migrating Windows code to Linux

But I still don’t think this should "confuse" a D3 developer. First, with the above functions as an example, the Windows functions aren’t even in there to be confusing. The functions don’t even exist in Windows – it would be confusing to me why a D3 developer would be looking for them in a C library that just proxies into the OS. Second, how many D3 developers are seriously trying to figure out how to write a socket client or manage semaphores? If you are clicking the links in this article to learn what these concepts, the D3 Reference Manual is not going to help you no matter how much info it has. If you know what these functions are then there should be no confusion as to why they are unsupported from one platform to another.

Rather than flagging specific %functions as not being supported for Windows, I think RD might have done better to create a doc section called the Unix C Function library, and another section for the Windows C Function library. Again however, since RD hasn’t in earnest updated the C Function docs since D3NT was introduced, it’s unrealistic to suggest that they re-organize what they have. And (let’s assume RD makes this decision based on established business needs) even if they did re-organize this doc section, considering my comments above, would they really be helping a large number of developers? Those who would want such docs probably couldn’t use them, and those who already use the features probably wouldn’t care if the doc is split up or not. That said, if it were my responsibility I would err on the side of having complete and accurate docs for whomever might want them.

Leave a Reply