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.

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)	FAPI Version
BadDynLink	–	API/FAPI	–	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
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 the address of the process environment string 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	DOSCALLS	API/FAPI	1.00
DosGetVersion	Returns the OS version number	DOSCALLS	API/FAPI	Done	Done	1.00
DosInsMessage	DOSCALLS	API/FAPI	1.00
DosMkDir	Creates a subdirectory	DOSCALLS	API/FAPI	Done	Done	1.00
DosMove	Moves a file object to another location and changes its name	DOSCALLS	API/FAPI	Done	1.00
DosNewSize	Changes the size of a file	DOSCALLS	API/FAPI	Done	1.00
DosPutMessage	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	Done	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	DOSCALLS	API/FAPI	1.00
DosSetFileInfo	Set attribute and extended attribute information for a file	DOSCALLS	API/FAPI	Done	1.00
DosSetFileMode	DOSCALLS	API/FAPI	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	DOSCALLS	API/FAPI	1.00
DosSubFree	DOSCALLS	API/FAPI	1.00
DosSubSet	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	DOSCALLS	API/FAPI	1.10
DosDevIOCtl	DOSCALLS	API/FAPI	1.00
DosError	DOSCALLS	API/FAPI	1.00
DosErrClass	DOSCALLS	API/FAPI	1.10
DosExecPgm	DOSCALLS	API/FAPI	1.00
DosExit	DOSCALLS	API/FAPI	1.00
DosFileLocks	DOSCALLS	API/FAPI	1.00
DosFindClose	DOSCALLS	API/FAPI	1.00
DosFindFirst	DOSCALLS	API/FAPI	1.00
DosFindNext	DOSCALLS	API/FAPI	1.00
DosGetCtryInfo	DOSCALLS	API/FAPI	1.10
DosGetDBCSEv	DOSCALLS	API/FAPI	1.10
DosGetCP	DOSCALLS	API/FAPI	1.10
DosSetCP	DOSCALLS	API/FAPI	1.10
DosGetCollate	DOSCALLS	API/FAPI	1.10
DosHoldSignal	DOSCALLS	API/FAPI	1.00
DosOpen	DOSCALLS	API/FAPI	1.00
DosQFileInfo	DOSCALLS	API/FAPI	1.00
DosRead	DOSCALLS	API/FAPI	1.00
DosReallocHuge	DOSCALLS	API/FAPI	1.00
DosReallocSeg	DOSCALLS	API/FAPI	1.00
DosSetCtryCode	DOSCALLS	API/FAPI	1.00
DosSetFHandState	DOSCALLS	API/FAPI	1.00
DosSetSigHandler	DOSCALLS	API/FAPI	1.00
KbdCharIn	KBDCALLS	API/FAPI	1.00
KbdFlushBuffer	KBDCALLS	API/FAPI	1.00
KbdGetStatus	KBDCALLS	API/FAPI	1.00
KbdSetStatus	KBDCALLS	API/FAPI	1.00
KbdStringIn	KBDCALLS	API/FAPI	1.00
KbdPeek	KBDCALLS	API/FAPI	1.00
VioGetBuf	VIOCALLS	API/FAPI	1.00
VioGetCurPos	VIOCALLS	API/FAPI	1.00
VioGetCurType	VIOCALLS	API/FAPI	1.00
VioGetPhysBuf	VIOCALLS	API/FAPI	1.00
VioReadCellStr	VIOCALLS	API/FAPI	1.00
VioReadCharStr	VIOCALLS	API/FAPI	1.00
VioScrollDn	VIOCALLS	API/FAPI	1.00
VioScrollLf	VIOCALLS	API/FAPI	1.00
VioScrollRt	VIOCALLS	API/FAPI	1.00
VioScrUnLock	VIOCALLS	API/FAPI	1.00
VioSetCurPos	VIOCALLS	API/FAPI	1.00
VioSetCurType	VIOCALLS	API/FAPI	1.00
VioSetMode	VIOCALLS	API/FAPI	1.00
VioShowBuf	VIOCALLS	API/FAPI	1.00
VioWrtCellStr	VIOCALLS	API/FAPI	1.00
VioWrtCharStr	VIOCALLS	API/FAPI	1.00
VioWrtCharStrAtt	VIOCALLS	API/FAPI	1.00
VioWrtNAttr	VIOCALLS	API/FAPI	1.00
VioWrtNCell	VIOCALLS	API/FAPI	1.00
VioWrtNChar	VIOCALLS	API/FAPI	1.00
VioWrtTTY	VIOCALLS	API/FAPI	1.00
VioScrLock	VIOCALLS	API/FAPI	1.00

Limitations

DOS 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.

OS/2 16-bit Protected Mode

16 MB memory

1GB virtual address space

Notes

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