This is an old revision of the document!
Table of Contents
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 | Changes the size of a file | DOSCALLS | API/FAPI | Done | |
DosPutMessage | DOSCALLS | API/FAPI | |||
DosQCurDir | Returns the full path name of the current directory | DOSCALLS | API/FAPI | Done | |
DosQCurDisk | Determines the current default drive for the requesting process | DOSCALLS | API/FAPI | Done | |
DosQFileMode | Queries the mode (attribute) of the specified file | DOSCALLS | API/FAPI | Done | |
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