en:docs:fapi

This is part of Family API which allow to create dual-os version of program runs under OS/2 and DOS

Note: This is legacy API call. It is recommended to use 32-bit equivalent

2021/09/17 06:47 · prokushev
2021/08/20 05:18 · prokushev

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. Versions up to 1.11 is a original OS/2 Family API. 1.20 and higher is a osFree extensions.

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 around 80-90 function calls (various information sources differ) that could be used in FAPI programs.

Name Description Module (OS/2) Library (DOS) Status (OS/2) Status (DOS) FAPI Version
BadDynLink Terminates execution with error message API/FAPI Done 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
DosCLIAccess Request I/O privilege for disabling and enabling interrupts DOSCALLS API/FAPI Done 1.00
DosPortAccess Request or release access to ports for I/O privilege 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 process environment 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 Retrieve a message from the specified system message file DOSCALLS API/FAPI 1.00
DosGetVersion Return the OS version number DOSCALLS API/FAPI Done Done 1.00
DosInsMessage Insert variable text string information into the body of a message DOSCALLS API/FAPI 1.00
DosMkDir Create a subdirectory DOSCALLS API/FAPI Done Done 1.00
DosMkDir2 Create a subdirectory with EA DOSCALLS API/FAPI Done Done ????
DosMove Move a file object to another location, change its name DOSCALLS API/FAPI Done 1.00
DosNewSize Changes the size of a file DOSCALLS API/FAPI Done 1.00
DosPutMessage Output the message 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 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 Set the date and time DOSCALLS API/FAPI Done 1.00
DosSetFileInfo Set attribute and extended attribute information for a file DOSCALLS API/FAPI Done 1.00
DosSetFileMode Changes the mode (attribute) of the specified file DOSCALLS API/FAPI Done 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 Suballocate portions of a segment DOSCALLS API/FAPI 1.00
DosSubFree Free memory previously allocated by DosSubAlloc DOSCALLS API/FAPI 1.00
DosSubSet Initialize a segment for suballocation 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 Case mapping on a string DOSCALLS API/FAPI 1.10
DosDevIOCtl Control functions on a device DOSCALLS API/FAPI 1.00
DosDevIOCtl2 Control functions on a device DOSCALLS API/FAPI ????
DosError Receive hard error notification DOSCALLS API/FAPI Done 1.00
DosErrClass Receive hard error code information DOSCALLS API/FAPI 1.10
DosExecPgm Execute another program as a child process DOSCALLS API/FAPI Done 1.00
DosExit End The current thread or process DOSCALLS API/FAPI Done 1.00
DosFileLocks Locks and unlock a range in an opened file DOSCALLS API/FAPI Done 1.00
DosFindClose Finish DosFindFirst or DosFindNext directory search function sequence DOSCALLS API/FAPI Done 1.00
DosFindFirst Finds the first file object or group of file objects whose name(s) match the specification DOSCALLS API/FAPI Done 1.00
DosFindFirst2 Finds the first file object or group of file objects whose name(s) match the specification DOSCALLS API/FAPI ???
DosFindNext Locate the next set of directory entries DOSCALLS API/FAPI Done 1.00
DosGetCtryInfo Obtain country-dependent formatting information that resides in the country information file DOSCALLS API/FAPI 1.10
DosGetDBCSEv Obtain a DBCS (double byte character set) environmental vector that resides in the country information file DOSCALLS API/FAPI Done 1.10
DosGetCP Query the current process code page and the prepared system code pages DOSCALLS API/FAPI Done 1.10
DosSetCP Set process code page and the session's display code page and keyboard code page DOSCALLS API/FAPI Done 1.10
DosGetCollate Obtain a collating sequence table DOSCALLS API/FAPI 1.10
DosHoldSignal Temporarily disable or enable signal processing for the current process DOSCALLS API/FAPI 1.00
DosOpen Open a file, a named pipe, or a device DOSCALLS API/FAPI Done 1.00
DosOpen2 Open a file with extended attributes DOSCALLS API/FAPI ????
DosQFileInfo Return information for a specific file DOSCALLS API/FAPI Done 1.00
DosRead Read the specified number of bytes from a file, pipe, or device to a buffer location DOSCALLS API/FAPI Done 1.00
DosReallocHuge Change the size of memory originally allocated by DosAllocHuge DOSCALLS API/FAPI 1.00
DosReallocSeg Reallocate a segment after discard or changes the size of a segment already allocated DOSCALLS API/FAPI Done 1.00
DosSetCtryCode DOSCALLS API/FAPI 1.00
DosSetFHandState Set the state of the specified file DOSCALLS API/FAPI 1.00
DosSetSigHandler Set signal handler DOSCALLS API/FAPI Done 1.00
DosAllocShrSeg Allocate a named shared memory segment to a process DOSCALLS API/FAPI Done 1.20
DosGetShrSeg Accesses a shared memory segment previously allocated by another process DOSCALLS API/FAPI Done 1.20
DosLoadModule Load a dynamic link module and returns a handle for the module DOSCALLS API/FAPI Done 1.20
DosFreeModule Free the reference to a dynamic link module for a process DOSCALLS API/FAPI Done 1.20
KbdCharIn Return a character data record from the keyboard KBDCALLS API/FAPI Done 1.00
KbdFlushBuffer Clear the keystroke buffer KBDCALLS API/FAPI Done 1.00
KbdGetStatus Get the current state of the keyboard KBDCALLS API/FAPI Done 1.00
KbdSetStatus Set the characteristics of the keyboard KBDCALLS API/FAPI 1.00
KbdStringIn Read a character string (character codes only) from the keyboard KBDCALLS API/FAPI 1.00
KbdPeek Return any available character data record from the keyboard without removing it from the buffer KBDCALLS API/FAPI Done 1.00
VioGetBuf Return the address of the logical video buffer (LVB) VIOCALLS API/FAPI 1.20
VioGetCurPos Return the coordinates of the cursor VIOCALLS API/FAPI Done 1.00
VioGetCurType Get cursor type VIOCALLS API/FAPI Done 1.00
VioGetPhysBuf Get addressability to the physical display buffer VIOCALLS API/FAPI 1.00
VioReadCellStr Read a string of character-attribute pairs from the screen VIOCALLS API/FAPI Done 1.00
VioReadCharStr Read a string of characters from the display VIOCALLS API/FAPI Done 1.00
VioScrollDn Scroll the entire display buffer (or area specified within the display buffer) down VIOCALLS API/FAPI Done 1.00
VioScrollLf Scroll the entire display buffer (or area specified within the display buffer) to the left VIOCALLS API/FAPI 1.00
VioScrollRt Scroll the entire display buffer (or area specified within the display buffer) to the right VIOCALLS API/FAPI 1.00
VioScrUnLock Release ownership of (unlocks) the physical display buffer VIOCALLS API/FAPI Done 1.00
VioSetCurPos Set the cursor's coordinates on the screen VIOCALLS API/FAPI Done 1.00
VioSetCurType Set the cursor type VIOCALLS API/FAPI Done 1.00
VioSetMode Set the mode of the display VIOCALLS API/FAPI Done 1.00
VioShowBuf Update the physical display buffer with the logical video buffer (LVB) VIOCALLS API/FAPI 1.20
VioWrtCellStr Write a string of character-attribute pairs (cells) to the display VIOCALLS API/FAPI Done 1.00
VioWrtCharStr Write a character string to the display VIOCALLS API/FAPI Done 1.00
VioWrtCharStrAtt Write a character string with repeated attribute to the display VIOCALLS API/FAPI Done 1.00
VioWrtNAttr Write an attribute to the display a specified number of times VIOCALLS API/FAPI Done 1.00
VioWrtNCell Write a cell (character-attribute pair) to the display a specified number of times VIOCALLS API/FAPI Done 1.00
VioWrtNChar Write a character to the display a specified number of times VIOCALLS API/FAPI Done 1.00
VioWrtTTY Write a character string to the display starting at the current cursor position VIOCALLS API/FAPI Done 1.00
VioScrLock Request ownership of (locks) the physical display buffer VIOCALLS API/FAPI Done 1.00
VioGetMode Return the mode of the display VIOCALLS API/FAPI Done 1.20
VioGetConfig Return the video display configuration VIOCALLS API/FAPI Done 1.??
VioGetAnsi Return the current ANSI status On/Off state VIOCALLS API/FAPI Done 1.20
VioSetAnsi Activate or deactivate ANSI support VIOCALLS API/FAPI Done 1.20
VioScrollUp Sroll the entire display buffer (or area specified within the display buffer) up VIOCALLS API/FAPI Done 1.20
VioDeRegister Deregister alternate video system VIOCALLS API/FAPI Done 1.20
VioRegister Register alternate video system VIOCALLS API/FAPI Done 1.20
DosQHandType Get handle type DOSCALLS API/FAPI Done 1.00
DosGetProcAddr Get module procedure address DOSCALLS API/FAPI Done 1.20
DosGetPID Get process id DOSCALLS API/FAPI Done 1.00
DosSetMaxFH Set maximum file handlers DOSCALLS API/FAPI Done 1.20
DosGetModHandle Get module handle DOSCALLS API/FAPI Done 1.20
DosQPathInfo Get path information DOSCALLS API/FAPI 1.??
DosQFSAttach Query information about an attached file system DOSCALLS API/FAPI 1.??
VioGetState Return the current settings of adapter VIOCALLS API/FAPI 1.??
VioSetState Set the current settings of adapter VIOCALLS API/FAPI 1.??
VioGetCP Query the code page for display VIOCALLS API/FAPI 1.20
VioSetCP Set the code page for display VIOCALLS API/FAPI 1.20
VioGetFont Get current font VIOCALLS API/FAPI 1.??
VioSetFont Set current font VIOCALLS API/FAPI 1.??
VioModeWait Notify process about it must restore its video mode VIOCALLS API/FAPI 1.20
VioModeUndo VIOCALLS API/FAPI 1.20
VioPopUp Show temporary screen to display message VIOCALLS API/FAPI 1.20
VioEndPopUp Return from temporary screen VIOCALLS API/FAPI 1.20
VioSavRedrawWait Notifies application when it must save/redraw its screen VIOCALLS API/FAPI 1.20
VioSavRedrawUndo VIOCALLS API/FAPI 1.20
VioPrtSc Dump screen to printer VIOCALLS API/FAPI 1.20
VioPrtScToggle Toggle VioWrtTty also write to printer VIOCALLS API/FAPI 1.20
DosQSysInfo Query system variablies values DOSCALLS API/FAPI Done 1.20
DosMemAvail Query maximum availabe huge memory block DOSCALLS API/FAPI Done 1.20

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


en/docs/fapi.txt · Last modified: 2021/09/22 09:40 by prokushev