-
-
Notifications
You must be signed in to change notification settings - Fork 35
/
DOS2-PIS.TXT
2063 lines (1246 loc) · 76.6 KB
/
DOS2-PIS.TXT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
MSX-DOS 2 PROGRAM INTERFACE SPECIFICATION
By ASCII corporation Japan
Supplied with COMPASS v1.0 by COMPJOETANIA
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
This document describes the interface to transient programs provided by
MSX-DOS version 2.xx.
CONTENTS
1. Introduction
2. Transient Program Environment
2.1 Entry from MSX-DOS
2.2 Return to MSX-DOS
2.3 Page Zero Usage
2.4 BIOS Jump Table
2.5 RAM Paging
3. MSX-DOS calls
3.1 Calling Conventions
3.2 Devices and Character I/O
3.3 File Handles
3.4 File Info Blocks
3.5 Environment Strings
3.6 File Control Blocks
4. Screen Control Codes
5. Mapper Support Routines
5.1 Mapper Initialization
5.2 Mapper Variables and Routines
5.3 Using Mapper Routines
5.4 Allocating and Freeing Segments
5.5 Inter-Segment Read and Write
5.6 Inter-Segment Calls
5.7 Direct paging routines
6. Errors
6.1 Disk Errors
6.2 MSX-DOS Function Errors
6.3 Program Termination Errors
6.4 Command Errors
1. INTRODUCTION
=================
This manual describes the environment which MSX-DOS 2 provides for trans-
ient programs on MSX 2 computers. It is intended as a guide for writing new
programs to run under MSX-DOS 2 and also to assist in converting existing
CP/M and MSX-DOS 1 programs to take advantage of the advanced features.
MSX-DOS 2 provides many enhancements to the standard CP/M and MSX-DOS 1
environment, but is largely compatible with existing programs. The main fea-
tures include:
MS-DOS style tree structured directories
File handles
Environment Strings
Proper error handling
Many extra DOS calls are implemented, and these are accessed via the DOS
entry jump at address 5 (the 'BDOS' jump in CP/M). The descriptions of the
individual functions can be found in the MSX-DOS 2 Function Specification.
Throughout this manual, the term MSX-DOS is used generally to refer to
MSX-DOS 2 unless otherwise stated.
2. TRANSIENT PROGRAM ENVIRONMENT
==================================
This chapter describes the environment in which transient programs are
executed under MSX-DOS, including entry and exit to the program and memory
usage.
2.1 ENTRY FROM MSX-DOS
A transient program will be loaded at address 0100h, the start of the TPA
(Transient Program Area), and is CALLed by MSX-DOS with the stack pointer set
to the end of the TPA. If the stack pointer points to that location, as much
RAM as possible can be used as the stack. If it is undesirable, then the
transient program must set up its own stack in the TPA.
The contents of the Z-80 registers when a transient program is entered are
undefined. The first 256 bytes of RAM starting at the address 0 will have
been set up with various parameters and code as described in section 2.3.
Interrupts are enabled when a transient program is entered and should
generally be left enabled. MSX-DOS function calls will generally reenable
interrupts if the transient program has disabled them.
2.2 RETURN TO MSX-DOS
A transient program can terminate itself in any of the following four ways:
1. Returning, with the original stack pointer.
2. Jump to location 0000h.
3. MSX-DOS "Program Terminate" function call.
4. MSX-DOS "Terminate with Error Code" function call.
The first two of these methods are identical as far as MSX-DOS is concer-
ned, and are compatible with CP/M and MSX-DOS 1. The third method is also
compatible with CP/M and MSX-DOS 1 and is equivalent to doing a "Terminate
with Error Code" function call with an error code of zero.
The new "Terminate with Error Code" function allows the program to return
an error code to MSX-DOS, the first three terminating methods always retur-
ning an error code of zero (no error). All specially written programs and
converted CP/M programs should use this new function, even for returning an
error code of zero.
Various other events outside the control of a program can cause it to
terminate. For example, typing "Ctrl-C" or "CTRL-STOP" at the keyboard, by
the user selecting "Abort" as the response to an "Abort/Retry/Ignore" disk
error message or by an error on the standard I/O channels. In these cases an
appropriate error code will be returned to MSX-DOS.
A transient program can define an "abort routine". This will be called to
treat the abnormal termination of the program appropriately when the program
terminates by a "Program Terminate" or "Terminate with error code" function,
or after an abort error (see above). How to define this routine and for what
may be used is described in the MSX-DOS Function Specification.
2.3 PAGE ZERO USAGE
On entry, various parameter areas are set up for the transient program in
the first 256 bytes of RAM. The layout of this area is as below and is compa-
tible with MSX-DOS 1 and with CP/M apart from the area used for MSX slot
switching calls.
+-------+-----+------+------+------+------+------+------+
0000h | Reboot entry | Reserved | MSX-DOS entry |
+------+------+------+------+------+------+------+------+
0008h | RST 08h not used | RDSLT routine entry point |
+------+------+------+------+------+------+------+------+
0010h | RST 10h not used | WRSLT routine entry point |
+------+------+------+------+------+------+------+------+
0018h | RST 18h not used | CALSLT routine entry point |
+------+------+------+------+------+------+------+------+
0020h | RST 20h not use | ENASLT routine entry point |
+------+------+------+------+------+------+------+------+
0028h | RST 28h not used | not used |
+------+------+------+------+------+------+------+------+
0030h | CALLF routine entry point | not used |
+------+------+------+------+------+------+------+------+
0038h | Interrupt vector | |
+------+------+------+ +
0040h | |
+ +
0048h | Used by secondary slot switching code |
+ +
0050h | |
+ +------+------+------+------+
0058h | | |
+------+------+------+------+ +
0060h | Unopened CP/M FCB for first parameter |
+ +------+------+------+------+
0068h | | |
+------+------+------+------+ +
0070h | Unopened CP/M FCB for second parameter |
+ +------+------+------+------+
0078h | | Space for end of FCB |
+------+------+------+------+------+------+------+------+
0080h | |
. . .
. . Default Disk transfer address. Initialized to .
. . original command line parameters. .
. . .
00F8h | |
+------+------+------+------+------+------+------+------+
At address 0000h is a jump instruction which can be used for terminating
the transient program. The destination of this jump can also be used to
locate the BIOS jump vector (see section 2.4). The low byte of this jump
address will always be 03h for CP/M compatibility.
The two reserved bytes at addresses 0003h and 0004h are the IOBYTE and
current drive/user in CP/M. Although MSX-DOS keeps the current drive byte up
to date for CP/M compatibility, new programs are not recommended to use this
but instead to use the "Get current drive" MSX-DOS function call. The user
number and IOBYTE are not supported since I/O redirection is not done in the
same way as CP/M and there is no concept of user numbers. At address 0005h is
a jump instruction to the start of the resident part of MSX-DOS which is used
for making MSX-DOS calls. In addition the address of this jump defines the
top of the TPA which the program may use. The size of the TPA depends on what
cartridges are used on the MSX machine and the number of them, but is typi-
cally 53K. The low byte of the destination of this jump will always be 06h
for CP/M compatibility, and the six bytes immediately preceding it will con-
tain the CP/M version number and a serial number.
Four bytes are reserved for the user at each Z80 restart location
(0008h-0028h), which is sufficient for a jump. The bytes between the restart
locations however are used for the entry points to various MSX slot switching
routines.
The whole area from 0038h to 005Bh is used for MSX interrupt and secondary
slot switching code, and must not be modified. Note that most CP/M debuggers
(such as ZSID and DDT) use address 38h as a breakpoint entry, and these pro-
grams will have to be modified to use a different restart. RST 28h is
recommended.
The two FCBs set up at addresses 005Ch and 006Ch are valid unopened FCBs
containing the first two command line parameters interpreted as filenames. If
both filenames are to be used then the second one must be copied to a sepa-
rate FCB elsewhere in memory because it will be overwritten when the first
one is opened. See section 3.6 for the format of FCBs.
The whole of the command line, with the initial command removed, is stored
in the default disk transfer area at address 0080h, with a length byte first
and a terminating null (neither the null nor the length byte are included in
the length). This string will have been upper-cased (when the environment
string UPPER is ON) and will include any leading spaces typed to ensure CP/M
compatibility.
New programs for MSX-DOS should not use the CP/M FCBs, since other MSX-DOS
calls are available which are generally easier to use and which allow pro-
grams to access directories and handle path names (see section 3 for details
of these facilities).
Improved methods are also available for accessing the command line. An
environment string called "PARAMETERS" is set up which contains the command
line not upper-cased. Another environment string called "PROGRAM" allows
programs to find out the drive, directory and filename from which they were
loaded. See section 3.5 for details of these environment strings and of envi-
ronment strings in general.
2.4 BIOS JUMP TABLE
The jump at address 0000h will always jump to an address whose low byte is
03h. At this address will be another jump instruction which is the second
entry in a seventeen entry jump table. This corresponds exactly to the BIOS
jump table in CP/M 2.2.
The first eight entries in the table are for rebooting and for character
I/O. These routines are implemented with the same specification as CP/M. The
remaining jumps are low level disk related functions in CP/M and have no
equivalent in MSX-DOS since its filing system is totally different. These
routines simply return without doing anything apart from corrupting the main
registers and returning an error where possible.
MSX-DOS switches to an internal stack while executing a BIOS call and so
only a small amount of space (8 bytes) is required on the user's stack.
Note that although the jump table is always on a 256 byte page boundary,
it is not the "correct" distance above the top of the TPA (as defined by the
contents of address 0006h) to correspond with CP/M 2.2. This should not mat-
ter to well behaved CP/M programs but it is rumoured that some programs rely
on the size of the BDOS in CP/M 2.2. These programs will need modification.
The entries in the BIOS jump vector are as below:
xx00h - JMP WBOOT ;Warm boot
xx03h - JMP WBOOT ;Warm boot
xx06h - JMP CONST ;Console status
xx09h - JMP CONIN ;Console input
xx0Ch - JMP CONOUT ;Console output
xx0Fh - JMP LIST ;List output
xx12h - JMP PUNCH ;Punch (auxiliary) output
xx15h - JMP READER ;Reader (auxiliary) input
xx18h - JMP RETURN ;Home in CP/M
xx1Bh - JMP RETURN ;Select disk in CP/M
xx1Eh - JMP RETURN ;Set track in CP/M
xx21h - JMP RETURN ;Set sector in CP/M
xx24h - JMP RETURN ;Set DMA address in CP/M
xx27h - JMP RETURN ;Read sector in CP/M
xx2Ah - JMP RETURN ;Write sector in CP/M
xx2Dh - JMP LSTST ;List status
xx30h - JMP RETURN ;Sector translate in CP/M
2.5 RAM PAGING
When a transient program is loaded, the mapper RAM slot will be enabled in
all four pages and the four RAM segments which make up the basic 64k will be
paged in. There will be MSX BIOS ROM compatible slot handling entry points
available in page-0 and various mapper support routines available in page-3
(see section 5 for specifications of these).
A program may do any slot switching and paging which it likes while it is
running and need not restore either the slot selections or the RAM paging
before it exits, since COMMAND2.COM will handle this. A program must of
course take the usual precautions with the interrupt and the slot entry
points if it alters page-0, and must never alter page-3 (nothing is allowed
to do that!).
Pages 0, 1 and 2 can contain any slot when doing a function call and will
be preserved. Any parameters can be passed from the slot being selected,
except that environment strings and disk transfer areas must be in the mapper
RAM slot.
Any RAM segments can be selected in pages 0, 1 and 2 when an MSX-DOS func-
tion call or an MSX-DOS BIOS function call is made, and also the stack can be
in any page. The current paging state will be preserved by all function calls
even in error conditions. Any disk transfers will be done to the RAM segments
which are paged in when the function call is made, even if they are not the
original TPA segments.
If a transient program wants to use more RAM than the TPA then it can use
the mapper support routines (described in section 5) to obtain more RAM.
Before using any RAM other than the four TPA segments, the program must ask
the mapper routines to allocate a new segment. This ensures that there is no
contention with the program trying to use a segment which is already in use
(by the RAM disk for example). The segments should normally be allocated as
"user segments" since these will automatically be freed when the program
terminates. "system segments" should only be allocated if it is necessary for
them to remain in use after the transient program has terminated.
Having allocated additional segments, the program may page them in and use
any of the mapper support routines to accessthem. It will normally be neces-
sary for a transient program to remember the segment numbers of the TPA seg-
ments in order to page them back in when they are required. The segment num-
bers will normally be 0, 1, 2 and 3 but this must NOT be assumed by transient
programs, they must use the "GET_Pn" mapper routines to find out the segment
numbers before paging anything else in.
3. MSX-DOS FUNCTION CALLS
===========================
3.1 CALLING CONVENTIONS
MSX-DOS function calls are made by putting the function code in register C
with any other parameters required in the other main registers and then exe-
cuting a "CALL 5" instruction. The operation will be performed and the
results will be returned in various registers depending on the function.
Generally all the main registers (AF, BC, DE and HL) will be corrupted by
MSX-DOS calls or will return results. The alternate register set (AF', BC',
DE' and HL') are always preserved, whilst the index registers (IX and IY) are
preserved except in the one or two cases where they return results.
Only a small amount of space (8 bytes) is needed on the transient pro-
gram's stack because MSX-DOS switches to an internal stack when it is called.
For compatibility all functions which have a CP/M counterpart return with
A=L and B=H. Frequently A returns an error flag, with zero indicating success
and 01h or FFh indicating failure.
All of the new MSX-DOS functions (function code above 40h) return with an
error code in A and any other results in the other main registers. An error
code of 0 means no error, whilst any non-zero code means an error occurred,
the exact nature of which can be found by looking at the value. A list of
error codes and messages is given in section 6. An "explain" function is
provided which will give an ASCII explanation string for an error code (see
Function Specification for details).
The actual functions available are documented in the MSX-DOS Function
Specification.
3.2 DEVICES AND CHARACTER I/O
Wherever a filename is given to an MSX-DOS function, a device name may
also be given. These devices are used for character based I/O and allow a
program to access a disk file or a character device in exactly the same way
without having to know which it is using.
The syntax of device names is identical to that of filenames so programs
do not need any special handling to use device names. This applies both to
the new MSX-DOS 2 functions and the CP/M compatible FCB functions. The reser-
ved filenames used for devices are:
CON - screen output, keyboard input
PRN - printer output
LST - printer output
AUX - auxiliary output/input
NUL - null device
When any of these appear as the main part of a filename, it actually re-
fers to the device; the extension is ignored. Most function calls that use
files can also use devices. For example, a filename of CON can be success-
fully given to the "rename file" function or to the "delete file" function.
No error will be returned but the device will be unaffected.
The AUX device mentioned above does not do anything by default, but a
routine may be hooked into it so that it refers for example to a serial dri-
ver. The NUL device does not actually do anything; output characters are
ignored and an end-of-file is always input. The LST and PRN devices are
identical.
The CON device is used to read from the keyboard or write to the screen.
When reading from the CON device, the system will read a line at a time allo-
wing the user to use line editing facilities. Only when the user types a CR
(carriage return) will the line be entered. End of input is signified by a
Ctrl-Z character at the start of a line.
The system automatically opens several file handles to these standard
devices (see section 3.3 for details). These file handles may be used by
programs for accessing the standard devices. Alternatively a program can do
character I/O by using the traditional CP/M character functions (functions
01h...0Bh). These two methods are both acceptable but they should not norma-
lly be mixed since they use separate buffering schemes and so characters can
get lost in these buffers.
The redirection is specified at the command line, both of these methods
(standard file handles and character functions) will be redirected. However
it is preferable to use the standard file handles and to read and write in
large blocks because when accessing disk files these will be very much faster
than using the character functions.
Even if the redirection was specified at the command line, programs may
sometimes need to do screen output and keyboard input which will bypass any
redirection. For example disk error handling routines may need to do this. To
facilitate this, there is a function provided which allows redirection of the
character functions to be temporarily cancelled. This is described in the
"Function Specification" document (function number 70h).
3.3 FILE HANDLES
File handles are the method by which files are read from and written to
using the new MSX-DOS functions. File handles may also be used to manipulate
files in other ways (e.g. the manipulation of the file attributes).
A file handle is an 8 bit number which refers to a particular open file or
device. A new file handle is allocated when the "open file handle" (function
43H) or "create file handle" (function 44H) function is used. The file handle
can be used to read and write data to the file and remains in existence until
the "close file handle" (function 45H) or "delete file handle" (function 52H)
function is called. Other operations can be done on files using file handles,
such as changing the attributes or renaming the files to which they refer.
Whenever MSX-DOS allocates a new file handle, it will use the lowest num-
ber available. The maximum file handle number in the current version is 63.
In future versions this may be increased but will never be greater than 127,
so file handles can never be negative.
Space for the internal data structures used for file handles is allocated
dynamically within a 16K RAM segment (the "data segment") so there is no
fixed limit to the number of file handles which can be open at one time. This
segment is kept outside the TPA, so anything stored there does not reduce TPA
size. As well as keeping internal file handle information, the system also
keeps disk buffers and environment strings in the data segment.
Various file handles are pre-defined and are already open when a transient
program is executed. These file handles refer to the standard input and out-
put devices (see section 3.2). The "traditional" CP/M style MSX-DOS character
I/O functions actually refer to these file handles.
A transient program actually gets a copy of the standard input and output
file handles which the command interpreter was using, rather than the origi-
nals. This means that the program can freely close these file handles and
re-open them to different destinations and need not reset them before
terminating.
The default file handles and their destinations are:
0 - Standard input (CON)
1 - Standard output (CON)
2 - Standard error input/output (CON)
3 - Standard auxiliary input/output (AUX)
4 - Standard printer output (PRN)
When the command interpreter is about to execute a command (for example a
transient program), it executes a "fork" function call (function 60H). This
informs the system that a new program is being executed as a "subroutine" and
amongst other things, all of the currently open file handles are duplicated,
so that the new program will be using copies of the original handles, rather
than the command interpreter's.
If the transient program changes any of the file handles, by closing any
existing ones or opening new ones, it will be the program's own set of file
handles which are modified, the original set will remain unaltered. After the
program has terminated, the command interpreter executes a "join" function
call (function 61H), passing to it a process id which was returned from the
original "fork". This tells the system that the new program has terminated
and so all its file handles can be thrown away.
Reference counts are kept of how many copies of each handle there are
which enables the system to tidy up any file handles which are no longer
needed when a program terminates. This ensures that the system will not run
out of file handles because of badly behaved programs not closing them.
These "fork" and "join" functions are available for user programs if they
find them useful. In addition to tidying up file handles, "join" will also
free up any user allocated RAM segments which the program has not freed.
3.4 FILE INFO BLOCKS
All new MSX-DOS functions that act on files on disk can be passed a simple
pointer to a null-terminated string (called an ASCIIZ string), which can
contain a drive, path and unambiguous filename. These are typically the ope-
rations which a transient program will perform, often through a high level
language interface. The Command Specification gives details of these.
To any of these ASCIIZ functions, a File Info Block (FIB) may passed ins-
tead. FIBs are used for more complex operations such as the searching of
directories for unknown files or sub-directories.
A FIB is a 64 byte area of the user's memory which contains information
about the directory entry on disk for a particular file or sub-directory. The
information in a FIB is filled in by the new MSX-DOS "find" functions ("find
first entry" (function 40H), "find new entry" (function 42H) and "find next
entry" (function 41H)). The format of a File Info
Block is as follows:
0 - Always 0FFh
1..13 - Filename as an ASCIIZ string
14 - File attributes byte
15..16 - Time of last modification
17..18 - Date of last modification
19..20 - Start cluster
21..24 - File size
25 - Logical drive
26..63 - Internal information, must not be modified
The 0FFh at the start of the fileinfo block must be there to distinguish
it from a pathname string, since some functions can take either type of
parameter.
The filename is stored in a suitable format for directly printing, and is
in the form of an ASCIIZ string. Any spaces will have been removed, the file-
name extension (if present) will be preceded by a dot and the name will have
been uppercased. If the entry is a volume label then the name will be stored
without the "." separator, with spaces left in and not uppercased.
The file attributes byte is a byte of flags concerning the file. The for-
mat of this byte is:
* Bit 0 - READ ONLY. If set then the file cannot be written to or deleted,
but can be read, renamed or moved.
* Bit 1 - HIDDEN FILE. If set then the file will only be found by the "Find
First" function if the "hidden file" bit is set in the search attributes
byte. All the commands implemented by the command interpreter that access
files and directories on disk can take a "/H" option which allows the command
to find hidden files.
* Bit 2 - SYSTEM FILE. As far as MSX-DOS functions are concerned, this bit
has exactly the same effect as the "HIDDEN FILE" bit except that the "Find
New" and "Create" function calls will not automatically delete a system file.
None of the commands implemented by the command interpreter allow system
files to be accessed.
* Bit 3 - VOLUME NAME. If set then this entry defines the name of the volume.
Can only occur in the root directory, and only once. All other bits are
ignored.
* Bit 4 - DIRECTORY. If set then the entry is a sub-directory rather than a
file and so cannot be opened for reading and writing. Only the hidden bit has
any meaning for sub-directories.
* Bit 5 - ARCHIVE BIT. Whenever a file has been written to and closed this
bit is set. This bit can be examined by, for example, the XCOPY command to
determine whether the file has been changed.
* Bit 6 - Reserved (always 0).
* Bit 7 - DEVICE BIT. This is set to indicate that the FIB refers to a cha-
racter device (eg. "CON") rather than a disk file. All of the other attri-
butes bits are ignored.
The time of last modification is encoded into two bytes as follows:
Bits 15..11 - HOURS (0..23)
Bits 10...5 - MINUTES (0..59)
Bits 4...0 - SECONDS/2 (0..29)
The date of last modification is encoded into two bytes as follows. If all
bits are zero then there is no valid date set.
Bits 15...9 - YEAR (0..99 corresponding to 1980..2079)
Bits 8...5 - MONTH (1..12 corresponding to Jan..Dec)
Bits 4...0 - DAY (1..31)
The file size is a 32 bit number stored with the lowest byte first, and is
zero for sub-directories.
The logical drive is a single byte drive number, with 1 corresponding to
A:, 2 to B: etc. It will never be zero, since if zero was specified in the
original function, this means the default drive and the driven number of the
default drive will be filled in here.
The internal information tells MSX-DOS where on the disk the directory
entry is stored. This enables functions to which the fileinfo block is passed
to operate on the directory entry, for example deleting it, renaming it or
opening it. Data stored here also enables the "find next entry" function
(function 41H) to carry on the search to find the next matching file. The
user should not access or modify the internal information at all.
Fileinfo blocks are filled in by the "find first entry", "find new entry"
and "find next entry" MSX-DOS functions. Each of these functions locates a
directory entry and fills in the fileinfo block with the relevant information
In the case of "find first entry" a directory will be searched for the
first entry which matches a given filename and which has suitable attributes
(see the Function Specification for details). "Find next entry" carries on a
search started by a previous "find first entry" function and updates the
fileinfo block with the next matching entry.
"Find new entry" is just like "find first entry" except that instead of
looking for a matching entry, it will create a new one and then return a
fileinfo block just as if "find first" had found it.
Having created a fileinfo block using one of the "find" functions there
are two ways in which it can be used. The first way is to simply use the
information which it contains such as the filename and size. For example the
"DIR" command simply prints out the information on the screen.
The more interesting way of using a fileinfo block is to pass it back to
another MSX-DOS function in order to carry out some operation on the direc-
tory entry. Many of the MSX-DOS functions described in the Function Specifi-
cation take a pointer in register DE which can either point to drive/path/fi-
le string or a fileinfo block. In either case a particular file or directory
is being specified for the function to act on.
The functions which can take such a parameter are "Delete File or Subdi-
rectory" (function 4DH), "Rename file or Subdirectory" (function 4EH), "Move
File or Subdirectory" (function 4FH), "Get/Set File Attributes" (function
50H), "Get/Set File Date and Time" (function 51H) and "Open File handle"
(function 43H). All of these carry out the obvious function on the specified
file or directory.
A fileinfo block can also be passed to a "find first" or "find new" func-
tion in place of the drive/path/file string. In this case the fileinfo block
must refer to a directory rather than a file and a filename string must also
be passed in register HL (typically null which is equivalent to "*.*"). The
directory specified by the fileinfo block will be searched for matches with
the filename, subject to the usual attribute checking. This feature is neces-
sary for the command interpreter so that a command such as "DIR A:UTIL" can
have the required action if UTIL is a directory.
3.5 ENVIRONMENT STRINGS
MSX-DOS maintains a list of "environment strings" in it's data segment. An
environment string is a named item which has a value associated with it. Both
the name and the value are user-defined. Environment strings are accessed at
the function call level via the "Get Environment String" (function 6BH), "Set
Environment String" (function 6CH) and "Find Environment String" (function
6DH) functions.
The name of an environment string is a non-null string consisting of any
characters that are valid in filenames. The name can be up to 255 characters
long. The characters of the name are upper-cased when the string is defined,
although for name comparisons case is not significant.
The value of an environment string consists of a string of non-null cha-
racters and can be up to 255 characters long. If the value of an environment
string is set to a null string, then the name is removed from the list of
environment strings. Similarly, if the value of an environment string that
has not been defined is read, then a null string is returned. The value is
not upper-cased and no interpretation is placed on the characters in the
value string.
When a transient program is loaded and executed from COMMAND2.COM, two
special environment strings are set up, which it can read.
An environment string called PARAMETERS is set up to the command line not
including the actual command name. This is similar to the one set up at 80h
for CP/M compatibility, but has not been upper-cased.
Another environment string called PROGRAM is also set up and this is the
whole path used to locate the program on disk. The drive is first, followed
by the path from the root and then the actual filename of the program. The
drive, path and filename can be separated if desired using the "Parse Path-
name" function call (function 5CH).
The PROGRAM environment string has several uses. The main use is that a
program can use it to load overlay files from the same directory as it was
loaded from. The last item in PROGRAM (ie. the actual program filename) is
replaced with the name of the overlay file, and then the new string can be
passed to any of the new MSX-DOS 2 functions that take ASCIIZ strings (such
as "Open File").
Note that some CP/M programs are capable of loading and running transient
programs, and in this case they obviously will not have set up the PROGRAM
and PARAMETERS environment strings, and they will in fact still be set up
from when the CP/M program was loaded. If a program wishes to use PROGRAM and
PARAMETERS and still be loadable from a CP/M program, then it can look at a
variable called "LOAD_FLAG", which is in page 0 at address 0037h. It is set
to zero on every MSX-DOS 2 function call but is set to non-zero immediately
before a transient program is executed by the command interpreter. Similarly,
if a new transient program has the ability to load other transient programs
and it sets up PROGRAM and PARAMETERS, then it should also set LOAD_FLAG to
non-zero.
Another special environment string is one called APPEND. This can be set
up by the user from the command interpreter and is used by the CP/M "Open
File (FCB)" function. When this function call is done and the file is not
found, an alternative directory, specified by APPEND, is searched. It is not
anticipated however that new transient programs will use this function call
or the APPEND environment string.
Several environment strings are set up by the command interpreter when it
starts up and are altered by the user to control various system features and
options, and it may be useful for transient programs to read some of these.
For example, it may be useful to read the PATH environment string or the DATE
and TIME environment strings if the program prints out dates and times. The
Command Specification contains details of these default environment strings.
3.6 FILE CONTROL BLOCKS
It is not anticipated that specially written MSX-DOS 2 transient programs
or MSX-DOS 1 or CP/M programs which are modified for MSX-DOS 2 will use the
CP/M-compatible FCB functions, but the format of the FCBs used for these
functions is given here for reference. This format is, of course, very simi-
lar to the FCBs used by CP/M and MSX-DOS 1 but the use of some of the fields
within the FCB are different (though generally compatible).
A basic FCB is 33 bytes long. This type of FCB can be used for file mana-
gement operations (delete, rename etc.) and also for sequential reading and
writing. The random read and write functions use an extra 3 bytes on the end
of the FCB to store a random record number. The MSX-DOS 1 compatible block
read and write functions also use this additional three (or in some cases
four) bytes - see the Function Specification for details.
The layout of an FCB is given below. A general description of each of the
fields is included here. The individual function description given in the
Function Specification details of how the fields are used for each function
where this is not obvious.
* 00h Drive number 1...8. 0 => default drive. Must be set up in all FCBs
used, never modified by MSX-DOS function calls (except "Open File" if APPEND
was used).
* 01h...08h Filename, left justified with trailing blanks. Can contain "?"
characters if ambiguous filename is allowed (see Function Specification).
When doing comparisons case will be ignored. When creating new files, name
will be uppercased.
* 09h...0Bh Filename extension. Identical to filename. Note that bit-7 of the
filename extension characters are NOT interpreted as flags as they are in
CP/M.
* 0Ch Extent number (low byte). Must be set (usually to zero) by the tran-
sient program before open or create. It is used and updated by sequential
read and write, and also set by random read and write. This is compatible
with CP/M and MSX-DOS 1.
* 0Dh File attributes. Set by "open", "create" or "find".
* 0Eh Extent number (high byte) for CP/M functions. Zeroed by open and cre-
ate. For sequential read and write it is used and updated as an extension to
the extent number to allow larger files to be accessed. Although this is
different from CP/M it does not interfere with CP/Ms use of FCBs and is the
same as MSX-DOS 1.
Record size (low byte) for MSX-DOS 1 compatible block functions. Must be
set to the required record size before using the block read or write
functions.
* 0Fh Record count for CP/M functions. Set up by open and create and modified
when necessary by sequential and random reads and writes. This is the same as
CP/M and MSX-DOS 1.
Record size (high byte) for MSX-DOS 1 compatible block functions. Must be
set to the required record size before using the block read and write
functions.
* 10h...13h File size in bytes, lowest byte first. File size is exact, not
rounded up to 128 bytes. This field is set up by open and create and updated
when the file is extended by write operations. Should not be modified by the
transient program as it is written back to disk by a close function call.
This is the same as MSX-DOS 1 but different from CP/M which stores allocation
information here.
* 14h...17h Volume-id. This is a four byte number identifying the particular
disk which this FCB is accessing. It is set up by open and create and is
checked on read, write and close calls. Should not be modified by the pro-
gram. Note that this is different from MSX-DOS 1 which stores the date and
time of last update here, and from CP/M which stores allocation information.
* 18h...1Fh Internal information. These bytes contain information to enable
the file to be located on the disk. Should not be modified at all by the
transient program. The internal information kept here is similar but not
identical to that kept by MSX-DOS 1 and totally different from CP/M.
* 20h Current record within extent (0...127). Must be set (normally to zero)
by the transient program before first sequential read or write. Used and
modified by sequential read and write. Also set up by random read and write.
This is compatible with CP/M and MSX-DOS 1.
* 21h...24h Random record number, low byte first. This field is optional, it
is only required if random or block reads or writes are used. It must be set
up before doing these operations and is updated by block read and write but
not by random read or write. Also set up by the "set random record" function.
For the block operations, which are in MSX-DOS 1 but not in CP/M, all four
bytes are used if the record size is less than 64 bytes, and only the first
three bytes are used if the record size is 64 bytes or more. For random read
and write only the first three bytes are used (implied record size is 128
bytes). This is compatible with CP/M and with MSX-DOS 1.
4. SCREEN CONTROL CODES
=========================
Below is a list of all control codes and escape sequences which may be
used when doing character output by MSX-DOS character functions, BIOS calls
or writing to the device CON. These are all compatible with MSX-DOS 1 and
contain the VT-52 control codes.
The screen is 24 lines of 2 to 80 characters. When a printing character is
displayed the cursor is moved to the next position and to the start of the
next line at the end of a line. If a character is written in the bottom right
position then the screen will be scrolled to allow the cursor to be positio-
ned at the start of the next line. The letters in escape sequences must be in
the correct case, the spaces are inserted for readability they are not part
of the sequence. Numbers (indicated by <n> or <m>) are included in the se-
quence as a single byte usually with an offset of 20h added.
Ctrl-G 07h = Bell.
Ctrl-H 08h = Cursor left, wraps around to previous line, stop
at top left of screen.
Ctrl-I 09h = Tab, overwrites with spaces up to next 8th
column, wraps around to start of next line, scrolls at bottom
right of screen.
Ctrl-J 0Ah = Line feed, scrolls if at bottom of screen.
Ctrl-K 0Bh = Cursor home.
Ctrl-L 0Ch = Clear screen and home cursor.
Ctrl-M 0Dh = Carriage return.
Ctrl-[ 1Bh = ESC - see below for escape sequences.
Ctrl-\ 1Ch = Cursor right, wrap around to next line, stop at
bottom right of screen.
Ctrl-] 1Dh = Cursor left, wrap around to previous line, stop
at top left of screen.
Ctrl-^ 1Eh = Cursor up, stop at top of screen.
Ctrl-_ 1Fh = Cursor down, stop at bottom of screen.
7Fh = Delete character and move cursor left, wrap
around to previous line, stop at top of screen.
Esc A = Cursor up, stops at top of screen.
Esc B = Cursor down, stops at bottom of screen.