VFOSSIL - An OS/2-Subset Video FOSSIL Appendage

Version 1.00, May 23, 1988

Rick Moore, Solar Wind Computing
FidoNet Address: 1:115/333





FidoNet Standards Committee index: FSC-0021





















Copyright (C) 1988, Rick Moore, Homewood, IL, 60430. All rights reserved.

This document may be distributed freely as long as it is distributed in its
original, unmodified form.

VFOSSIL - An OS/2-Subset Video FOSSIL Appendage FSC-0021
Page 2


VFOSSIL design criteria:

The VFOSSIL appendage proposed here is designed to be an compatible subset of
the OS/2 VIO subsystem. All services are proper subsets of the equivalent OS/2
VIO API's, and if you stick to the services defined in this document, you
will be able to compile and run your programs with very minor changes in an
OS/2 environment.

VFOSSIL (and OS/2 VIO at this time) only supports text modes. It is possible
to use the "set mode" service to set a graphics mode, but that is the only
support for pixel-oriented graphics functions provided by VFOSSIL. The minimum
environment supported by VFOSSIL is a 80 by 24 monochrome text screen, and any
program using VFOSSIL calls should be capable of operating within this level of
support. By querying the VFOSSIL, the full capabilities of a specific
implementation may be determined and used, but all programs using VFOSSIL
should be capable of operating with the 80 by 24 monochrome text environment.


The organization of the video screen:

The virtual screen is organized in rows of columns of character/attribute
pairs, hereafter referred to as cells. The characters actually displayed
are located on the even addresses, the attribute for each character is
located at character+1.

Regardless of the manner in which the video screen is actually organized, the
programmer will view it as a a contiguous area of memory, referred to as the
"logical video buffer" (LVB). The LVB is (NumRow * NumCol) cells in length.

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Page 3

VFOSSIL installation:

The VFOSSIL appendage is installed via the standard FOSSIL external
application function. The FOSSIL interrupt (14h) is issued with the
following parameters:

AH = 7EhInstall appendage
AL = 81hVFOSSIL application code
DX = offset of VFOSSIL entry point
ES = segment of VFOSSIL entry point

Upon return from the FOSSIL interrupt, the following registers are
modified:

AX = 1954hFOSSIL signature
BL = 81hVFOSSIL application code
BH = 01h - Installation was successful
00h - Installation was unsuccessful

VFOSSIL removal:

The VFOSSIL appendage is removed via the standard FOSSIL external
application function. The FOSSIL interrupt (14h) is issued with the
following parameters:

AH = 7FhRemove appendage
AL = 81hVFOSSIL application code
DX = offset of VFOSSIL entry point
ES = segment of VFOSSIL entry point

Upon return from the FOSSIL interrupt, the following registers are
modified:

AX = 1954hFOSSIL signature
BL = 81hVFOSSIL identification code
BH = 01h - Removal was successful
00h - Removal was unsuccessful

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Page 4


VFOSSIL functions called via the standard FOSSIL interrupt (14h):

The following three functions are called via the standard FOSSIL interrupt,
int 14h. All other VFOSSIL functions are called via the OS/2 compatible
direct call interface.

Subfunction 00h - Return VFOSSIL information

Entry:AH = 81hVFOSSIL application code
AL = 00hVFOSSIL subfunction
ES:DI = Far pointer to VFOSSIL information structure

Exit:AX = 1954h FOSSIL signature

This function is used before calling the open function (sub-function 01h)
to determine the characteristics of the VFOSSIL. Such things returned in
the structure are current version level and number of functions supported.

The format of the information structure filled in by this call is as
follows:

DWSize of this structure, in bytes, including this field
DWVFOSSIL major version
DWVFOSSIL revision level
DWHighest VFOSSIL application function supported

Subfunction 01h - Open VFOSSIL

Entry:AH = 81hVFOSSIL application code
AL = 01hVFOSSIL subfunction
CX = Length of application function table (in bytes)
ES:DI = Far pointer to application function table

