FIOLIB.TXT - Help-file for FIOLIB           387 lines                2013.07.28
=================================

File created by Dr. Stefan W. Stumpferl

Before we start: You can have a look at FTEST.C where some of the functions
were used.

cpcstart()
----------
This function prepares FutureOS for running Small-C programs. It is only used
by FIOLIB.C itself. The user doesn't and shouldn't use that function.

byebye()
--------
This function is used to end a Small-C program under FutureOS. You can use this
function or just end the program. Both has the same effect. The function byebye
displays the message  "Press any key to return to the Desktop." , then it waits
for a pressed key and finally jumps back to the Desktop of FutureOS.

oscall(adr,regpack)
-------------------
int adr;
int *regpack; /* af,hl,de,bc */
This function is used to call a subroutine of the OS. The contents of "regpack"
are loaded in the Z80 registers, then the OS-routine "adr" at the address "adr"
is called. And then the Z80 registers are written back in "regpack".  Beginning
at regpack the 16 Bit registers AF, HL, DE and BC follow:
regs[0]=a; /* AF */
regs[1]=b; /* HL */
regs[2]=c; /* DE */
regs[3]=d; /* BC */

mode(n)
-------
int n;
Set the screen MODE to 0, 1, 2 or 3.  Mode 0, 1 and 2 are the same as with the
MODE command under Basic. Don't use Mode 3! The mode is changed and the screen
will be cleared, the cursor is set to the most left, most upper position.

cls()
-----
This is the same as the BASIC command CLS. It clears the screen and the cursor
is set to the most left, most upper position.

frame()
-------
Waits for the Frame Fly Back. Returns as soon as the screen is displayed and
before the raster scan starts to draw the next screen.
Can be used to synchronise events with the drawing of the screen, to make
programs flicker free.

s80x25()
--------
Sets the format of the screen to 80 columns and 25 lines (in Mode 2), or to 40
columns and 25 lines (in Mode 1). Only the screen format is changed, NO cls!

s64x32()
--------
Sets the format of the screen to 64 columns and 32 lines (screen Mode 2), or 32
columns and 32 lines (in Mode 1). Only the screen format is changed, NO cls!

pen0(n)
-------
int n;
Changes the PEN for MODE 0. This type of PEN selection is needed if you want to
paint dots ( with plot(x,y) ) under SCREEN MODE 0. You can use PEN 1 - 15. It's
the same like the command PEN in Basic, when using MODE 0. Only the PEN of MODE
0 is changed. The PEN selections of Mode 1 and 2 aren't changed!

pen1(n)
-------
int n;
Changes the PEN for MODE 1. You can use PEN 1, 2 or 3. It's the same like the
command PEN in Basic. If you select PEN 0 then the two-color PEN is selected.
Only the PEN of MODE 1 is changed. The PEN's for Mode 0 and 2 aren't changed!

pen2(n)
-------
int n;
Selects character attributes for SCREEN MODE 2.  Integer n must be between 0
and 4. So you can use normal, italics, underlined, inverted and streaked out
character attributes.
Only the character-attributes for MODE 2 are changed!!! The PEN's for Mode 0
and 1 aren't changed!

ink(p,c)
--------
int p,c;
The INK function changes the COLOR of a PEN. It's the same like the INK command
of Basic. Attention: You can only give ONE colour to the PEN. PEN 16 is BORDER!

locate(x,y)
-----------
int x,y;
Function LOCATE is nearly the same like the Basic command LOCATE, you give the
column (x) and the line (y) where the cursor should be positioned. You have 80
columns in Mode 2 and 40 columns in Mode 1 (if the screnn has 80x25 format).

plot(x,y)
---------
int x,y;
The function PLOT allows to set a POINT on the screen. You can use SCREEN MODEs
0, 1 or 2. Unter Mode 2, PEN 1 is always used. Under the MODEs 0 and 1 the used
PEN depends on the functions pen0(n) and pen1(n), which preselect the PEN. MODE
2 screen format should be 64*32. The screen format (rows, lines) for MODE 0 and
1 can be selected freely. The coordinate position 0,0 is the upper left corner.

