Talk:OS2 API

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 definition 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 disadvantage.

• 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

Type definition format

Hi there, I've begun to work on the Data Types, so count me in. It were nice to have an entry point from the main structure for this. The presentation format seems not to be defined yet 100% clearly. So let us try this one:

Base types definition format

short

Short is a standard c type.

Pls, don't use language-specific definition. Here must be something like

Short is a short integer.

-- Prokushev

There's nothing wrong with that, but think about this:

1. We loose possibly significant information with this template. Most types are

  defined via typedef, but there are also #define definitions (see #define
  SHORT short). Maybe there are types defined via macro! So we should say what
  style a type has.

I don't see difference between typedefs and defines. Result is always same. And many languages don't have c-like preprocessor -- prokushev

You're right, the 'result' is the same, but the features have a major difference. Typedefs can be overloaded in object oriented environments, while defines can't!

So add C-specific description to such 'yupes'. Like Define section in API description. -- prokushev

And what about macros?

Don't think we must include macros. -- Prokushev

-- Anakor

2. What in general is a 'Base Type'? I've seen two different situations declared

  as 'Base Type'.
  First is a standard C Type(K&R) like 'Base Type->short'. So 'Base Type' means
  standard C Type?
  Second is a OS/2 Type from the tk-headers like 'Base Type->ULONG'.
  We must clarify this!
  -- Anakor

Personally, I prefer avoid usage of C-specific types. For me we must be stopped at USHORT and describe them as was done for unsigned short. This is because unsigned long is C-specific type. In pascal unsigned short can be just integer or something other. In another language - another basetype. We need not describe all language specific things, but something general. I vote for second approach. -- prokushev

If we want language-neutral docs, we should eliminate all K&R types like 'short', 'long', 'void' and others, because this is not language-neutral, but I don't think this is a solution for the problem.

As I said before, I prefer to stop on USHORT instead of K&R unsigned short. Same for ULONG, etc. -- prokushev

I assume we are here at a point of decision. We should discuss about, whether a language-neutrality -without loosing information- is possible. I don't think so, because some features are only present in C/C++. As example I will take pointers. A great portion of the data types are pointers. To my knowledge pascal has no pointers. How we can present it in language-neutral manner then?

Pointers exists in all languages which practically used. They has different names, but pointers actually. -- prokushev

Second thought. The OS2 API Documentation, as it is today, is NOT language-neutral, see this:

---

OS2 API:WinGetLastError
WinGetLastError(anchorHndl) <-- C-style function call

No. Most of known languages uses same call syntax. -- prokushev

Define (C/C++)              <-- c-style define
INCL_WINERRORS or INCL_PM or INCL_WIN

Yes. It is C/C++ only section. Pascal/Ada/Fortran has no such defines. -- prokushev

Calling conversion
Cdecl32                     <-- c-style calling method

No. C-style calling convention is system. This is language-neutral calling convention. Read more in above discussion. -- prokushev'

Example Code                <-- c-style example
HAB     anchorHndl;
ERRORID rc;
...
rc = WinGetLastError(anchorHndl);
...

---

Also, read more. We assuming for examples used C without C-specific voodoos (like =+, ++, --, etc.). As result such code can be translated to corresponding language, if required. Read more above. -- prokushev'

-- Anakor

OK, I think we come to a nice compromise here (this is what I had in mind). The template for current and future data types will look like this:

--------------------------------------------------------
== MYDATATYPE ==                         <-in any case

MyDataType is the importance Datatype

=== Type ===                             <-in any case

USHORT firstfield
ULONG  secondfield

==== C declaration method ====           <-if applicable

typedef const struct

=== Fields ===                           <-if applicable

firstfield    This means very important
secondfield   This means important 

=== Comment ===                          <-if applicable

This is an example.
-- cut --------------------------------------------------

All occurrences of K&R types will be removed. We don't need them and we are language-neutral. Hope Daniel read here, too. No further link to K&R types should be done. With this template we don't loose information. I will begin to modify all current data types to fit this template. So we don't have the need to split up the data types in base, simple, complex. We only have this template for all data types. This all sounds very nice. -- Anakor

SOM interface definition format

SOM interfaces defined via the SOM 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";               

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

 };
#endif /* __SOMIDL__ */
};

Metaclass

M_WPShadow

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

OpenDoc availability

Does Warp Server for e-business (4.5) include this? I'll have to see if eComStation does or not. -- Daniel Lee Kruse

Don't know. At least Warp 4 Merlin includes OpenDoc 1.1 -- Prokushev

Just a Note

All the Control Program DataTypes are now in the wiki, plus some DataTypes from other API's which procedures needed already available here. The DataTypes now has a entry page at OS2 API:DataType with a list. That's all for this Year now, because I must spend some time on other projects. So I wish you a peaceful Xmas and a happy new year. -- Frank