-

LIBRARY PUBLIC DOCUMENT NDOS

From HI-TECH C for CP/M Fan WIKI(EN)
Jump to: navigation, search

NDOS 1.0 - By Konami Man, 2-2001

WHAT IS THIS?

NDOS is a library of C functions that allow you to conveniently use all the functions of MSX-DOS 2 (keyboard input / output and screen, access to files and directories, handling of environment variables, direct access to sectors, definition of disk error handling routines, etc.). NDOS functions in turn call those in the NASM library to perform the calls to the operating system, so always have to link both libraries together when compiling programs that make use of the functions of NDOS.

The complete distribution of NDOS includes the following files:

LIBNDOS.LIB
Library file containing the object code of all the functions of NDOS.
NDOS.H
File with the header of all the functions, in which also the necessary data structures are defined for some functions and some useful constants.
DOSCODES.H: This file defines the names of all functions of DOS 2, just as in the document "MSX DOS 2 Function Codes specification. "It also defines the names of all possible errors same as in the document "MSX DOS 2 Program Interface Specification", but the "." for "_" since the compiler does not accept names that contain points. For this reason some errors have been defined with a name other than the original, because it coincided with the name of some function. Errors with changed names are:
_SEEKE, original is .SEEK (error 0F3h)
_FOPENE, original is .FOPEN (error 0CAh)

This file is identical to the one included in the NASM distribution.

NDOS.TXT
This document.
NDOSE.TXT
English version of this document.
Files * .C and * .AS
The source codes of all NDOS functions.

This manual assumes that system concepts are known such as file descriptors ("file handles"), FIBs, variables of environment, etc. All of these concepts are explained in the DOS manual, documents "MSX-DOS 2 Program Interface Specification" and "MSX-DOS 2 Function Codes Specification ".

Likewise, the details of the NDOS functions do not explain details specifics regarding the use of the DOS calls involved, for example, possible error codes that can be generated by each of them or the peculiarities of the use of file descriptors that actually refer to devices. For this type of information you should also consult the documents.

NDOS functions are designed to be used under DOS 2. It may some work under DOS 1 but nothing is guaranteed.

STRUCTURES

In the file NDOS.H some data structures are defined that are necessary to use some functions. They are the following:

FLAGS

typedef struct {
        b0: 1;
        b1: 1;
        b2: 1;
        b3: 1;
        b4: 1;
        b5: 1;
        b6: 1;
        b7: 1;
} flags;

The flags type is used in functions that require input parameters and / or return flag-type results, i.e. multiple values of a bit encoded in one byte. You can convert a flags variable to a int type or vice versa by means of a simple cast.

DISKPARAM

typedef struct {
        uchar phdrive;
        uint  secsize;
        uchar secpclus;
        uint  secrsv;
        uchar fatcopies;
        uint  rootentr;
        uint  sectotal;
        uchar mediaid;
        uchar secpfat;
        uint  firstroot;
        uint  firstdata;
        uint  maxclus;
        uchar dirty;
        ulong volid;
        uint  clustotal;
        uint  clusfree;
        uint  dpbpnt;
        char  unused[2];
} diskparam;


This structure is used in the GETDPAR function to obtain the parameters of a disc. The meaning of each field of the structure is:

phdrive 
Physical unit number (1 = A :, etc).
secsize
Sector size (always 512 normally).
secpclus 
Sectors per cluster
secrsv 
Sectors reserved.
fatcopies 
Number of copies of the FAT.
rootentr 
Number of entries in the root directory.
sectotal 
Total number of logical sectors
mediaid 
Device descriptor byte.
secpfat
Number of sectors per FAT.
firstroot 
First sector of the root directory.
firstdata 
First sector of the data area.
maxclus
Maximum cluster number
dirty
It indicates that there are deleted files that can be recovered with UNDEL if it is not zero.
volid 
Volume label (-1 if none).
clustotal 
Total number of clusters.
clusfree 
Number of free clusters.
dpbpnt 
Pointer to the DPB (Drive Parameters Block) of the file.
unused 
Reserved, do not use.

FIB

