Category : BBS Programs+Doors
Archive   : FSC-0021.ZIP
Filename : FSC-0021.DOC

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 = 7Eh Install appendage
AL = 81h VFOSSIL 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 = 1954h FOSSIL signature
BL = 81h VFOSSIL 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 = 7Fh Remove appendage
AL = 81h VFOSSIL 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 = 1954h FOSSIL signature
BL = 81h VFOSSIL 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 = 81h VFOSSIL application code
AL = 00h VFOSSIL 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:

DW Size of this structure, in bytes, including this field
DW VFOSSIL major version
DW VFOSSIL revision level
DW Highest VFOSSIL application function supported

Subfunction 01h - Open VFOSSIL

Entry: AH = 81h VFOSSIL application code
AL = 01h VFOSSIL 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 = 1954h FOSSIL 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 = 81h VFOSSIL application code
AL = 02h VFOSSIL subfunction

Exit: AX = 1954h FOSSIL 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 +00h VioGetMode Query current video mode
+04h VioSetMode Set video mode
+08h VioGetConfig Query video hardware configuration
+0Ch VioWrtTTY Write data in TTY mode
+10h VioGetANSI Query current ANSI state
+14h VioSetANSI Set ANSI state
+18h VioGetCurPos Query current cursor position
+1Ch VioSetCurPos Set cursor position
+20h VioGetCurType Query current cursor parameters
+24h VioSetCurType Set cursor parameters
+28h VioScrollUp Scroll screen up
+2Ch VioScrollDn Scroll screen down
+30h VioReadCellStr Read cell string from display
+34h VioReadCharStr Read char string from display
+38h VioWrtCellStr Write cell string
+3Ch VioWrtCharStr Write char string (existing attributes)
+40h VioWrtCharStrAtt Write char string (constant attributes)
+44h VioWrtNAttr Replicate attribute
+48h VioWrtNCell Replicate cell
+4Ch VioWrtNChar Replicate char

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


VioGetMode - Query current video mode


Parameters:

PTR Pointer to a video mode data structure
WORD VIO handle (must be 0)


Video mode data structure:

DW Structure length (including this field)
DB Mode characteristics
-------0 Monochrome/printer adapter
-------1 Other adapter
------0- Text mode
------1- Graphics mode
-----0-- Enable color
-----1-- Disable color (black and white)
DB Number of colors supported by the display
1 = 2 colors
2 = 4 colors
4 = 16 colors
DW Number of text columns
DW Number of text rows
DW Reserved
DW Reserved
DD Reserved


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:

PTR Pointer to a video mode data structure (see VioGetMode)
WORD VIO 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:

PTR Pointer to a video configuration data area
WORD VIO handle (must be 0)


Video configuration data area:

DW Structure length (includes this field)
DW Adapter type
0 = Monochrome/printer
1 = CGA
2 = EGA
3 = VGA
7 = 8514A
DW Display type
0 = Monochrome
1 = Color
2 = Enhanced color
9 = 8514
DD Adapter 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:

WORD Pointer to a character string that VFOSSIL will write
to the screen
WORD String length
WORD VIO 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:

PTR Pointer to a one-word field in which VFOSSIL will return the
current ANSI state:
0 = Off
1 = On
WORD VIO 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:

PTR Pointer to a one-word field indicating how ANSI processing
is to be set:
0 = Off
1 = On
WORD VIO 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:

PTR Pointer to a one word field in which VFOSSIL will return
the current cursor row
PTR Pointer to a one word field in which VFOSSIL will return
the current cursor column
WORD VIO 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:

WORD Desired cursor row
WORD Desired cursor column
WORD VIO 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:

PTR Pointer to a cursor type data area
WORD VIO handle (must be 0)


Cursor type data area:

DW Cursor start line
DW Cursor end line
DW Cursor width (always 1)
DW Cursor 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:

PTR Pointer to a cursor type data area (see VioGetCurType)
WORD VIO 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:

WORD Top row of the scroll area
WORD Left column of the scroll area
WORD Bottom row of the scroll area
WORD Right column of the scroll area
WORD Number of rows to scroll. A value of -1 causes the scroll
area to be cleared.
PTR Pointer to a char/attr cell that is used to fill the scroll
area.
WORD VIO 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:

WORD Top row of the scroll area
WORD Left column of the scroll area
WORD Bottom row of the scroll area
WORD Right column of the scroll area
WORD Number of rows to scroll. A value of -1 causes the scroll
area to be cleared.
PTR A pointer to a char/attr cell that is used to fill the scroll
area.
WORD VIO 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:

PTR Pointer to a buffer into which the cell string is to be
placed
PTR Pointer 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.
WORD Row where the read is to start
WORD Column where the read is to start
WORD VIO 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:

PTR Pointer to a buffer into which the character string is to be
placed
PTR Pointer 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.
WORD Row where the read is to start
WORD Column where the read is to start
WORD VIO 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:

PTR Pointer to the cell string to be written
WORD Cell string length. Since each cell occupies two bytes,
this number is twice the number of cells to be written.
WORD Row at which write is to begin
WORD Column at which write is to begin
WORD Vio 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:

PTR Pointer to the character string to be written
WORD Character string length
WORD Row at which write is to begin
WORD Column at which write is to begin
WORD Vio 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:

PTR Pointer to the character string to be written
WORD Character string length
WORD Row at which write is to begin
WORD Column at which write is to begin
PTR Pointer to the display attribute to be used with each
character written
WORD Vio 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:

PTR Pointer to the display attribute to be replicated
WORD Replication count
WORD Row at which write is to begin
WORD Column at which write is to begin
WORD Vio 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:

PTR Pointer to the cell to be replicated
WORD Replication count
WORD Row at which write is to begin
WORD Column at which write is to begin
WORD Vio 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:

PTR Pointer to the character to be replicated
WORD Replication count
WORD Row at which write is to begin
WORD Column at which write is to begin
WORD Vio 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