Beware of MCS inconsistencies:
When inserting or deleting MCS-objects or increasing the size of an existing
MCS-item, it is important to use
handle-based MCS-syscalls. Otherwise process-switching (MENU-key) could
lead to an inconsistent main memory. F. i. e-ACT can get
confused, if it cannot detect changes applied to the main memory by another
process.
A safe way seems to be the use of syscalls, the
BfileMainMemory-functions rely on.
MCS syscalls
To understand MCS syscalls, it could be useful to know
the main memory's structure.
Some MCS syscalls operate on MCS-handles.
0x0363: int
MCS_CreateDirectory( unsigned char*dir, char*dirno );
Creates an entry dir in the MCS
directory.
Returns the number of the created directory in *dirno.
Returns 0, if no error occurs.
Returns 0xF0, if dir==0 or the length of *dir==0.
Returns 0x42, if the directory already exists.
Returns 0x43, if the directory space is exhausted.
0x0364: int MCS_WriteItem(
unsigned char*dir, unsigned char*item, short itemtype,
int data_length, int buffer );
Creates or overwrites item dir.item
of length data_len into the MCS.
item data are initialized with buffer.
itemtype is used to set dir.item-member flags[0].
Returns error 0x40, if dir does not exist.
Returns error 0x35, if dir.item exists and if bit 6 of
dir.item-member flags[0] is set (readonly-flag; before changed
by the actual function call!).
Returns error 0x32, if dir.item-member's flags[1] bit 0 is
1.
Returns error 0x34, if dir.item-member's flags[1] bit 1 or 2
is 1.
Returns error 0x10, if data_length is not 4-aligned.
Returns error 0x11, if MCS-capacity is exhausted.
Returns 0, if no error occurs.
This is a 5-parameter syscall!
0x0366: int
MCS_DeleteDirectory( unsigned char*dir );
Deletes the MCS directory dir.
returns 0, if no error occurs.
Returns 0xF0, if dir==0 or the length of *dir==0.
Returns 0x40, if dir not found.
Returns 0x45, if item-count is not zero. If items are present, use 0x086F
beforehand.
Returns 0x46, if *dir=="@APLWORK" or "main".
Returns 0x46, if dirno > 0x66.
Returns 0x47, if dir's flags[1] bit 0 is 1.
0x0367: int MCS_DeleteItem(
unsigned char*dir, unsigned char*item );
Deletes dir.item.
Returns 0, if successful.
Returns 0xF0, if either dir or item==0 or the length of *dir
or *item ==0.
Returns 0x40, if dir not found.
Returns 0x30, if item not found.
Returns 0x32, if item's flags[1] bit 0 is 1.
Returns 0x34, if item's flags[1] bit 1 or 2 is 1.
0x0368: int MCS_GetState(
int*maxspace, int*currentload, int*remainingspace
);
Returns max. available main memory in *maxspace.
Returns current main memory load in *currentload.
Returns currently availabe main memory in *remainingspace.
Returns 0.
0x0369: int
MCS_GetSystemDirectoryInfo( unsigned char*dir, unsigned int*pdir,
char*dirno );
Returns some information concerning the
main-directory.
name: usually "main".
pdir: usually 0x88030A10
dirno:usually 2.
0x0370: int MCS_RenameItem(
unsigned char*srcdir, unsigned char*srcitem, unsigned char*tgtdir,
int tgtitem );
Renames (moves) srcdir.srcitem
to tgtdir.tgtitem.
This function first copies srcitem to tgtitem and than
deletes srcitem. Hence, it needs temporary MCS-space of the size of
the object to be renamed. Else it returns memory full error 0x5F. That is a
considerable disadvantage.
Returns 0x40, if srcdir or tgtdir does not exist.
Returns 0x32, if srcitem's flags[1] bit 0 is 1.
Returns 0x34, if srcitem's flags[1] bit 1 or 2 is 1.
Returns 0x5F, memory full.
0x0371: int
MCS_OverwriteData( unsigned char*dir, unsigned char*item,
int write_offset, int bytes_to_write, void*buffer
);
Writes bytes_to_write bytes of
buffer to dir.item.
write_offset defines where to start the write inside dir.item's
data area.
returns 0x13, when the number of bytes to write exceeds the item's actual data
length.
returns 0x14, when the bytes_to_write plus write_offset
exceeds the item's actual data block end.
returns 0, if no error occurred.
This is a 5-parameter syscall!
0x0372: int MCS_GetItemData(
unsigned char*dir, unsigned char*item, int offset,
int bytes_to_read, void*buffer );
Reads bytes_to_read bytes from dir.item
to *buffer.
offset defines where to start the read inside dir.item's
data area.
Returns 0, if no error occurred.
This is a 5-parameter syscall!
0x0373: int
MCS_RenameDirectory( unsigned char*oldname, unsigned char*newname
);
Renames MCS directory entry oldname to
newname.
Returns 0, if no error occurs.
0x0375: int
MCS_SearchDirectory( unsigned char*dir,
TMainMemoryDirectoryEntry*pdir,
char*dirno );
Searches dir in the MCS directory.
Returns the pointer to the directory entry in *pdir.
Returns the number of the directory entry in *dirno.
Returns 0, if no error occurs.
Returns 0xF0, if dir==0 or the length of *dir==0.
Returns 0x40, if dir not found.
0x0376: int
MCS_SearchDirectoryItem( unsigned char*dir, unsigned char*item,
char*flags_0, TDirectoryItem*item_ptr,
int*data_ptr, int*data_length );
Tries to locate item in the MCS
directory dir and if successful, retrieves some information of
item.
Returns dir.item-member flags[0] in *flags_0, the
meaning of which is unknown yet (except bit 6, see 0x364).
Returns the pointer to the item in *item_ptr.
Returns the pointer to the data in *data_ptr.
Returns the length of the data in *data_length.
Returns 0, if no error occurs.
Returns 0x30, if item not found.
This is a 6-parameter syscall!
Example: sys0376( "system", "ABC", ... ) investigates the properties of the
BASIC-program "ABC".
0x037C: int
MCS_GetFirstDataPointerByDirno( char*dirno, void*pdata );
Retrieves the first(!) data pointer of MCS
directory (by dirno) in *pdata.
Returns the same value.
It does not check the allowed range of dirno! It steps in an
exception-trap if dirno is outside of 1..0x93.
This function may be useful for directories with one data-item (f. i. "@RUNMAT"/"RECALL",
the RUN.MAT history).
0x037D: int
MCS_GetDirectoryEntryByNumber( char dirno,
TMainMemoryDirectoryEntry*pdir
);
Retrieves the MCS directory entry address in *pdir
by dirno.
Returns 0, if no error occurs.
Returns 0x44, if dirno is outside of the allowed range 1..0x93.
The function allows to build a MCS-findfirst/findnext functionality.
0x037E: int MCS_SearchItem(
unsigned char*item,
TMainMemoryDirectoryEntry*pdir, unsigned short*itemno );
Searches item in the MCS directory
pointed at by pdir.
item has to be zero padded to 8 chars!
Returns the number of the directory item in *itemno.
The *itemno range starts at zero.
returns 0, if no error occurs.
0x037F: int MCS_str8cpy(
unsigned char*source, unsigned char*target, int mode
);
Copies max. 8 chars of source to
target (t. i. strncpy( target, source, 8 ) )
With mode = 0, target is converted to upper case.
With mode = 1, target is converted to lower case.
With mode = 2, target is not converted.
Returns 0, if no error occurs.
Returns 0xF0, if the source length is zero.
Is often used in connection with MCS-functions.
0x0380: void
MCS_GetDirectoryEntryAddress( void*directory_entry_address );
directory_entry_address receives the
start of MCS RAM directory.
0x0381: void
MCS_GetCurrentBottomAddress( void*current_bottom_address );
current_bottom_address receives the MCS
RAM bottom (0x88030000..0x8803FFFF).
0x0383: int MCS_GetCapa(
int*current_bottom );
current_bottom receives the current MCS
RAM bottom.
returns Main Memory capacity
0x0392: int
MCS_GetMainMemoryStart( void );
returns the MainMemoryStart-address.
A second set of syscalls is documented in
MCS-handles.
(18.03.2011 16:14:42)