This structure represents a FIB type memory block (File Info Block), normally used to search for files (FFIND function) but also can be used in other functions that support file names or FIBs indistinctly. 

typedef struct {
        char  alwaysff;
        char  fname[13];
        char  attrib;
        uint  time;
        uint  date;
        uint  startclus;
        ulong fsize;
        uchar drive;
        char  internal[38];
} fib;

The meaning of each field is:

alwaysff
It always contains the value 0xFF, indicating that it is an FIB and not a filename.
fname
File name in readable format (file.ext).
attrib
Byte of file attributes.
time
Time of last modification of the file.
date
Date of last modification of the file.
startclus
Initial Cluster of the file.
fsize
File size.
drive
Logical unit (1 = A, etc).
internal
Internal system information, do not modify.

DATE and TIME

Structures that represent a date and an hour respectively, used in the functions of obtaining / establishing the date of the system or a file. 

typedef struct {
        int year;
        int month;
        int day;
        int wday;
} date;

typedef struct {
int hour;
        int minute;
        int second;
} time;

The meaning of each field is:

year
Year (1980 to 2079)
month
Mes (1=January to 12=December)
day
Day of month (1 a 31)
wday
Day of week (0=Sunday a 6=Saturday)
hour
Hour (0 a 23)
minute
Minute (0 a 59)
second
Second (0 a 59)


Some functions, such as FFIND, require or return the date and time encoded in an int value. To convert from an int to a structure of type date or time, or vice versa, you can use the functions ITOT, TTOI, ITOD and DTOI.

PARSEDATA

Structure used in PARSEP and PARSEF functions to interpret a route and a filename, respectively. 

typedef struct {
        char* termchar;
        char* lastitem;
        int logdrive;
        flags f;
} parsedata;

The meaning of each field is:

termchar
Pointer to the end of the chain.
lastitem
Pointer to the last element in the string.
logdrive
Logical unit (1 = A, etc.).
f
Various flags:
f.b0=1 if not only unit is specified.
f.b1=1 if directory specified.
f.b2=1 if unit is specified.
f.b3=1 if filename specified.
f.b4=1 if extension is specified.
f.b5=1 if the last element is ambiguous (use wildcards).
f.b6=1 if the last item is "." Or "..".
f.b7=1 if the last item is "..".

CONSTANTS

In the file NDOS.H also define some constants that can be used as parameters for the functions or to interpret the results. They are the following:

System file descriptors

In all functions that support a file descriptor ("file handle") as parameter you can specify a system descriptor, which makes reference to a device instead of a file:


STDIN (0)
Screen output
STDOUT (1)
Keypad input
STDERR (2)
Output of error messages, normally identical to STDOUT
AUX (3)
Auxiliary device, default does nothing
PRN (4)
Printer

Modes of opening a file

They are used in the functions of opening and creating files:

F_NOWRITE
Can not write to the file
F_NOREAD
Can not read from file
F_NOINH
The file is not inherited by child processes created with FORK

You can combine two or more s with the "|" operator. For example, specifying F_NOINH | F_NOWRITE as the opening mode, the file opens as only reading and not heritable.

Attributes of the files

They are used in the functions of establishing and consulting the attributes of a file:

A_RDO
Read Only
A_HID
Hidden
A_SYS
System
A_VOL
Not a file but a volume label
A_DIR
Directory
A_ARC
Archive
A_DEV
Not a file but a device
A_NEW
Used in the function to create a file, if it is 1 and already exists a file with the same name, not be erased and an error is generated

You can combine two or more s with the "|" operator. For example, specifying A_HID | A_DIR as search attributes in FFIND, look for n hidden files and subdirectories in addition to normal files.


Methods of obtaining a character

They are used in the NGETC function to get a character from the keyboard.

NOWAIT
If not specified, wait until the user press a key; If you specify and the user is not pressing any key, the function to return 0 immediately.
NOTICE
If specified, the character corresponding to the key pressed does not appears on the screen.

They can be combined with the "|" operator.

Other constants defined in NDOS.H

Uchar equivalent to unsigned char
Uint equivalent to unsigned int
Ulong equivalent to unsigned long
Fhanle equivalent to int
ESC equivalent to 27 (escape code)

