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.

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

As example of dual mode program lets clone EXEHDR tools from OS/2 and Windows SDK/Toolkit. First of all consider we writing program for OS/2. Other things will be done later to make dual mode program.

#include <os2.h>
#include <newexe.h>
exe_hdr mz_hdr;
new_exe ne_hdr;
void main(void)
{
DosOpen(FileHandle);
DosRead(FileHandle, mz_hdr);
DumpMZ(mz_hdr);
if (is_extended_exe(mz_hdr))
{
DosRead(FileHandle, buffer);
if (is_NE(buffer)) DumpNE((new_exe)buffer);
}
DosClose(FileHandle);
}

Function Calls

OS/2 1.0 introduced 93(?) function calls that could be used in FAPI programs.

Name	Description	Module (OS/2)	Library (DOS)	Status (OS/2)	Status (DOS)
BadDynLink	–	API/FAPI	–
DosBeep	Generates sound from the speaker	DOSCALLS	API/FAPI	Done
DosBufReset	Flushes a file cache buffers	DOSCALLS	API/FAPI	Done	Done
DosChDir	Defines the current directory for the requesting process	DOSCALLS	API/FAPI	Done	Done
DosChgFilePtr	Moves the read/write pointer	DOSCALLS	API/FAPI	Done	Done
DosClose	Closes a handle to a file, pipe, or device	DOSCALLS	API/FAPI	Done	Done
DosCreateCSAlias	Create CS alias from data segment	DOSCALLS	API/FAPI	Done
DosDelete	Removes a directory entry associated with a file name	DOSCALLS	API/FAPI	Done	Done
DosDevConfig	Return device configuration	DOSCALLS	API/FAPI	Done
DosDupHandle	Returns a new file handle for an open file	DOSCALLS	API/FAPI	Done	Done
DosFreeSeg	Deallocates a memory segment	DOSCALLS	API/FAPI	Done
DosGetDateTime	Get the current date and time	DOSCALLS	API/FAPI	Done
DosGetEnv	Returns the address of the process environment string for the current process	DOSCALLS	API/FAPI	Done
DosGetHugeShift	Returns a shift count used to derive the selectors that address memory allocated with DosAllocHuge	DOSCALLS	API/FAPI	Done
DosGetMachineMode	Returns the current mode of the processor	DOSCALLS	API/FAPI	Done	Done
DosGetMessage	DOSCALLS	API/FAPI
DosGetVersion	Returns the OS version number	DOSCALLS	API/FAPI	Done	Done
DosInsMessage	DOSCALLS	API/FAPI
DosMkDir	Creates a subdirectory	DOSCALLS	API/FAPI	Done	Done
DosMove	Moves a file object to another location and changes its name	DOSCALLS	API/FAPI	Done
DosNewSize	DOSCALLS	API/FAPI
DosPutMessage	DOSCALLS	API/FAPI
DosQCurDir	DOSCALLS	API/FAPI
DosQCurDisk	DOSCALLS	API/FAPI
DosQFileMode	DOSCALLS	API/FAPI
DosQFSInfo	DOSCALLS	API/FAPI
DosQVerify	Returns the value of the verify flag	DOSCALLS	API/FAPI	Done	Done
DosRmDir	Removes a subdirectory from the specified disk	DOSCALLS	API/FAPI	Done	Done
DosSelectDisk	Selects the drive specified as the default drive	DOSCALLS	API/FAPI	Done	Done
DosSetDateTime	DOSCALLS	API/FAPI
DosSetFileInfo	DOSCALLS	API/FAPI
DosSetFileMode	DOSCALLS	API/FAPI
DosSetVerify	Sets write verification	DOSCALLS	API/FAPI	Done	Done
DosSleep	DOSCALLS	API/FAPI
DosSubAlloc	DOSCALLS	API/FAPI
DosSubFree	DOSCALLS	API/FAPI
DosSubSet	DOSCALLS	API/FAPI
DosWrite	DOSCALLS	API/FAPI
DosAllocHuge	DOSCALLS	API/FAPI
DosAllocSeg	DOSCALLS	API/FAPI
DosCaseMap	DOSCALLS	API/FAPI
DosDevIOCtl	DOSCALLS	API/FAPI
DosError	DOSCALLS	API/FAPI
DosExecPgm	DOSCALLS	API/FAPI
DosExit	DOSCALLS	API/FAPI
DosFileLocks	DOSCALLS	API/FAPI
DosFindClose	DOSCALLS	API/FAPI
DosFindFirst	DOSCALLS	API/FAPI
DosFindNext	DOSCALLS	API/FAPI
DosGetCtryInfo	DOSCALLS	API/FAPI
DosGetDBCSEv	DOSCALLS	API/FAPI
DosHoldSignal	DOSCALLS	API/FAPI
DosOpen	DOSCALLS	API/FAPI
DosQFileInfo	DOSCALLS	API/FAPI
DosRead	DOSCALLS	API/FAPI
DosReallocHuge	DOSCALLS	API/FAPI
DosReallocSeg	DOSCALLS	API/FAPI
DosSetCtryCode	DOSCALLS	API/FAPI
DosSetFHandState	DOSCALLS	API/FAPI
DosSetSigHandler	DOSCALLS	API/FAPI
KbdCharIn	KBDCALLS	API/FAPI
KbdFlushBuffer	KBDCALLS	API/FAPI
KbdGetStatus	KBDCALLS	API/FAPI
KbdSetStatus	KBDCALLS	API/FAPI
KbdStringIn	KBDCALLS	API/FAPI
KbdPeek	KBDCALLS	API/FAPI
VioGetBuf	VIOCALLS	API/FAPI
VioGetCurPos	VIOCALLS	API/FAPI
VioGetCurType	VIOCALLS	API/FAPI
VioGetPhysBuf	VIOCALLS	API/FAPI
VioReadCellStr	VIOCALLS	API/FAPI
VioReadCharStr	VIOCALLS	API/FAPI
VioScrollDn	VIOCALLS	API/FAPI
VioScrollLf	VIOCALLS	API/FAPI
VioScrollRt	VIOCALLS	API/FAPI
VioScrUnLock	VIOCALLS	API/FAPI
VioSetCurPos	VIOCALLS	API/FAPI
VioSetCurType	VIOCALLS	API/FAPI
VioSetMode	VIOCALLS	API/FAPI
VioShowBuf	VIOCALLS	API/FAPI
VioWrtCellStr	VIOCALLS	API/FAPI
VioWrtCharStr	VIOCALLS	API/FAPI
VioWrtCharStrAtt	VIOCALLS	API/FAPI
VioWrtNAttr	VIOCALLS	API/FAPI
VioWrtNCell	VIOCALLS	API/FAPI
VioWrtNChar	VIOCALLS	API/FAPI
VioWrtTTY	VIOCALLS	API/FAPI
VioScrLock	VIOCALLS	API/FAPI

Limitations

Real Mode

max. 640K memory

no virtual address space

no multitasking

no undocumented OS services

If the filename of an executable produced by BIND is changed, then it will not run under DOS 2.1.

Protected Mode

16 MB memory

1GB virtual address space

Notes

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