move(x,y)
---------
int x,y;
The function MOVE allows to set the graphic cursor (start coordinates of a line
for example) to X and Y. The coordinate position 0, 0 is the upper left corner.

draw(x,y)
---------
int x,y;
DRAWs a line form the actual graphic cursor position (use MOVE to set it!) to
the coordinates X and Y. The coordinate position 0, 0 is the upper left corner.
You can use this function in all screen-MODEs, -formats and with all PENs.

circle(r)
---------
int r;
CIRCLEs can be created by this routine.  The center of the CIRCLE should be set
before through the MOVE(X,Y) function, else the actual X and Y coordinates will
be used. The variable r contains the RADIUS of the CIRCLE. (Use under Mode 1)!!

set_time(l,h)
-------------
int h,l;
*** not now ***

get_time(l,h)
-------------
int *h,*l;
*** not now ***

lscr(s)
-------
char *s;
Loads a 16 KB screen to address &C000. Do not load pictures with file-header!!!
To define the picture / screen which should be loaded, a string with the format
"DUU:filenameEXT" has to be given to the function. "D" is the DRIVE "a".."m" or
"A".."M", UU is the USER-number in hexadezimal "00".."FE", "filename" and "EXT"
define the name of the file and the extension. You must type in every "space"!!
Between the "filename" and the "EXT" is _NO_ point!!! And _NEVER_ use User &FF!

fopen(name,mode)
----------------
char *name,*mode;
Opens a file to read or to write. A file-name must be provided in the format:
"DUU:FilenameExt".  D ist the Drive-letter (A..M),  U is the User-number in a
hexadezimal view. Between the Name and the Extension of the file, there is NO
Dot! An example: "B00:Role-Play-D". The string "filename" isn't allowed to be
located between &4000 and &7FFF, there it can't be read!!!
The File-mode "mode" can be "r"/"R", "w"/"W", "a"/"A". "R" opens a file to be
read. "W" opens a file to be written. (("A" appends a file-not finished yet))
You can access every byte of every file everytime. But a file can't be longer
than 16 KB. If you need more space, just open another 16 KB file!

If fopen(name,mode) is successfull the number of the file is given back, this
number is between 32 and 63 (&20-&3F). Else "EOF" is given back!

fclose(f)
---------
int f;
Close an previously opened file with the File-number "f". Whereas "f" must lie
between 32 and 63 (&20-&3F). The file "f" is written back to disc.

sfile(f)
--------
int f;
Select file to read/write from/to. The File-number "f" must lie between 32 and
63 (&20-&3F). The file is selected for all future read/write operations, until
sfile(f) is used again or a new file is opened with fopen(name,mode).

sfico(c)
--------
int c;
Set File-Counter of the actual selected File. The File-Couter must be an value
between &4000 and &7FFF. The File-Counter defines where to read from, or where
to write to (inside the file).

cat()
-----
*** not now ***

err(s)
------
char *s;
Returns the message "Error: " and displays an error number. Can be used to give
an error-message to the user.

putchar(c)
----------
char c;
Uses putc() to display a character on the screen or write a byte to a file.

putc(c,unit)
------------
char c;
int unit;
Uses putb() to display a character. Adds CR control code after LF control code.

putb(c,unit)
------------
char c;
int unit;
Display a byte on the screen or write a byte to a file.

gets(s)
-------
char *s;
Get a new/empty string from the keyboard, the string is maximal 80 Bytes long.
This function switches the screen MODE to 2,  the string is entered at cursor-
position.

edst(s)
-------
char *s;
Edit a string at address "s", the string is 80 Bytes long. This function
switches the screen MODE to 2,  the string is edited at cursor-position.