CR_LF: this is not a constant, but a char pointer pointing to a string "\n\r". CR_LF is used in NEWLINE and FNEWLINE macros instead of a string "\n\r", to prevent the compiler from defining that string each instead find a call to these macros.

FORMAT OF THE DESCRIPTION OF THE FUNTIONS

A detailed description of all NDOS. The descriptions have the following format: 


[(N)] NAME [*]

Exit name (entry, ..., entry)

Description of function.

DOS functions used [*]

-----
(...)
Sample program or subfunction (except for very simple functions)
or reference to the example of another function
(...)
-----


Some NDOS functions have the same name as other NDOS functions of C standard library (eg OPEN, GETC or PRINTF) but its use is slightly different. To avoid conflicts, these functions are defined with an "N" as the first caracter: NOPEN, NGETC, NPRINTF; in the description of this type of functions, the name is preceded by "(N)".

However, it is possible to force the compiler to recognize the names of function without the initial N as belonging to NDOS. This is achieved defining the NSTDIO shell, either with the directive "#define NSTDIO" (which must be located BEFORE "#include NDOS.H") or by including -DNSTDIO in the compiler command line. The effect is the definition of a macro for each function whose name begins with N, without the initial N (for example, does "#define open nopen").

Some functions have no associated object code, but are simply macros defined in NDOS.H which in turn call other functions. For example, the PUTC function, which prints a character on the screen, is actually a macro that calls FPUTC (writing a character in a file) specifying STDOUT as the file descriptor. In the description of these functions, name is followed by an asterisk.


Following the description of each function, the DOS calls are listed. A asterisk next to one of these calls indicates that it can be used safe from a disk error handling routine (defined with the ATERROR function of NDOS, 64h DOS call); So if all the calls used by a function have asterisks, the function itself can be used securely from a disk error handling routine.

The functions are ordered alphabetically, regardless of the N of the functions that have it. The following are all the functions as a quick reference, and the following section gives an overview of detailed description of each:

ABSEC
Read or write disk sectors
ASSIGN
Assigns logical drives to physical drives
(N) ATERROR
Defines a function to call in case of disk error
(N) ATEXIT
Defines a function to call when the program is finished
BEEP *
It sounds a "beep"
BS *
Deletes the character to the left of the cursor
BTOA *
Converts a number to a string on binary basis
BUFFERS
Sets or queries the number of system sector buffers
(N) CHDIR
Change the current directory
CHKCHAR
Helps manipulate strings containing graphic characters
(N) CLERR *
Overrides the error condition caused by a previous function
(N) CLOSE
Closes an open file
CLS *
Clears the screen
CREATE
Create a file
CURBLK *
Select the normal cursor
CURDOWN *
Moves the cursor one position down
CURLEFT *
Moves the cursor one position to the left
CUROFF *
Sets the cursor to "hidden"
CURON *
Sets the cursor to "visible"
CURRIGHT *
Moves the cursor one position to the right
CURUND *
Select the small cursor
CURUP *
Moves the cursor up one position
DELLINE *
Deletes the line in which the cursor is
DELTOENDL *
Delete from the cursor to the end of the line
DELTOENDS *
Delete from the cursor to the end of the screen
DOSVER
Returns the version of MSX-DOS
DTOI
Encode a structure of type "date" into an integer
DUPFH
Duplicate a file descriptor
EOF
Indicates whether the pointer of an open file is beyond the end
ENSUREFH
Moving Internal System Buffers to Disk Data
That have been written in a file
(N) EXIT
Program execution ends
EXPLAIN
Gets an error message for a given error code
FDELETE
Delete a file
FILEDT
Queries / sets date / time of an open / unopened file
FFIND
Search for files on disk
(N) FGETC
Reads a character from an open file
FILEATT
Gets or modifies the attributes of a file, open or not
FINDENV
Finds the name and value of an environment variable
FLUSH
Cleans unusable disk buffers
FNEWLINE *
Prints a line break in a file
FORK
Prepares the environment to execute a child process
FORWARD *
Places the pointer of a file at the end of the file
FPRINT
Prints a string in a file
(N) FPRINTF
Print formatted in a file
(N) FPUTC
Write a character in an open file
(N) FTELL *
Returns the current pointer position of an open file
GDATE
Gets System Date
GETARG
Gets a command line parameter
(N) GETC
Gets a keyboard character
(N) GETCWD
Returns the current directory
GETDPAR
Gets the parameters of a disk
GETDRV
Returns the default drive
GETDTA
Gets the real address of transfer. Disk for DOS functions 1
(N) GETENV
Gets the value of an environment variable
GETERR
Returns the code of the last generated DOS error
GETFATT *
Gets the attributes of an unopened file
GETFDATE *
Gets the date of an unopened file
GETFTIME *
Gets the time of an unopened file
GETHATT *
Gets the attributes of an open file
GETHDATE *
Gets the date of an open file
GETHTIME *
Gets the time of an open file
GETLOGV
Indicates the existing disk drives
GTIME
Gets the system time
HOME * Moves the cursor to the top of the screen
INPUT
Gets a string from the keyboard
INSLINE *
Inserts a new line above the cursor
IOCTRL
Performs control operations on a file descriptor
ITOA *
Converts a number to a string on a decimal basis
ITOD
Decodes an encoded date structure into an integer
ITOT
Decodes an encoded time structure into an integer
JOIN
Indicates that the parent process will resume control
LOCATE *
Position the cursor in the given coordinates
(N) MKDIR
Create a directory
MOVE
Moves a file
MPRINT
Prints multiple strings on the screen
MPUTC
Prints multiple on-screen characters
NEWLINE *
Prints a line break on the screen
NTOA
Converts a number to a string in any base
NUMARGS
Gets the number of parameters in the command line
(N) OPEN
Opens a file
PARSEF
Examines and returns information about a filename
PARSEP
Examines and returns information about a file path
PAUSEKEY *
Wait for the user to press a key (see also WAITKEY)
PRINT *
Prints an on-screen string
(N) PRINTF
Screen formatted printout
PRINTLN *
Print a finished line in screen line break
(N) PUTC *
Prints a character on the screen
RAMDISK
Create or destroy RAMdisk, or check its size
RDSEC *
Reads disk sectors
(N) READ
Reads data from a file
REDIR
Check or modify the status of the redirection
(N) RENAME
Rename a file
(N) REWIND *
Places the pointer of an open file at the beginning of the file
(N) RMDIR
Deletes a directory
SDATE
Sets the system date
SEEK
Modifies the pointer of an open file
SETDRV
Selects default drive
SETDTA
Sets the disk transfer area for DOS functions 1
(N) SETENV
Sets the value of an environment variable
SETFATT *
Sets the attributes of an unopened file
SETFDATE *
Sets the date of an unopened file
SETFTIME *
Sets the time of an unopened file
SETHATT *
Sets the attributes of an open file
SETHDATE *
Sets the date of an open file
SETHTIME *
Sets the time of an open file
(N) SPRINTF
Memory formatted printing
STIME
Sets the system time
SUPRLINE *
Deletes the line in which the cursor is
TESTFH
Checks whether a file descriptor corresponds to a given file
TTOI
Encodes a structure of type "time" into an integer
VERIFY
Enables, disables or verifies the automatic verification of the
Boot sector in file accesses
WAITKEY
Wait for the user to press a key (see also PAUSEKEY)
WPATH
Returns the full path of the last file found with FFIND
(N) WRITE
Write data to a file
WRSEC
Write Disk Sectors
XTOA *
Converts a number to a string in hexadecimal base

DESCRIPCION OF THE FUNCIONS

Now translationg[from WIKI editor]

AS USUAL

NDOS is freeware, so distribute it as you want, but please distribute only the complete package (listed in section 1) and if you do any modification please explain it in a separate package.

If you want to kick me or congratulate me or blah, blah... contact me at konamiman@konamiman.com, and visit my home page at http://www.konamiman.com

Y que Kyoko es la es la m s mejor.

Retrieved from "http://hi-tech.msx.click/en/index.php?title=LIBRARY_PUBLIC_DOCUMENT_NDOS&oldid=346"