Exit:BH = Highest VFOSSIL application function supported
AX = 1954hFOSSIL signature

This VFOSSIL subfunction will initialize the table pointed to by
ES:DI with far pointers to the VFOSSIL application services. The
number of far pointers initialized is equal to the value returned
in register BH + 1. Under no circumstances will the number of
far pointers initialized exceed the value passed in register CX / 4.
All other processing necessary to ready the VFOSSIL for use by the
application program should be performed at this time.

Subfunction 02h - Close VFOSSIL

Entry:AH = 81hVFOSSIL application code
AL = 02hVFOSSIL subfunction

Exit:AX = 1954hFOSSIL signature

This VFOSSIL function terminates all VFOSSIL operations, and leaves
the VFOSSIL in a state that allows for it to be removed from memory,
or to be reinitialized via VFOSSIL function 01h.

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 5


VFOSSIL application services:

All calls to VFOSSIL services are made in a manner identical to the OS/2 API
protocol. All services are entered via a far call, with parameters passed
via the stack. All services return an error code in register AX. The
parameters are pushed onto the stack Pascal-style, from left to right. The
parameters are passed on the stack in one of the three following ways:

WORD A one-word value pushed directly onto the stack

DWRD A double-word value pushed directly onto the stack
(low word first, followed by the high word)

PTR A far pointer to a memory area. Far pointers are passed
as double-word values, segment followed by offset.

Single-word and double-word input parameters are always passed as WORD and
DWRD. If the service returns information in the parameter field itself,
then it is pushed as a PTR, even if the object is a WORD or a DWRD. Variable
length parameters, such as data structures or ASCIIZ strings, are always
passed as PTR objects.

All cursor coordinates are expressed as zero (0) based numbers.

Each VFOSSIL service requires a "handle" parameter as the last parameter
passed to the service. At this time, zero (0) is the only valid handle.

The actual addresses used to call the application services are contained in
the address table filled in by the VFOSSIL initialization call described
above. All addresses are in far (segment/offset) format. Here is the format
of the application service address table:

Table+00hVioGetModeQuery current video mode
+04hVioSetModeSet video mode
+08hVioGetConfigQuery video hardware configuration
+0ChVioWrtTTYWrite data in TTY mode
+10hVioGetANSIQuery current ANSI state
+14hVioSetANSISet ANSI state
+18hVioGetCurPosQuery current cursor position
+1ChVioSetCurPosSet cursor position
+20hVioGetCurTypeQuery current cursor parameters
+24hVioSetCurTypeSet cursor parameters
+28hVioScrollUpScroll screen up
+2ChVioScrollDnScroll screen down
+30hVioReadCellStrRead cell string from display
+34hVioReadCharStrRead char string from display
+38hVioWrtCellStrWrite cell string
+3ChVioWrtCharStrWrite char string (existing attributes)
+40hVioWrtCharStrAttWrite char string (constant attributes)
+44hVioWrtNAttrReplicate attribute
+48hVioWrtNCellReplicate cell
+4ChVioWrtNCharReplicate char

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 6


VioGetMode - Query current video mode


Parameters:

PTRPointer to a video mode data structure
WORDVIO handle (must be 0)


Video mode data structure:

DWStructure length (including this field)
DBMode characteristics
-------0Monochrome/printer adapter
-------1Other adapter
------0-Text mode
------1-Graphics mode
-----0--Enable color
-----1--Disable color (black and white)
DBNumber of colors supported by the display
1 = 2 colors
2 = 4 colors
4 = 16 colors
DWNumber of text columns
DWNumber of text rows
DWReserved
DWReserved
DDReserved


A partial video mode buffer may be specified. VFOSSIL returns only the data
that will fit into the buffer. The minimum buffer length is 3, and the
maximum buffer length is 12. Partial fields are not returned.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
382 - Buffer too small
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 7


VioSetMode - Set video mode


Parameters:

PTRPointer to a video mode data structure (see VioGetMode)
WORDVIO handle (must be 0)


