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.

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)
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