Introduction to the OS/2 API Documentation

From EDM2
Jump to: navigation, search

by Prokushev, Daniel Lee Kruse, Anakor, Martin Iturbide


The OS/2 API is not available for public domain. A range of OS/2 products includes API documentation. Latest OS/2 Toolkit is part of Convenience Packages and eComStation.

Anyway, OS/2 Toolkit documentation contains errors, not all API documented etc. Lot of parts just not included.

In 1996 The OS/2 API project was started. But copyright issues not allowed to extend project after maintainers lost interest in it. So, all work from the OS/2 API project was never completed.

After EDM/2 was relaunched, in 2004 Daniel Lee Kruse started OS/2 API Documentation pages. Wiki provided good chance to make this project live.

This article describes how any API entry must be described.

API entry definition

Each API entry must be described and documented in common and standard representation form. Here is example of API function definition as used in the project ({this is comment}):

DosBeep {function name as Page Name}

Generates the specified frequency on the computer's speaker. {general function description}


DosBeep(frequency, duration) : {function definition. No types described here}


frequency - ULONG - input 
{parameter description with type and stream direction}

Frequency as Hertz with valid values from 37 through 32767. {parameter description}

duration - ULONG - input 

Length of the sound in milliseconds.


None. {list of used constants}


NO_ERROR  {list of return codes}


DOSCALLS {name of export module}

Define (C/C++)

DOS_PROCESS {This entry optional and actual only for OS/2 Toolkit compatible C/C++ section. Controls include sequence}

Ordinal/Export name

286 {Ordinal and/or export name of function. Can be detected by LxLite, NeLite, etc.}

Calling convention

Cdecl32 {Calling convention of function. Possible values are: Cdecl32, Cdecl16, Pascal32 & Pascal16}


I don't have any. {Function specific comments}

Example Code

Not needed for this example listing.

{Here example code. Prefered language - C. But various language-specific voodoo (like C/C++ += -= ++ --) must not used. Minimal pointers<->ULONG conversions because potential error points.}

Related Functions

OS Version Introduced

OS/2 2.1

Messages definition

Messages also can be interpreted as API entry. Usually you call API function WinSendMsg and receive the result. Each message has some specific parameters and return codes. So, message also must be represented in some form.

SOM Interface definition

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 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;
   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__ */


I don't have any.

OS Version Introduced

OS/2 2.1

Types definition

MyType {DataType Name as Page Name}

MyType description


List of the types fields, e.g.

ULONG  oNextEntryOffset
FDATE  fdateCreation

C Declaration Method

One of the following:

  • typedef
  • typedef struct
  • typedef const
  • macro or #define


Explanation of the fields under type, e.g.

oNextEntryOffset   Offset of next entry.
fdateCreation      Date of file creation.


Additional comments where applicable.

If anything in the type can't be done yet then leave a message in the talk page of the corresponding type, like this:


Link to MB_OK can't be done yet

Example Code

If there is any sample on how to use/declare the data type.

Constants definition

TRUE {Constant name }


BOOL {Constant type}


1 {Constant value}