A partial video mode buffer may be specified. The minimum buffer length is 3,
and the maximum buffer length is 12. Partial fields are not supported. The
remaining fields are set to default values.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
355 - Unsupported mode
382 - Buffer too small
421 - Invalid VIO parameter
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 8


VioGetConfig - Query video hardware configuration


Parameters:

PTRPointer to a video configuration data area
WORDVIO handle (must be 0)


Video configuration data area:

DWStructure length (includes this field)
DWAdapter type
0 = Monochrome/printer
1 = CGA
2 = EGA
3 = VGA
7 = 8514A
DWDisplay type
0 = Monochrome
1 = Color
2 = Enhanced color
9 = 8514
DDAdapter memory size


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
382 - Buffer too small
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 9


VioWriteTTY - Write data in TTY mode


Parameters:

WORDPointer to a character string that VFOSSIL will write
to the screen
WORDString length
WORDVIO handle (must be 0)


This service writes a string to the video screen in TTY mode. The characters
CR, LF, BS, TAB, and BELL are interpreted as control values rather than
being display as values. If ANSI mode has been enabled (see VioGetANSI,
VioSetANSI), then ANSI control sequences are also interpreted as control
strings. In ANSI mode, this service is not required to be reentrant, and
should not be called when a MS/DOS function is in progress. When in non-ANSI
mode, this service is required to be reentrant, and may be called from
within a MS/DOS function. If the write goes beyond the end of a line, it
continues at the start of the next line. The write terminates at the end of
the screen. The cursor is left positioned at the next character position to
be written.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 10


VioGetANSI - Query current ANSI state


Parameters:

PTRPointer to a one-word field in which VFOSSIL will return the
current ANSI state:
0 = Off
1 = On
WORDVIO handle (must be 0)


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 11


VioSetANSI - Set ANSI state


Parameters:

PTRPointer to a one-word field indicating how ANSI processing
is to be set:
0 = Off
1 = On
WORDVIO handle (must be 0)


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
421 - Invalid VIO parameter
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 12


VioGetCurPos - Query current cursor position


Parameters:

PTRPointer to a one word field in which VFOSSIL will return
the current cursor row
PTRPointer to a one word field in which VFOSSIL will return
the current cursor column
WORDVIO handle (must be 0)


This service returns the current cursor position. Cursor coordinates are
zero based.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 13


VioSetCurPos - Set cursor position


Parameters:

WORDDesired cursor row
WORDDesired cursor column
WORDVIO handle (must be 0)


This service sets the cursor position to the zero based coordinates specified
by the parameters. If either of the parameters is invalid, the cursor
position is left unchanged.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 14


VioGetCurType - Query current cursor parameters


Parameters:

PTRPointer to a cursor type data area
WORDVIO handle (must be 0)


Cursor type data area:

DWCursor start line
DWCursor end line
DWCursor width (always 1)
DWCursor attribute (-1 = hidden)


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 15


VioSetCurType - Set cursor parameters


Parameters:

PTRPointer to a cursor type data area (see VioGetCurType)
WORDVIO handle (must be 0)


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
421 - Invalid VIO parameter
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 16


VioScrollUp - Scroll screen up


Parameters:

WORDTop row of the scroll area
WORDLeft column of the scroll area
WORDBottom row of the scroll area
WORDRight column of the scroll area
WORDNumber of rows to scroll. A value of -1 causes the scroll
area to be cleared.
PTRPointer to a char/attr cell that is used to fill the scroll
area.
WORDVIO handle (always 0)


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 17


VioScrollDn - Scroll screen down


Parameters:

WORDTop row of the scroll area
WORDLeft column of the scroll area
WORDBottom row of the scroll area
WORDRight column of the scroll area
WORDNumber of rows to scroll. A value of -1 causes the scroll
area to be cleared.
PTRA pointer to a char/attr cell that is used to fill the scroll
area.
WORDVIO handle (always 0)


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 18


