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.

Does Pascal, etc. have typdefs like C/C++ with the ULONG above? -daniel lee kruse

Pascal, Ada, Modula and Fortran has type definitions. Don't know about other languages. - prokushev

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

Don't make this stuff to complicated! Most of OS/2 development is done in C out there, the toolkit is C/C++ only. If you want to add any possible language tweak here you will end in a mess. e.g. you had to add descriptions for Perl, Python, Ruby, Modula and probably quite some more. -Cinc

Personally, I consider Define (C/C++) section is not required. It is specific to OS/2 Toolkit. Watcom has slightly different defines. According other languages. Don't stop other programmers. I don't like to learn another language because "all uses them". (Personally I know C/C++ on level to freely understand and write some things on it, but don'like this 'portable' garbage). -- 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 if the name exists with help of LXLite, LXDump, etc. - prokushev

A function will only be exported by name if the developer decided to do so by providing a proper EXPORT statement. Ordinals may be specified by the developer or will be chosen by the compiler if not done. They always exist. If you don't specify the ordinal it may happen that it changes from DLL release to DLL release. For undocumented functions IBM usually uses ordinal only exports. -Cinc

Calling convention

Cdecl32

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

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 convention 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 convention. According _System. Each API call has things like APIENTRY. If you look into os2def you'll notice

#define APIENTRY _System

. APIENTRY16 has definition

#define _Far16 _Pascal

And yes. Cdecl32 etc. can be pointed as Cdecl32 there will be table with corresponding calling conventions 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

TRUE

Type

BOOL

Value

1

SOM interface definition format

SOM interfaces defined via Interface Definition Language. Module name not known all the time, so no module information. Calling convention is always Cdecl32.

Interface

interface WPShadow : WPAbstract
{
 WPObject wpQueryShadowedObject(in BOOL fLock);
 BOOL wpSetShadowTitle(in PSZ pszNewTitle);
 BOOL wpSetLinkToObject(in WPObject FromObject);

#ifdef __SOMIDL__
 implementation {

   releaseorder: wpSetLinkToObject,withdrawn,wpSetShadowTitle,wpQueryShadowedObject;

   externalstem = wplink;
   local;
   externalprefix = shd_;
   majorversion = 1;
   minorversion = 2;
   filestem = wpshadow;
   metaclass = M_WPShadow;
   callstyle = oidl;
   dllname = "pmwp.dll";               

   SOM:ObjectMethods:wpQueryTitle: override;
   SOM:ObjectMethods:wpSetup: override;
   SOM:ObjectMethods:wpSaveState: override;
   SOM:ObjectMethods:wpRestoreState: override;
   SOM:ObjectMethods:wpQueryStyle: override;
   SOM:ObjectMethods:wpInitData: override;
   SOM:ObjectMethods:wpUnInitData: override;
   SOM:ObjectMethods:wpSetTitle: override;
   SOM:ObjectMethods:wpFilterPopupMenu: override;
   SOM:ObjectMethods:wpModifyPopupMenu: override;
   SOM:ObjectMethods:wpMenuItemSelected: override;
   SOM:ObjectMethods:wpViewObject: override;
   SOM:ObjectMethods:wpMenuItemHelpSelected: override;
   SOM:ObjectMethods:wpCreateFromTemplate: override;
   SOM:ObjectMethods:wpOpen: override;
   SOM:ObjectMethods:wpInsertPopupMenuItems: override;
   SOM:ObjectMethods:wpInsertMenuItems: override;                                                
   SOM:ObjectMethods:wpCreateShadowObject: override;
   SOM:ObjectMethods:wpDragOver: override;
   SOM:ObjectMethods:wpDrop: override;
   SOM:ObjectMethods:wpQueryDefaultHelp: override;
   SOM:ObjectMethods:wpConfirmDelete: override;
   SOM:ObjectMethods:wpConfirmObjectTitle: override;
   SOM:ObjectMethods:wpPrintObject: override;
   SOM:ObjectMethods:wpFormatDragItem: override;
   SOM:ObjectMethods:wpDraggedOverObject: override;
   SOM:ObjectMethods:wpDroppedOnObject: override;
   SOM:ObjectMethods:wpQueryNameClashOptions: override;
   SOM:ObjectMethods:wpFilterMenu: override;                                                     
   SOM:ObjectMethods:wpModifyMenu: override;                                                     
   SOM:ObjectMethods:somDefaultInit: override;          
   SOM:ObjectMethods:somDestruct: override;             

 };
#endif /* __SOMIDL__ */
};

Comments

I don't have any.

OS Version Introduced

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

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

Loading time

OK, I think the OS2_API page will take too long to load on slower connections. It's slower than I like on DSL. I'd like to hear suggestions. One would be to just have the Control Programming, Presentation Programming, etc. links go to separate pages instead of the sub-sections that they are. Another is to leave it alone. Thoughts? - Daniel Lee Kruse

From my point of view, only solution is to divide on sections (CPI, PM, etc.). -- Prokushev

It is MUCH better now. -- Daniel Lee Kruse

SubSectioning

Only question about sectioning. Originally I placed all SOM based APIs under SOM section. No all API's mixed. I consider this is incorrect approach. I propose move OpenDoc, OSA, WPS etc. back to SOM subsection. -- Prokushev

Do you mean the layout on the OS/2 API page, or the namespace sandboxing (URL), or both? I agree with you. It was my unfamiliarity with the APIs that I didn't know what section/subsection to place them. I haven't changed the API_Call to OS2_API:API_Call yet (for the SOM calls), but maybe I should have it be SOM:API_Call instead for the namespacing? The more I think about it I think SOM:API_Call would be better for the SOM stuff. -- Daniel Lee Kruse