Difference between revisions of "FIOLIB"

Revision as of 17:07, 21 December 2009

The FIOLIB is needed to use the programming language C for FutureOS. There are CP/M versions of Small-C and Windows-based cross-compilers of the C language. Use FIOLIB.C instead of IOLIB.C. The FIOLIB.C contains all needed C functions to use FutureOS system-calls.

You can take a normal C program compile it, assemble it, link the object-code with FIOLIB (and all other needed libraries), then add a header to the *.COM file with COMFU.COM.

To start such an C-program under FutureOS you have to start the RUNC-environment previously. RUNC expands the features of FIOLIB. With RUNC it is possible to store functions in expansion RAM, leaving more main memory free for C applications.

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.

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)!!

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 is 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).

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.