basedit(b)
----------
char *b;
Edit a string at address "b",  whereby "b" must lie between &4000-&BFFF, the
edited string is 80 Bytes long. This function switches the screen MODE to 2,
the string is edited at the cursor-position.

getkey(n)
---------
int *n;
GETKEY reads the actual pressed key from the keyboard. It waits until a key is
pressed. The pressed key is returned in "n".

getchar()
---------
The Function waits until no key is pressed, then it reads the first pressed key
from the keyboard. It waits for a pressed key, then returns. Uses getc(stdin);

getc(unit)
----------
int unit;
Get character from keyboard or from file. (LF control codes are deleted?).
Uses getb(unit).

getb(unit)
----------
int unit;
Get byte from keyboard of from file.

puts(buf)
---------
char *buf;
Print a null-terminated string on the screen. Uses putchar(c);

upper(c)
--------
int c;
Converts letter to upper case.

getp(port)
----------
Input a byte from port "port".
Function format: getp(p) where p is a 16 bit port number

putp(value,port)
----------------
OUT byte "value" to 16 Bit port "port".
Function format: putp('A',n); or putp(value,n);

rnd(n)
------
int n;
rnd(n) returns an integer value between  0 and n.  If n is 0 the value will lie
within + / - 32 kB. Based on suggestions in Hamming's book on Numerical Methods
for Scientists and Engineers. A seed is multiplied by a large number causing an
overflow.

exit()
------
Exit the Small-C program, initializes OS and return to the Desktop.
No message is displayed. Jump to Desktop happens immediately.

alloc(b)
--------
int b;  /* # bytes desired */
Allocates (b) bytes of memory. Routine returns address of a block of memory.
The heap grows upwards.

free(addr)
----------
int addr;
This routine resets the top of heap pointer (HEAPTOP) to addr*

avail()
-------
avail() returns the number of bytes between top of heap (HEAPTOP) and the end
of the TPA (heapend). Remember that this includes the stack!

hex(x)
------
int x;
Returns hexadezimal byte, uses hexb(x);

hexb(x)
-------
int x;
Uses hexn(x); to display a hexadizimal byte.

hexn(x)
-------
int x;
Uses putchar(); to display hexadezimal characters.

strcmp(str1,str2)
-----------------
char *str1,*str2;
Compares two strings. This function returns an integer: less than, equal to, or
greater than zero depending on whether the string at 'str1' is less than, equal
to, or greater than the string at 'str2'.

strncmp(str1,str2,n)
--------------------
char *str1, *str2; int n;
Works like strcmp, except that a maximum of n characters are compared.

strcpy(tar,src)
---------------
char *tar,*src;
Copies the string at 'src' to 'tar'.

strncpy(tar,src,n)
------------------
char *src,*tar;
int n;
Copy string of n-bytes from "src" to "tar".  Works like strcpy(), except that n
characters are transferred - regardless of the length of the source string.  If
the source string is too long it is truncated and a null character is placed at
the end of the destination string.

strlen(s)
---------
char *s;
Returns the length of a given string, the count of the number of characters in
the string 's'. The null character at the end of the string is not included in
the count.

strcat(dest,sour)
-----------------
char *dest,*sour;
Function appends the string at 'sour' to the end of the string at 'dest'.
A null character terminates the end of the new 'dest' string. The space
reserved for 'dest' must be long enough to hold the resulting string.
The function returns 'dest'.

strncat(dest,sour,n)
--------------------
char *dest,*sour; int n;
Function works like strcat(), except that a maximum of n characters from the
source string are transferred to the destination.

strchr(str,c)
-------------
char *str,c;
Returns a pointer to the first occurrence of the character 'c' in the string
at 'str'. A NULL pointer is returned if the character is not found.

strrchr(str,c)
--------------
char *str,c;
Works like strchr(), except that the rightmost occurrence of the character is
searched for.

tolower(s)
----------
char *s;
Convert character to lower case.

toupper(s)
----------
char *s;
Converts character to upper case.

  387 lines                2013.07.28
=================================

File creat