en:docs:fapi

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
DosBeep Generates sound from the speaker DOSCALLS API
DosBufReset Flushes a file cache buffers DOSCALLS API Done Done
DosChDir Defines the current directory for the requesting process DOSCALLS API Done Done
DosChgFilePtr Moves the read/write pointer DOSCALLS API Done Done
DosClose Closes a handle to a file, pipe, or device DOSCALLS API Done Done
DosCreateCSAlias DOSCALLS API
DosDelete Removes a directory entry associated with a file name DOSCALLS API Done Done
DosDevConfig DOSCALLS API
DosDupHandle Returns a new file handle for an open file DOSCALLS API Done Done
DosFreeSeg Deallocates a memory segment DOSCALLS API Done
DosGetDateTime DOSCALLS API
DosGetEnv DOSCALLS API
DosGetHugeShift DOSCALLS API
DosGetMachineMode Returns the current mode of the processor DOSCALLS API Done Done
DosGetMessage DOSCALLS API
DosGetVersion Returns the OS version number DOSCALLS API Done Done
DosInsMessage DOSCALLS API
DosMkDir Creates a subdirectory DOSCALLS API Done Done
DosMove DOSCALLS API
DosNewSize DOSCALLS API
DosPutMessage DOSCALLS API
DosQCurDir DOSCALLS API
DosQCurDisk DOSCALLS API
DosQFileMode DOSCALLS API
DosQFSInfo DOSCALLS API
DosQVerify Returns the value of the verify flag DOSCALLS API Done Done
DosRmDir Removes a subdirectory from the specified disk DOSCALLS API Done Done
DosSelectDisk Selects the drive specified as the default drive DOSCALLS API Done Done
DosSetDateTime DOSCALLS API
DosSetFileInfo DOSCALLS API
DosSetFileMode DOSCALLS API
DosSetVerify Sets write verification DOSCALLS API Done Done
DosSleep DOSCALLS API
DosSubAlloc DOSCALLS API
DosSubFree DOSCALLS API
DosSubSet DOSCALLS API
DosWrite DOSCALLS API
DosAllocHuge DOSCALLS API
DosAllocSeg DOSCALLS API
DosCaseMap DOSCALLS API
DosDevIOCtl DOSCALLS API
DosError DOSCALLS API
DosExecPgm DOSCALLS API
DosExit DOSCALLS API
DosFileLocks DOSCALLS API
DosFindClose DOSCALLS API
DosFindFirst DOSCALLS API
DosFindNext DOSCALLS API
DosGetCtryInfo DOSCALLS API
DosGetDBCSEv DOSCALLS API
DosHoldSignal DOSCALLS API
DosOpen DOSCALLS API
DosQFileInfo DOSCALLS API
DosRead DOSCALLS API
DosReallocHuge DOSCALLS API
DosReallocSeg DOSCALLS API
DosSetCtryCode DOSCALLS API
DosSetFHandState DOSCALLS API
DosSetSigHandler DOSCALLS API
KbdCharIn KBDCALLS API
KbdFlushBuffer KBDCALLS API
KbdGetStatus KBDCALLS API
KbdSetStatus KBDCALLS API
KbdStringIn KBDCALLS API
KbdPeek KBDCALLS API
VioGetBuf VIOCALLS API
VioGetCurPos VIOCALLS API
VioGetCurType VIOCALLS API
VioGetPhysBuf VIOCALLS API
VioReadCellStr VIOCALLS API
VioReadCharStr VIOCALLS API
VioScrollDn VIOCALLS API
VioScrollLf VIOCALLS API
VioScrollRt VIOCALLS API
VioScrUnLock VIOCALLS API
VioSetCurPos VIOCALLS API
VioSetCurType VIOCALLS API
VioSetMode VIOCALLS API
VioShowBuf VIOCALLS API
VioWrtCellStr VIOCALLS API
VioWrtCharStr VIOCALLS API
VioWrtCharStrAtt VIOCALLS API
VioWrtNAttr VIOCALLS API
VioWrtNCell VIOCALLS API
VioWrtNChar VIOCALLS API
VioWrtTTY VIOCALLS API
VioScrLock VIOCALLS API
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

en/docs/fapi.txt · Last modified: 2018/09/06 07:51 by prokushev