VioReadCellStr - Read cell string from display


Parameters:

PTRPointer to a buffer into which the cell string is to be
placed
PTRPointer to a one-word field which, upon entry, specifies
the length of the cell buffer (in bytes), and, on return,
contains the number of bytes actually read. Each cell
occupies two bytes, so the number of cells read is equal to
half of the buffer length specified.
WORDRow where the read is to start
WORDColumn where the read is to start
WORDVIO handle (always 0)


If the read request extends beyond the end of the line, it continues at the
first column of the next line. If an attempt is made to read past the end of
the screen, the read operation terminates and the length field is set to the
actual number of bytes read.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 19



VioReadCharStr - Read character string from display


Parameters:

PTRPointer to a buffer into which the character string is to be
placed
PTRPointer to a one-word field which, upon entry, specifies
how many characters are to be read, and, on return,
contains the number of characters actually read.
WORDRow where the read is to start
WORDColumn where the read is to start
WORDVIO handle (always 0)


If the read request extends beyond the end of the line, it continues at the
first column of the next line. If an attempt is made to read past the end of
the screen, the read operation terminates and the length field is set to the
actual number of characters read.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 20


VioWrtCellStr - Write a cell string


Parameters:

PTRPointer to the cell string to be written
WORDCell string length. Since each cell occupies two bytes,
this number is twice the number of cells to be written.
WORDRow at which write is to begin
WORDColumn at which write is to begin
WORDVio handle (must be 0)


If the write request extends beyond the end of the line, it continues at the
first column of the next line. If an attempt is made to write past the end of
the screen, the write operation terminates.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 21


VioWrtCharStr - Write a character string, using existing attributes


Parameters:

PTRPointer to the character string to be written
WORDCharacter string length
WORDRow at which write is to begin
WORDColumn at which write is to begin
WORDVio handle (must be 0)


The attributes of the display cells whose characters are replaced are not
modified. If the write request extends beyond the end of the line, it
continues at the first column of the next line. If an attempt is made to
write past the end of the screen, the write operation terminates.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 22


VioWrtCharStrAtt - Write a character string, using constant attribute


Parameters:

PTRPointer to the character string to be written
WORDCharacter string length
WORDRow at which write is to begin
WORDColumn at which write is to begin
PTRPointer to the display attribute to be used with each
character written
WORDVio handle (must be 0)


If the write request extends beyond the end of the line, it continues at the
first column of the next line. If an attempt is made to write past the end of
the screen, the write operation terminates.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 23


VioWrtNAttr - Replicate an attribute byte, leaving characters unchanged


Parameters:

PTRPointer to the display attribute to be replicated
WORDReplication count
WORDRow at which write is to begin
WORDColumn at which write is to begin
WORDVio handle (must be 0)


The characters contained in the display cells whose attributes are replaced
are not modified. If the write request extends beyond the end of the line,
it continues at the first column of the next line. If an attempt is made to
write past the end of the screen, the write operation terminates.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 24


VioWrtNCell - Replicate a cell


Parameters:

PTRPointer to the cell to be replicated
WORDReplication count
WORDRow at which write is to begin
WORDColumn at which write is to begin
WORDVio handle (must be 0)


If the write request extends beyond the end of the line, it continues at the
first column of the next line. If an attempt is made to write past the end of
the screen, the write operation terminates.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle

VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021
Application Services Page 25


VioWrtNChar - Replicate an character, leaving attributes unchanged


Parameters:

PTRPointer to the character to be replicated
WORDReplication count
WORDRow at which write is to begin
WORDColumn at which write is to begin
WORDVio handle (must be 0)


The attributes contained in the display cells whose characters are replaced
are not modified. If the write request extends beyond the end of the line,
it continues at the first column of the next line. If an attempt is made to
write past the end of the screen, the write operation terminates.


Error codes returned:

0 - Successful completion
116 - Internal VIO failure
358 - Invalid row value
359 - Invalid column value
436 - Invalid VIO handle