This is part of Family API which allow to create dual-os version of program runs under OS/2 and DOS

Note: This is legacy API call. It is recommended to use 32-bit equivalent

Family API

Family API (FAPI) is a subset of Control Program API which can be used to write binary portable applications. Such applications can be run as on OS/2 as on DOS system without any modifications. It is known 2 versions of original Family API 1.00 and 1.10. Also exists side Family API implementation. FAMAPI by Jonathan de Boyne Pollard and HX DOS Extender API by Andreas Grech. Versions up to 1.10 is a original OS/2 Family API. 1.20 and higher is a osFree extensions.

Dual OS applications

It is possible to write programs which will run on OS/2, DOS and Windows NT from one binary. Moreover, same source code can be used without any #ifdef and other preprocessor statements. Such portability achieved via Family API. Family API is OS/2 API emulation layer on top of DOS. OS/2 executable file is in NE (New Executable) file format. NE file consist of two parts:

Legacy DOS MZ EXE format part;

NE EXE part.

Using Family API MZ part of file used to provide loading and dynamic linking mechanism to load and link NE. Also Family API file contains emulation library which translates OS/2 API calls to DOS interrupt calls. So, same file can be executed as in OS/2 as in DOS. Windows NT contains OS2 Subsystem (os2ss.exe) which provides OS/2 API layer on top of Windows NT kernel. So, Family API allows to support 3 OSes using one binary file.

For current time only 16-bit Family API supported.

Writing portable tools

http://www.edm2.com/index.php/Hints_for_writing_simple_programs_for_both_OS/2_and_DOS

Function Calls

OS/2 1.0 introduced around 80-90 function calls (various information sources differ) that could be used in FAPI programs.

