en:docs:fapi

This is an old revision of the document!


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.

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:

  1. Legacy DOS MZ EXE format part;
  2. 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