A MCS directory item is defined by a directory-name and
an item-name.
Some MCS syscalls operate with the input
parameters unsigned char*dir and unsigned char*item, to
locate an item.
Some MCS syscalls operate on MCS-handles, instead.
The MCS-handles are global variables.
They must be set before using a MCS syscall, which operates on
MCS-handles.
The content of the MCS-handles cannot be relied on, after
process switch (MENU-key)!
unsigned char MCS_DirectoryHandle[8]; OS 1.02, 1.03: 0x88008BEC
unsigned char MCS_ItemHandle[8]; OS 1.02, 1.03: 0x88008BFC
char MCS_Term; OS 1.02, 1.03: 0x88008C04; seems to be the terminating zero of
MCS_ItemHandle, only.
int MCS_Result; OS 1.02, 1.03: 0x88008C0C
char MCS_Type; OS 1.02, 1.03: 0x88008C10
0x0804: int CLIP_Store(
unsigned char*buffer, in length );
Copies length bytes of buffer
to the clipboard.
The clipboard is stored in main memory's directory @REV2, items CLIP and
NAT_CLIP.
0x0829: unsigned char*MCS_CreateDirectory(
unsigned char*dir );
Creates a directory using
MCS syscall 0x0363.
The function returns the 2nd-level-errorcodes (see syscall 0x0866).
0x082A: int
MCS_PutInternalItem( char dirtype, unsigned char*item, int
data_len, void*buffer );
Creates item of length data_len
in the MCS internal directory according to dirtype (see 0x0863).
item's data-area is initialized with *buffer.
The function does not overwrite an existing item.
item's itemtype is set according to dirtype (see 0x0852).
If the function succeeds, MCS-handles are set. MCS_Type is
set to dirtype.
Returns 0, if no error occurs.
Returns error 0x10, if dirtype is zero.
Returns error 0x12, if item is zero.
Returns error 0x24, if item already exists.
Hint: data_len is increased automatically, if not 4-aligned.
Examples:
MCS_PutInternalItem( 2, "4", 7, "\x001\x008\x080\x003\x0826\0" ); // set
function 4, COS 6, selected, bold style
MCS_PutInternalItem( 2, "6", 9, "\x001\x008\x000\x002\x0831.8\0" ); // set
function 6, TAN 1.8, unselected, normal style
0x082B: int
MCSPutVar2( unsigned char*dir, unsigned char*item, int
data_len, void*buffer );
This is one of the
Bfile_Mainmemory-base-functions.
Creates an item dir.item of length
data_len in the MCS.
item is initialized with *buffer.
The function does not overwrite an existing dir.item.
dir.item-member flags[0] is set to 0xD4.
If the function succeeds, MCS-handles are set.
Returns 0, if no error occurs.
Returns 0x25, if dir.item already exists.
Returns error 0x40, if dir does not exist.
0x0830: int
MCSOvwDat2( unsigned char*dir, unsigned char*item, int
bytes_to_write, void*buffer, int write_offset );
This is one of the
Bfile_Mainmemory-base-functions.
Writes bytes_to_write bytes of buffer to dir.item.
write_offset defines where to start the write inside dir.item's
data area.
If the function succeeds, MCS-handles are set.
Returns 0, if no error occurred.
This is a 5-parameter syscall!
0x0832: int
MCS_OverwriteOpenItem( int bytes_to_write, void*buffer, int
write_offset );
Writes bytes_to_write bytes of
buffer to the currently open MCS-handle's item.
write_offset defines where to start the write inside MCS_ItemHandle's
data area.
Returns 0, if AlphaMem has been rewritten.
Returns 0, if main memory has been rewritten (item's data-length reduced).
Returns 1, if main memory has been rewritten (item's data-length unchanged).
Returns 2, if main memory has been rewritten (item's data-length enlarged).
Any other return-value denotes an error.
Example:
MCS_OpenInternalDirectoryItem( 2, "4", &data_len ); // first open function 4
MCS_OverwriteOpenItem( 9, "\x001\x008\x080\x003\x0813.2", 0 ); // rewrite
function 4 to SIN 3.2
MCS_OverwriteOpenItem( 5, "1.23", 4 ); // rewrite function 4 to 1.23
0x0833: int
MCS_ClearInternalDirectory( char dirtype );
Deletes all items in the internal directory according to dirtype (see
0x0863),
which have the required itemtype depending on dirtype (see 0x0853).
Error 0x10: invalid dirtype.
Error 0x23: no items
Returns 0, if successful.
If the function succeeds, it clears ("closes") the MCS-handles.
Example: MCS_ClearInternalDirectory( 5 ); would delete all Lists.
0x0834: int
MCS_ClearDirectory( unsigned char*dir );
The function deletes all items of directory
*dir.
The directory itself is not deleted.
If successful, the function clears ("closes") the MCS-handles.
The function returns the 2nd-level-errorcodes (see syscall 0x0866).
0x0835: int
MCS_DeleteInternalItem( char dirtype, unsigned char*item );
Deletes item in the intrinsic directory
according to dirtype (see 0x0863).
Checks the required itemtype depending on dirtype.
Error 0x10: invalid dirtype.
Error 0x40: no items or no matching item
Returns 0, if successful.
If the function succeeds, it sets MCS handles:
MCS directoryhandle is set to the directory defined by dirtype.
MCS itemhandle is set to the deleted item.
MCS type is set to dirtype.
MCS Result is set to the result of the MCS_SearchDirectory.
If no matching item is found, the function clears ("closes") the
MCS-handles.
Example: MCS_DeleteInternalItem( 1, "ABC" ); would delete the BASIC program
"ABC".
0x0836: int
MCSDelVar2( unsigned char*dir, unsigned char*item );
This is one of the
Bfile_Mainmemory-base-functions.
Deletes dir.item.
Returns 0x40, if dir or dir.item does not exist.
Returns 0, if no error occurred.
If successful, the function clears ("closes") the MCS-handles.
0x083A: int
MCS_GotoInternalItem( char dirtype, unsigned char*item, int
direction );
Step 1:
map a directory name to dirtype using syscall 0x0863.
Step 2: the function searches the directory by the name found in step 1.
If item==0, the function positions to the top (direction>0)
or the bottom (direction<=0) of the underlying item-array.
If item!=0, the function tries to go exactly to the item with the
name *item.
Only those items are accounted for, which own the right item-type.
syscall 0x0853 maps an item-type to a directory-type. If you read it reverse:
dirtype==1 : item-type = 0xC7 (BASIC program)
dirtype==0xA : item-type = 0xCD (CAPTURE file)
dirtype==-1: item-type = 0xD3
else : item-type = see 0x0853.
If the function succeeds, it sets MCS-handles:
MCS directoryhandle to the directory selected in step 1.
MCS itemhandle to the item found.
MCS type to dirtype.
MCS Term to zero.
MCS Result is set with the result of the DirectorySearch, done in step 2.
Returns 0, if the function succeeded.
Returns 0x10, if dirtype==0.
If the directory search (step 2) fails, the function returns the
syscall-0x375-result, translated by syscall 0x0866 (MCS_MapError).
Returns 0x40, if item does not exist in the directory.
Returns 0x41, if no items are available in the directory.
F. i., the function is used, when "PRGM" is invoked and the list of BASIC
programs is gathered.
0x083B: int
MCS_OpenMainMemoryItem( unsigned char*dir, unsigned char*item,
char direction );
Searches dir.item.
direction = -1: searches from the last to the first item.
direction = 1: searches from the first to the last item.
Returns 0, if no error occurs.
If successful, the function sets some MCS-handles:
strncpy( MCS_DirectoryHandle, dir, 8 );
strncpy( MCS_ItemHandle, item, 8 );
MCS_Result = 0 on success;
MCS_Type = -2;
MCS_Term = 0.
0x083C: int
MCS_GotoHandleNeighbour( char direction );
Searches the current MCS-handle's neighbour.
direction==1 : try next
direction==-1 : try prev
Returns 0x57, if MCS_Type is zero.
Returns 0x40, if item not found.
Returns 0, if successful.
If successful, the function sets MCS_ItemHandle to the neighbour found.
Example:
MCS_GotoInternalItem( 1, "B", 1 ); set BASIC program "B" as current item
MCS_GotoHandleNeighbour( -1 ); try to go to the BASIC program, which precedes
"B"
0x083D: int
MCS_CheckOpenedItem( char*dirtype, int*data_len );
Checks the currently opened MCS-handles.
*dirtype is set according to syscall 0x0853.
*data_len is set to the length of the corresponding data-block.
Returns 0, if no error occurs.
0x083E: int MCS_GetOpenItem(
unsigned char*item );
Copies the itemname of the current
MCS-handles into *item.
Returns 0, if the function succeeded.
0x083F: int
MCS_OpenInternalDirectoryItem( char dirtype, unsigned char*item,
int*data_len );
Tries to open the MCS-handles
for item in the internal directory according to dirtype (see
0x0863).
The length of the underlying data is returned in *data_len.
Returns the result of MCS_SearchDirectoryItem(0x376), mapped by
MCS_MapError(0x866).
0x0840: int
MCSGetDlen2( unsigned char*dir, unsigned char*item, int*data_len
);
This is one of the
Bfile_Mainmemory-base-functions.
dir directory name (f. i. "system"
in case of BASIC programs)
item item name (f. i. the name of a BASIC program)
*data_len length of item-data
If successful, the function sets the MCS-handles to dir
and item.
Returns 0, if no error occurs.
Returns 0x40, if item does not exist.
0x0841: int
MCSGetData1( int offset, int len_to_copy, void*buffer
);
This is one of the
Bfile_Mainmemory-base-functions.
Operates on MCS-handles (f. i. opened with
0x083B or 0x084D; implicitly by 0x840). Never use this call after a
MENU-key-aware inout-function like GetKey.
MCS_Type 0: AlphaMem data are retrieved
from MCS_ItemHandle.
MCS_Type not 0: main memory data are retrieved from
MCS_DirectoryHandle.MCS_ItemHandle.
if offset is zero, the complete available data-block is copied to *buffer
(len_to_copy is ignored!).
Otherwise the len_to_copy bytes of data beginning at offset
are copied to *buffer.
Returns 0, if no error occurred.
0x0843: int
MCS_MapMCS_Result( void );
Returns MCS_Result, mapped by
MCS_MapError(0x866).
0x084D: int
MCS_OpenAlphaMemItem( char variablename, int*data_len, void*data_ptr
);
Returns the pointer to the data in data_ptr.
Returns the length of the data in *data_len (normally 24 for
AlphaVars).
Returns 0, if no error occurred.
If successful, the function sets some MCS-handles:
It sets MCS_DirectoryHandle to "main" (but "main" is not the directory, where
AlphaVars are stored! See
MCS structure.).
It sets MCS_ItemHandle to variablename.
It sets MCS_Type to zero.
0x0852: int
MCS_DirtypeToItemtype( char dirtype );
0->0x82;1->0xC7;2->0xC8;3->0xD5;4->0x85;5->0x8A;
6->0x8C;7->0xCE;0xA->0xCD;-1->0xD3;-2->0xD4
else 0;
This function is included as reference.
0x0853: int
MCS_ItemtypeToDirtype( char itemtype );
The function maps an item-type to a
directory-type.
0x82->0;0xC7->1(BASIC program);0xC8->2(Functions);0xD5->3;0x85->4;
0x8A->5(Lists);0x8C->6;0xCE->7(PICTURE file);0xCD->0x0A(CAPTURE file,
CLIPBOARD);
0xD3->-1;0xD4->-2(f. i. @RUNMAT.REPLAY, SSHEET)
else -> 0x80;
This function is included as reference.
0x0863:
unsigned char*MCS_DirtypeToName( char dirtype );
returns the pointer to a directoryname according
to dirtype.
dirtype==1 -> "system"
dirtype==0xA -> "@REV2"
dirtype==-1 -> "@APLWORK"
else -> "main".
Covers only some internal directories.
"system" holds the BASIC-programs.
"@REV2" holds the CAPTURE-files, the CLIPBOARD (CLIP and NAT_CLIP).
"main" is used for several itemtypes. F. i. Functions (0xC8) and Lists(0x8A).
0x0866: int MCS_MapError(
int error_in );
Maps the errorcode of the 1st-level MCS
functions
to the errorcode of the 2nd-level MCS-functions.
0->0; 0x10->0x13;0x11->0x51;0x12->0x17;0x13->0x15;
0x14->0x33;0x15->0x18;0x16->0x16;0x18->0x19;0x41->0x12;
0x50->0x30;0x51->0x32;0x52->0x52;0xFF->0xFF;
else -> 0x40
The meaning of the errorcodes will be analyzed later.
0x086F: int
MCS_DeleteDirectoryItems( unsigned char*dir );
Deletes all items of the MCS directory dir.
Returns 0, if no error occurs.
(03.06.2011 10:16:45)