Talk:OS2 API

Please don't make this available to the outside world just yet. I'm still considering layout and content for the opening page. Thanks. Daniel Lee Kruse

API definition format

How about describing API in an language-neutral format? I mean not in C notation but in something like SOM IDL? Because C API defination hard to read and some info missed (like ordinals and module names).

---

Language-neutral format is a good idea. Having never seen SOM IDL I have no idea what that would look like. Could you please post an example or two?

I had in mind that each API call would be a single page sectioned out. For example, the API call and its parameters, then a section with the parameters explained with constants listed - if any. Another section with example code. Maybe a section with closely related functions. A section detailing the return codes of that API call. Thanks. -Daniel Lee Kruse

Essentially that means an implementation like the docs coming with the toolkit?

Really, I mean definition of functions. At the present time C/C++ notation is used. As in header files. But such description has some disadvantager.

• Function location not known (in which module function placed)
• Ordinal or export name not known
• Type and constant definition can be defined via #define -> without documentation impossible to predict is type or value defined
• Impossible to convert to another language without human resources.

So, some language(programming)-neutral description seems to be good solution for above. // Prokushev

An example API function page

DosBeep

DosBeep(frequency, duration)

Generates the specified frequency on the computer's speaker.

Parameters

frequency - ULONG - input

Frequency as Hertz with valid values from 37 through 32767.

duration - ULONG - input

Length of the sound in milliseconds.

Constants

None.

Returns

NO_ERROR
ERROR_INVALID_FREQUENCY

Module

DOSCALLS

IIRC or is it DOSCALLS1? -daniel lee kruse

DOSCALL1. But it was library (lib) in old OS/2 versions. Actually, kernel handles DOSCALLS name (no real DLL).

Define (C/C++)

DOS_PROCESS

Note: No value for non C/C++ languages

Should we have the define section then?  Or using this sub-heading: Define (C/C++)? 
-daniel lee kruse

Define (C/C++ only) is ok for me. - prokushev

Ordinal/Export name

286 - I don't know the export name

IIRC Doscalls exports functions only by ordinal

What determines the export name versus ordinal only? -daniel lee kruse

Heh. Ordinals exists always. But if name present then name must be used. It's not so critical for API functions (because ordinals has fixed value from version to version) but name always unique. You can check is name exists with help of LXLite, LXDump, etc. - prokushev

Calling conversion

Cdecl32

 I propose to set Cdecl32, Cdecl16, Pascal32 & Pascal16 calling convertions.

Sounds good to me.  Is this a C/C++ only item, too, or are there other languages that
 have this?  Obviously, Java doesn't, but I'm not knowledgable about any of the other 
languages. -daniel lee kruse

At least Pascal supports them. Also fortran. Most probably other compiler also support
 something like this. Only difference is used keywords (i.e. FPC has Cdecl and Far16 
modifiers, C uses _Far16 _System modifiers etc.).  - prokushev

Would it be good to list the language with the calling conversion if the languages list
 them differently, or are they uniform across the languages?  IIRC, there is _System and 
another I don't remember under c/c++.  I don't know about Fortran, Pascal, etc.  
-daniel lee kruse

Various _compilers_ uses various logic to point calling conversion. According _System. Each API call has things like APIENTRY. If you look into os2def you'll notice

#define APIENTRY _System

. APIENTRY16 has definetion

#define _Far16 _Pascal

And yes. Cdecl32 etc. can be pointed as Cdecl32 there will be table with corresponding calling conversions for various compilers.

Example Code

Not needed for this example listing.

Should this just be pseudo-code? -daniel lee kruse

Don't think so. But various language-specific voodoo (like C/C++ += -= ++ -- must not be used). Minimal pointers<->ULONG conversions because potential error points. -- prokushev

Related Functions

WinAlarm

Most probably WinAlarm ;)

Didn't think about that one.

Comments

I don't have any.

OS Version Introduced

For example, OS/2 2.1
// End of example listing

Please edit to make more like what you had in mind. -Daniel Lee Kruse

Keyboard, mouse, video function list question

Should the mouse, keyboard, and video sections go under the control programming i/o section? Or maybe we ought to have an I/O section and place them there along with netlabs' usb api. -Daniel Lee Kruse

Most probably, we can create 2 sections. Highlevel Device I/O Function (Vio/Kbd/Mou) and low level Device I/O function (IOCtls) // Prokushev

Sounds great to me. -Daniel Lee Kruse

I suggest keeping the sections like in the official IBM docs so people migrating from there are not confused and can locate stuff easily. So for VIO/KEYBD/MOUSE there should be a separate section IMHO. -Cinc

But they are in CPI documentation. ;) BTW we can put them in both places ;) - Prokushev