Name	Description	Module (OS/2)	Library (DOS)	Status (OS/2)	Status (DOS)	FAPI Version
BadDynLink	Terminates execution with error message	–	API/FAPI	–	Done	1.00
DosBeep	Generates sound from the speaker	DOSCALLS	API/FAPI	Done	1.00
DosBufReset	Flushes a file cache buffers	DOSCALLS	API/FAPI	Done	Done	1.10
DosChDir	Defines the current directory for the requesting process	DOSCALLS	API/FAPI	Done	Done	1.00
DosChgFilePtr	Moves the read/write pointer	DOSCALLS	API/FAPI	Done	Done	1.00
DosClose	Closes a handle to a file, pipe, or device	DOSCALLS	API/FAPI	Done	Done	1.00
DosCreateCSAlias	Create CS alias from data segment	DOSCALLS	API/FAPI	Done	1.00
DosCLIAccess	Request I/O privilege for disabling and enabling interrupts	DOSCALLS	API/FAPI	Done	1.00
DosPortAccess	Request or release access to ports for I/O privilege	DOSCALLS	API/FAPI	Done	1.00
DosDelete	Removes a directory entry associated with a file name	DOSCALLS	API/FAPI	Done	Done	1.00
DosDevConfig	Return device configuration	DOSCALLS	API/FAPI	Done	1.00
DosDupHandle	Returns a new file handle for an open file	DOSCALLS	API/FAPI	Done	Done	1.00
DosFreeSeg	Deallocates a memory segment	DOSCALLS	API/FAPI	Done	1.00
DosGetDateTime	Get the current date and time	DOSCALLS	API/FAPI	Done	1.00
DosGetEnv	Return process environment for the current process	DOSCALLS	API/FAPI	Done	1.00
DosGetHugeShift	Return a shift count used to derive the selectors that address memory allocated with DosAllocHuge	DOSCALLS	API/FAPI	Done	1.00
DosGetMachineMode	Returns the current mode of the processor	DOSCALLS	API/FAPI	Done	Done	1.00
DosGetMessage	Retrieve a message from the specified system message file	DOSCALLS	API/FAPI	1.00
DosGetVersion	Return the OS version number	DOSCALLS	API/FAPI	Done	Done	1.00
DosInsMessage	Insert variable text string information into the body of a message	DOSCALLS	API/FAPI	1.00
DosMkDir	Create a subdirectory	DOSCALLS	API/FAPI	Done	Done	1.00
DosMkDir2	Create a subdirectory with EA	DOSCALLS	API/FAPI	Done	Done	????
DosMove	Move a file object to another location, change its name	DOSCALLS	API/FAPI	Done	1.00
DosNewSize	Changes the size of a file	DOSCALLS	API/FAPI	Done	1.00
DosPutMessage	Output the message	DOSCALLS	API/FAPI	1.00
DosQCurDir	Returns the full path name of the current directory	DOSCALLS	API/FAPI	Done	1.00
DosQCurDisk	Determines the current default drive for the requesting process	DOSCALLS	API/FAPI	Done	1.00
DosQFileMode	Queries the mode (attribute) of the specified file	DOSCALLS	API/FAPI	Done	1.00
DosQFSInfo	Query file system info	DOSCALLS	API/FAPI	1.00
DosQVerify	Returns the value of the verify flag	DOSCALLS	API/FAPI	Done	Done	1.00
DosRmDir	Removes a subdirectory from the specified disk	DOSCALLS	API/FAPI	Done	Done	1.00
DosSelectDisk	Selects the drive specified as the default drive	DOSCALLS	API/FAPI	Done	Done	1.00
DosSetDateTime	Set the date and time	DOSCALLS	API/FAPI	Done	1.00
DosSetFileInfo	Set attribute and extended attribute information for a file	DOSCALLS	API/FAPI	Done	1.00
DosSetFileMode	Changes the mode (attribute) of the specified file	DOSCALLS	API/FAPI	Done	1.00
DosSetVerify	Sets write verification	DOSCALLS	API/FAPI	Done	Done	1.00
DosSleep	Suspend the current thread for a specified time	DOSCALLS	API/FAPI	Done	1.00
DosSubAlloc	Suballocate portions of a segment	DOSCALLS	API/FAPI	1.00
DosSubFree	Free memory previously allocated by DosSubAlloc	DOSCALLS	API/FAPI	1.00
DosSubSet	Initialize a segment for suballocation	DOSCALLS	API/FAPI	1.00
DosWrite	Write buffer to file	DOSCALLS	API/FAPI	Done	1.00
DosAllocHuge	Allocate multiple segments as a huge block of memory	DOSCALLS	API/FAPI	Done	1.00
DosAllocSeg	Allocate a data segment up to 64KB in size	DOSCALLS	API/FAPI	Done	1.00
DosCaseMap	Case mapping on a string	DOSCALLS	API/FAPI	1.10
DosDevIOCtl	Control functions on a device	DOSCALLS	API/FAPI	1.00
DosDevIOCtl2	Control functions on a device	DOSCALLS	API/FAPI	????
DosError	Receive hard error notification	DOSCALLS	API/FAPI	Done	1.00
DosErrClass	Receive hard error code information	DOSCALLS	API/FAPI	1.10
DosExecPgm	Execute another program as a child process	DOSCALLS	API/FAPI	Done	1.00
DosExit	End The current thread or process	DOSCALLS	API/FAPI	Done	1.00
DosFileLocks	Locks and unlock a range in an opened file	DOSCALLS	API/FAPI	Done	1.00
DosFindClose	Finish DosFindFirst or DosFindNext directory search function sequence	DOSCALLS	API/FAPI	Done	1.00
DosFindFirst	Finds the first file object or group of file objects whose name(s) match the specification	DOSCALLS	API/FAPI	Done	1.00
DosFindFirst2	Finds the first file object or group of file objects whose name(s) match the specification	DOSCALLS	API/FAPI	???
DosFindNext	Locate the next set of directory entries	DOSCALLS	API/FAPI	Done	1.00
DosGetCtryInfo	Obtain country-dependent formatting information that resides in the country information file	DOSCALLS	API/FAPI	1.10
DosGetDBCSEv	Obtain a DBCS (double byte character set) environmental vector that resides in the country information file	DOSCALLS	API/FAPI	Done	1.10
DosGetCP	Query the current process code page and the prepared system code pages	DOSCALLS	API/FAPI	Done	1.10
DosSetCP	Set process code page and the session's display code page and keyboard code page	DOSCALLS	API/FAPI	Done	1.10
DosGetCollate	Obtain a collating sequence table	DOSCALLS	API/FAPI	1.10
DosHoldSignal	Temporarily disable or enable signal processing for the current process	DOSCALLS	API/FAPI	1.00
DosOpen	Open a file, a named pipe, or a device	DOSCALLS	API/FAPI	Done	1.00
DosOpen2	Open a file with extended attributes	DOSCALLS	API/FAPI	????
DosQFileInfo	Return information for a specific file	DOSCALLS	API/FAPI	Done	1.00
DosRead	Read the specified number of bytes from a file, pipe, or device to a buffer location	DOSCALLS	API/FAPI	Done	1.00
DosReallocHuge	Change the size of memory originally allocated by DosAllocHuge	DOSCALLS	API/FAPI	1.00
DosReallocSeg	Reallocate a segment after discard or changes the size of a segment already allocated	DOSCALLS	API/FAPI	Done	1.00
DosSetCtryCode	DOSCALLS	API/FAPI	1.00
DosSetFHandState	Set the state of the specified file	DOSCALLS	API/FAPI	1.00
DosSetSigHandler	Set signal handler	DOSCALLS	API/FAPI	Done	1.00
DosAllocShrSeg	Allocate a named shared memory segment to a process	DOSCALLS	API/FAPI	Done	1.20
DosGetShrSeg	Accesses a shared memory segment previously allocated by another process	DOSCALLS	API/FAPI	Done	1.20
DosLoadModule	Load a dynamic link module and returns a handle for the module	DOSCALLS	API/FAPI	Done	1.20
DosFreeModule	Free the reference to a dynamic link module for a process	DOSCALLS	API/FAPI	Done	1.20
DosQHandType	Get handle type	DOSCALLS	API/FAPI	Done	1.00
DosGetProcAddr	Get module procedure address	DOSCALLS	API/FAPI	Done	1.20
DosGetPID	Get process id	DOSCALLS	API/FAPI	Done	1.00
DosSetMaxFH	Set maximum file handlers	DOSCALLS	API/FAPI	Done	1.20
DosGetModHandle	Get module handle	DOSCALLS	API/FAPI	Done	1.20
DosQPathInfo	Get path information	DOSCALLS	API/FAPI	1.??
DosQFSAttach	Query information about an attached file system	DOSCALLS	API/FAPI	1.??
DosQSysInfo	Query system variablies values	DOSCALLS	API/FAPI	Done	1.20
DosMemAvail	Query maximum availabe huge memory block	DOSCALLS	API/FAPI	Done	1.20
DosGetInfoSeg	Query global and local information segments	DOSCALLS	API/FAPI	Done	1.20
KbdCharIn	Return a character data record from the keyboard	KBDCALLS	API/FAPI	Done	1.00
KbdFlushBuffer	Clear the keystroke buffer	KBDCALLS	API/FAPI	Done	1.00
KbdGetStatus	Get the current state of the keyboard	KBDCALLS	API/FAPI	Done	1.00
KbdSetStatus	Set the characteristics of the keyboard	KBDCALLS	API/FAPI	1.00
KbdStringIn	Read a character string (character codes only) from the keyboard	KBDCALLS	API/FAPI	1.00
KbdPeek	Return any available character data record from the keyboard without removing it from the buffer	KBDCALLS	API/FAPI	Done	1.00
KbdOpen	Create a new logical keyboard	KBDCALLS	API/FAPI	Done	1.20
KbdClose	Close the existing logical keyboard	KBDCALLS	API/FAPI	Done	1.20
KbdGetFocus	Bind the logical keyboard to the physical keyboard	KBDCALLS	API/FAPI	Done	1.20
KbdFreeFocus	Free the logical-to-physical keyboard bond	KBDCALLS	API/FAPI	Done	1.20
KbdGetCp	Query the code page being used to translate scan codes to ASCII characters	KBDCALLS	API/FAPI	1.20
KbdSetCp	Set the code page used to translate key strokes received from the keyboard	KBDCALLS	API/FAPI	1.20
KbdXlate	Translate scan codes with shift states into ASCII codes	KBDCALLS	API/FAPI	1.20
KbdSetCustXt	Install, on the specified handle, the translate table	KBDCALLS	API/FAPI	1.20
KbdGetHWId	Return the type of keyboard in use	KBDCALLS	API/FAPI	1.20
KbdRegister	Registers a keyboard subsystem within a session	KBDCALLS	API/FAPI	1.20
KbdDeRegister	Deregister a keyboard subsystem within a session	KBDCALLS	API/FAPI	1.20
MouRegister	Register a mouse subsystem within a session	KBDCALLS	API/FAPI	1.20
MouDeRegister	Deregister a mouse subsystem within a session	KBDCALLS	API/FAPI	1.20
MouGetNumButtons	Return the number of buttons supported on the installed mouse driver	MOUCALLS	API/FAPI	1.20
MouGetNumMickeys	Return the number of mickeys in each centimeter for the installed mouse driver	MOUCALLS	API/FAPI	1.20
MouGetDevStatus	Return status flags for the installed mouse device driver	MOUCALLS	API/FAPI	1.20
MouGetNumQueEl	Return the current status for the mouse device driver event queue	MOUCALLS	API/FAPI	1.20
MouReadEventQue	Read an event from the mouse device FIFO event queue	MOUCALLS	API/FAPI	1.20
MouGetScaleFact	Return a pair of 1-word scaling factors for the current mouse device	MOUCALLS	API/FAPI	1.20
MouGetEventMask	Return the current value of the mouse event queue mask	MOUCALLS	API/FAPI	1.20
MouSetScaleFact	Assign to the current mouse device driver a new pair of 1-word scaling factors	MOUCALLS	API/FAPI	1.20
MouSetEventMask	Assign a new event mask to the current mouse device driver	MOUCALLS	API/FAPI	1.20
MouGetHotKey	Return mouse button or buttons defined as system hot key	MOUCALLS	API/FAPI	1.20
MouSetHotKey	Define mouse button or buttons as system hot key	MOUCALLS	API/FAPI	1.20
MouOpen	Open the mouse device for the current session	MOUCALLS	API/FAPI	1.20
MouClose	Close the mouse device for the current session	MOUCALLS	API/FAPI	1.20
MouGetPtrShape	Get (copy) the pointer shape for the session	MOUCALLS	API/FAPI	1.20
MouSetPtrShape	Set the pointer shape and size for the session	MOUCALLS	API/FAPI	1.20
MouDrawPtr	Notify the mouse device driver that an area is now available	MOUCALLS	API/FAPI	1.20
MouRemovePtr	Notify the mouse device driver that the area is not available	MOUCALLS	API/FAPI	1.20
MouGetPtrPos	Querie the current row and column coordinate	MOUCALLS	API/FAPI	1.20
MouSetPtrPos	Set a new row and column coordinate position	MOUCALLS	API/FAPI	1.20
MouInitReal	Initialize mouse pointer draw support for DOS mode	MOUCALLS	API/FAPI	1.20
MouFlushQue	Flush (empty) the mouse event queue	MOUCALLS	API/FAPI	1.20
MouSetDevStatus	Set the mouse device driver status flags	MOUCALLS	API/FAPI	1.20
VioGetBuf	Return the address of the logical video buffer (LVB)	VIOCALLS	API/FAPI	1.20
VioGetCurPos	Return the coordinates of the cursor	VIOCALLS	API/FAPI	Done	1.00
VioGetCurType	Get cursor type	VIOCALLS	API/FAPI	Done	1.00
VioGetPhysBuf	Get addressability to the physical display buffer	VIOCALLS	API/FAPI	1.00
VioReadCellStr	Read a string of character-attribute pairs from the screen	VIOCALLS	API/FAPI	Done	1.00
VioReadCharStr	Read a string of characters from the display	VIOCALLS	API/FAPI	Done	1.00
VioScrollDn	Scroll the entire display buffer (or area specified within the display buffer) down	VIOCALLS	API/FAPI	Done	1.00
VioScrollLf	Scroll the entire display buffer (or area specified within the display buffer) to the left	VIOCALLS	API/FAPI	1.00
VioScrollRt	Scroll the entire display buffer (or area specified within the display buffer) to the right	VIOCALLS	API/FAPI	1.00
VioScrUnLock	Release ownership of (unlocks) the physical display buffer	VIOCALLS	API/FAPI	Done	1.00
VioSetCurPos	Set the cursor's coordinates on the screen	VIOCALLS	API/FAPI	Done	1.00
VioSetCurType	Set the cursor type	VIOCALLS	API/FAPI	Done	1.00
VioSetMode	Set the mode of the display	VIOCALLS	API/FAPI	Done	1.00
VioShowBuf	Update the physical display buffer with the logical video buffer (LVB)	VIOCALLS	API/FAPI	1.20
VioWrtCellStr	Write a string of character-attribute pairs (cells) to the display	VIOCALLS	API/FAPI	Done	1.00
VioWrtCharStr	Write a character string to the display	VIOCALLS	API/FAPI	Done	1.00
VioWrtCharStrAtt	Write a character string with repeated attribute to the display	VIOCALLS	API/FAPI	Done	1.00
VioWrtNAttr	Write an attribute to the display a specified number of times	VIOCALLS	API/FAPI	Done	1.00
VioWrtNCell	Write a cell (character-attribute pair) to the display a specified number of times	VIOCALLS	API/FAPI	Done	1.00
VioWrtNChar	Write a character to the display a specified number of times	VIOCALLS	API/FAPI	Done	1.00
VioWrtTTY	Write a character string to the display starting at the current cursor position	VIOCALLS	API/FAPI	Done	1.00
VioScrLock	Request ownership of (locks) the physical display buffer	VIOCALLS	API/FAPI	Done	1.00
VioGetMode	Return the mode of the display	VIOCALLS	API/FAPI	Done	1.20
VioGetConfig	Return the video display configuration	VIOCALLS	API/FAPI	Done	1.??
VioGetAnsi	Return the current ANSI status On/Off state	VIOCALLS	API/FAPI	Done	1.20
VioSetAnsi	Activate or deactivate ANSI support	VIOCALLS	API/FAPI	Done	1.20
VioScrollUp	Sroll the entire display buffer (or area specified within the display buffer) up	VIOCALLS	API/FAPI	Done	1.20
VioDeRegister	Deregister alternate video system	VIOCALLS	API/FAPI	Done	1.20
VioRegister	Register alternate video system	VIOCALLS	API/FAPI	Done	1.20
VioGetState	Return the current settings of adapter	VIOCALLS	API/FAPI	1.??
VioSetState	Set the current settings of adapter	VIOCALLS	API/FAPI	1.??
VioGetCP	Query the code page for display	VIOCALLS	API/FAPI	1.20
VioSetCP	Set the code page for display	VIOCALLS	API/FAPI	1.20
VioGetFont	Get current font	VIOCALLS	API/FAPI	1.??
VioSetFont	Set current font	VIOCALLS	API/FAPI	1.??
VioModeWait	Notify process about it must restore its video mode	VIOCALLS	API/FAPI	1.20
VioModeUndo	VIOCALLS	API/FAPI	1.20
VioPopUp	Show temporary screen to display message	VIOCALLS	API/FAPI	1.20
VioEndPopUp	Return from temporary screen	VIOCALLS	API/FAPI	1.20
VioSavRedrawWait	Notifies application when it must save/redraw its screen	VIOCALLS	API/FAPI	1.20
VioSavRedrawUndo	VIOCALLS	API/FAPI	1.20
VioPrtSc	Dump screen to printer	VIOCALLS	API/FAPI	1.20
VioPrtScToggle	Toggle VioWrtTty also write to printer	VIOCALLS	API/FAPI	1.20

Compatibility

Feature	DOS 16-bit Real Mode	DOS 16-bit Protected Mode	OS/2 16-bit Protected Mode
Max memory	640KB	16MB	16MB
Virtual memory	No	No	1Gb
Multitasking	No	No	Yes
Long filenames	Yes*	Yes*	Yes
App EXE name change	3+	3+	Yes

* Supported since version 1.20 Requires LFN driver under DOS or run in Windows 9x VDM.

Remarks

For implementation details refer to Implementation details section.

Notes

This text based on http://www.edm2.com/index.php/Family_API