User manual

The goal of UniDOS is to add handling of new drives while keeping as much as possible the look and feel we are all used to with the floppy disc drives. It also ensure a strong compatibility with old softwares designed to only handle A: and B: drives, while letting them access the new drives and their directories.

File management

To ensure a better compatibility, UniDOS is limited to the same naming constraints than AMSDOS. It means that file names are limiter to 8 characters, that file name extension is limited to 3, and that all the allowed and forbidden characters are the same. Thanks to that, any program designed for AMSDOS will work without any modification with UniDOS and vice versa1).

Writing files

UniDOS handles files writing like AMSDOS. Files are first created with the temporary extension “.$$$”2), then the final name is given at file close whilst renaming any already existing file with the same name as “.BAK”3).

Like AMSDOS, when no extension is provided to the file name to save, an automatic extension is added depending on the file type:

  • “.BAS” in case of a Basic file.
  • “.BIN” in case of a binary file.
  • “.LNK” in case of a symbolic link4).
  • “.   ” in any other case.

Reading files

Like AMSDOS, when no file extension is provided to the file name to load, UniDOS automatically attempts to access the file by using the following default extensions:

  1. “.   ”, file with an empty extension.
  2. “.BAS”, Basic file.
  3. “.BIN”, binary file.
  4. “.LNK”, symbolic link5).

Drives handling

To handle new drives related to hard disks or USB ports, rather than adding letters which are often cryptic and require to modify existing program to take them into account, UniDOS introduces the concepts of logical drives and physical drives.

Access to files can be done through either a logical or physical drive name.

Logical drives

These drives remain the traditional AMSDOS drives: A: and B:. But what is changing with UniDOS is that these drives A: and B: are reconfigurables and can become aliases to any physical drive6).

Then, the drive A: can be assigned to the physical drive of your hard disk whilst drive B: could be the internal 3“ drive of your CPC.

Logical drives assignation

Logical drives assignation is done dynamically, either directly with the LOAD command of Basic, or with the RSX |DRIVE used with two parameters instead of one.

To assign the current logical drive to the physical drive SD::

LOAD"SD:"

To assign the current logical drive to the path “SD:GAMES/ACTION”:

LOAD"SD:GAMES/ACTION"

To assign the logical drive A: to the path “SD:GAMES/ACTION”:

|DRIVE,"A","SD:GAMES/ACTION"

The RSX |DRIVE without parameter will display the list of the available physical drives on your CPC (with their description) and the current assignation of the logical drives.

|DRIVE

Available DOS devices:
   DFA: Floppy Disc A
    SD: MicroSD Card
  ZERO: Bytes provider

Logical drives:
 >A: SD:GAMES/ACTION/
  B: DFA:
Logical drives persistency

It is important to notice that the logical drives assignation is persistent.

Are kept after a reboot or a power off of the CPC:

  • The current logical drive (A: or B:).
  • Assignation of each logical drive.

Not only this persistency is quite convenient for the user, it also allows all the programs which are manually reinitializing the ROMs to work in a transparent manner (and even the softwares which could only work from A: when using AMSDOS/ParaDOS will now work from any drive thanks to UniDOS).

By default, before any modification from the user, A: is the current logical drive and it is assigned to the path DFA: ; the logical drive B: is assigned to the path DFB:.

Please note that some DOS nodes could modify these default values; refer to their documentation.

If the user hold the key CONTROL during the boot of the CPC, the persistency is reset to the default values7). Persistency could also be reset automatically in case of UniDOS ROM update. Anycase, a beep is emitted.

Physical drives

The physical drives are drives which are related to specific peripherals. They consist in names up to 8 characters plus a terminal ”:“. DOS nodes are providing them (either statically or dynamically).

UniDOS internal physical drives

Two physical drives exist automatically when AMSDOS or ParaDOS was found. They are associated to internal and external floppy disc drives.

They consist in:

  • DFA: for the internal floppy disc drive.
  • DFB: for the external floppy disc drive.

To load a file from the internal floppy disc drive8), you could write:

LOAD"DFA:MYFILE"

Another physical drive exist automatically when a tape interface is detected:

  • TAPE: let you access the tape like a regular drive.
DOS nodes physical drives

Each DOS node can provide up to 8 new physical drives to the system. Each drive is more or less sophisticated depending on the hardware or software capabilities (removable or not; supporting directories or not; limited to read only or not; limited to write only or not; seek in files support or not, …).

Refer to the DOS nodes user manual to know about the physical drives and their properties.

Paths handling

UniDOS introduces support for directories on all capable medias. Access to directories and files is done in a standard manner, similar to what can be found on other systems.

General syntax to access a path is the following;

DRIVE:LEVEL-1/LEVEL-2/.../LEVEL-N/FILE

Drive name is before ”:“, it can be either a logical or a physical drive name; directories names are following, separated by ”/“ for each level. UniDOS currently supports up to 6 levels.

Names of the directories are in the same form than file names, 8 characters for the name itself, and 3 for the extension. They also provide the same attributes, so that like a file, a directory can be write protected and/or hidden.

Please note that to keep AMSDOS compatibility, the “USER” number can still be provided before the drive name, so that the path “5A:DIR1/DIR2/FILE” is valid. If A: is not assigned to a physicial drive handled by AMSDOS, the “USER” is then silently ignored.

Directory changing

Logical drives A: and B: are each assigned to both a physical drive and a path. The choice of the current logical drive is done through the traditional RSX |A and |B.

The physical drive and path assigned to the current logical drive can be simply changed by using the LOAD command. To change to the sub-directory “ACTION” in the directory “GAMES” from the drive SD: you can enter:

LOAD"SD:GAMES/ACTION"

You can also use relative path, so that the following sequence is equivalent to the previous command:

LOAD"SD:"
LOAD"GAMES"
LOAD"ACTION"

You can go back to the root of the physical drive with:

LOAD":"

You can go to the directory “GAMES” from the root of the current drive with:

LOAD":GAMES"

You can go to a directory “TOOLS” from the preivous level with:

LOAD"/TOOLS"

And to go up by two level then enter a new directory from this point:

LOAD"//DEMOS"

All these commands will open a directory if the target is a directory. In casde the taget is a file, then the file will be opened.

It is possible to force directory opening, so that the command will fail if the target is a file. It is done simply by adding a ”/“ to the edn of the path. That way, the following command will fail if “DEMOS” is a file:

LOAD"DEMOS/"

Directory creation

Similar to the LOAD command, adding a ”/“ at the end of the path given to the SAVE command will create a directory instead of a file.

To create a directory “DRAWER” is the current path, you can type:

SAVE"DRAWER/"

File access

Paths can be used within all traditional command designed for simple file names. It means that you can provide paths to the commands RUN, LOAD, SAVE, etc.; but also ti the RSX |ERA, |REN, |DIR, etc..

All these mechanism are generic, so that:

  • LOAD”LOADER“ will load the program “LOADER” located in the current path.
  • RUN”:DISK“ will execute the program “DISK” located at the root of the current drive.
  • |COPY,”UMS:CAPTURE.SCR“,”:SCREENS/“ will copy the file “CAPTURE.SCR” located at the root of the UMS: drive to the directory “SCREENS” located at the root of the current drive (see section dedicated to the |COPY RSX for more information).
  • |DIR,”SCREENS/*.*“ will list all the files located in the directory “SCREENS” from the current path level (see section dedicated to the |DIR RSX for more d'information).

Please note that when the name of a logical drive is user, the expressed path is relative to the path assigned to the logical drive. For instance, if the logical drive A: is assigned to “SD:GAMES” then you can load the program “MENU” from the directory “SD:GAME/ACTION” this way:

LOAD"A:ACTION/MENU"

The files without a name, like they can exust of “stream” type drives (like the tape or a serial drive) can be accessed with the character . (dot).

RUN"TAPE:."

Catalog

The files catalog of the current directory can be obtained normally, with the legacy CAT command. The result is similar to what AMSDOS produces, except that sizes are displayed using four digits instead of only three9), and that the unit is dynamic.

If the size of a file (or the free space on disk) is larger than 1000KiB, then it will be expressed using MiB, if it is larger than 1000MiB, GiB will be used ; and beyond 1000GiB, TiB will be displayed. In case or directories, a marker [DIR] is displayed instead of the size.

In the catalog header, the name of the current directory is displayed between brackets right after the name of the physical drive:

CAT

Device SD: [ROOT]

!UNIDOS!.NVM    2K  DMADEMO .    [DIR]  LSUSB   .BAS    6K  STK     .    [DIR]
B2F     .    [DIR]  EQUINOXE.    [DIR]  OCP     .    [DIR]  STKDMA  .    [DIR]
BENCH   .BAS    3K  FAIRY   .      14K  OFE5    .    [DIR]  STKOS   .    [DIR]
BRKPOINT.AVI  311M  GAMES   .    [DIR]  PAO     .    [DIR]  TEST    .AVI    1G
DIGITRAK.    [DIR]  LARSEN  .    [DIR]  SCREENS .    [DIR]  

  51G free

Like AMSDOS does, result is sorted by name, and the number of columns depends on the current window width. Also, the display can be interrupted like the Basic LIST command: press ESC once will hold the operation, twice it will interrupt it; this is quite convenient when displaying large catalogs.

The maximum number of files displayable through the CAT command is 146, beyond this limit the message “Other files exist” will be displayed at the end of the catalog to let you know that the entire file list could not be displayed10). The RSX |DIR and |INFO do not have this limitation and are always capable to display the entire file list.

CAT'arts AMSDOS will be still properly displayed from floppy discs, but adaptations might be required so that they still work once the file copied to another device.

Please note that the RSX |DIR behaves exactly like AMSDOS' one (see section dedicated to |DIR RSX for more information), the files being displayed without sorting and without their size; which allows display in five columns in full width mode 2, but won't allow to distinguish file from directories:

|DIR

Device SD: [ROOT]

TEST    .AVI   BRKPOINT.AVI   !UNIDOS!.NVM   BENCH   .BAS   LSUSB   .BAS 
FAIRY   .      STKOS   .      STKDMA  .      STK     .      SCREENS .    
PAO     .      OFE5    .      OCP     .      LARSEN  .      GAMES   .    
EQUINOXE.      DMADEMO .      DIGITRAK.      B2F     .    

  51G free

In addition, UniDOS adds a RSX |INFO similar to the one of Utopia ROM from Arnor Ltd. and which allows to obtain detailled information on files (see section dedicated to |INFO RSX for more information):

|INFO

              SIZE      LOAD LOGL ENTRY
BRKPOINT.AVI  13722198  ---- ---- ----
TEST    .AVI  4DC88660  ---- ---- ----
!UNIDOS!.NVM  000004F5  ---- ---- ----
BENCH   .BAS  00000996 $0170 0916 0000
LSUSB   .BAS  0000168C  ---- ---- ----
FAIRY   .     0000379F &0800 371F 0800
STKOS   .     Dir
STKDMA  .     Dir
STK     .     Dir
SCREENS .     Dir
PAO     .     Dir
OFE5    .     Dir
OCP     .     Dir
LARSEN  .     Dir
GAMES   .     Dir
EQUINOXE.     Dir
DMADEMO .     Dir
DIGITRAK.     Dir
B2F     .     Dir

UniDOS also provides support for symbolic links.

Symbolic links car be created with the |MAKELINK RSX for which you will find detailled information in the dedicated section. Once a link has been created, all read access to it will automatically redirect to its target.

Symbolic links can have any file, directory or even logical or physical drive as target. Moreover, the target can be linked with either an absolute or relative path. The target do not need to exist when the link is created; it allows dynamic links which are quite useful when used with a removable medias as target (such as USB sticks or floppy discs).

Symbolic links also work from and to floppy discs, even if AMSODS itself cannot handle them.

By default, symbolic links are created and loaded with the extension ”.LNK“ but any extension can be specified. Like files and directories, a symbolic link can be write protected and/or hidden. Deleting a symbolic link will destroy the link itself, not its target.

RSX

All RSX from UniDOS do have an automatic redirection. It means that if RSX are called whilst UniDOS is not active, the RSX from the AMSDOS will be called instead.

Most RSX provided by UniDOS are identical to the ones from AMSDOS, with sometimes more features. Furthermore, they are all interruptible like the Basic command LIST: press once ESC will put the operation on hold, twice will interrupt it; this is quite useful when displaying large catalogs.

Please note that some of the additional RSX are not compatible with floppy discs handled by AMSDOS: this is the case of |PROTECT, |UNPROTECT, |HIDE, |SHOW and |INFO.

|DOS

This RSX activates UniDOS and management of all DOS nodes. This is the default, but if UniDOS was disabled by using |DISC or |TAPE then this RSX allows you to reenable it..

It is important to notice that the UniDOS activation state is part of the persistent information. It means that once UniDOS was disabled, it will remain disabled even after a restart of the CPC.

|DISC

This RSX activates AMSDOS (instead of UniDOS or tape management). See |DOS for more details.

Variants |DISC.IN and |DISC.OUT are activating AMSDOS only for input or output files (they are here for historical reason and their usage is limited to mix AMSDOS and tape management only; mixing input and output files between UniDOS and AMSDOS is forbidden).

|TAPE

This RSX activates the tape management (instead of UniDOS or AMSDOS). See |DOS for more details.

Variantes |TAPE.IN and |TAPE.OUT are activating tape management only for input or ouput files.

|A

Activates the logical drive A: as the current drive.

Current assignation of drive A: is then used (and altered) by file and directory handling commands.

|B

Activates the logical drive B: as the current drive.

Current assignation of drive B: is then used (and altered) by file and directory handling commands.

|DRIVE

Unlike command |DRIVE from AMSDOS which roughly takes one single parameter, UniDOS also allows to use it without parameter or with two parameters

Without parameter

Syntax: |DRIVE

List available DOS devices and the current assignation and activation state of the logical drives.11).

Caution, this command is different from |NODE which lists all the supported drives.

|DRIVE

Available DOS devices:
   DFA: Floppy Disc A
    SD: MicroSD Card
  ZERO: Bytes provider

Logical drives:
 >A: SD:GAMES/ACTION/
  B: DFA:
With one parameter

Syntax: |DRIVE,”[A|B]“

Identical to AMSDOS:

  • |DRIVE,”A“ does the same as |A.
  • |DRIVE,”B“ does the same as |B.
With two parameters

Syntax: |DRIVE,”[A|B]“,”PATH“

Assign the specified path to the logical drive A: or B:.

This path can be absolute or relative to the current assignation of the logical drive to alter.

|DRIVE,"B","SD:GAMES/ACTION"

|PATH

Without parameter

Syntax: |PATH

Display the current path (the one corresponding to the assignation of the current logical drive).

The returned path is always an explicit path; it means that it is always endings by a ”/“ (or by a ”:“ if we are at the root of the drive) and that it can directly be used as a prefix to concatenate a additional file or directory name.

|PATH
SD:GAMES/ACTION/
With one parameter

Syntax: |PATH,@var$

Return the current path in the variable var$.

var$=SPACE$(255)
|PATH,@var$
PRINT vars$
SD:GAMES/ACTION/

|DIR

Identical to |DIR RSX from AMSDOS, the only difference is that paths are handled.

Tip: if the path provided as parameter is an explicit path (for instance “SD:” or “GAMES/”), then its contents will be listed, just like if the pattern “*.*” were used.

Please note the difference between |DIR,”GAMES“ (“GAMES” is then a filtering pattern) and |DIR,”GAMES/“ (“GAMES” is then an explicit directory) :

|DIR,"GAMES"

Device SD: [ROOT]

GAMES   .    

  51G free
|DIR,"GAMES/"

Device SD: [GAMES]

DIZZY   .      IRON    .    
SEYMOUR .    

  51G free

|ERA

Identical to |ERA RSX from AMSDOS, the only difference is that paths are handled.

During deleting operation, a confirmation will be asked to the usr for each protected or hidden file encoutered.

Tip: if the path provided is an explicit directory (name ending with ”/“; for instance “GAMES/”), then all the files it contains will be automatically deleted (like if the pattern “*.*” was given), but not the direcory itself.

Please note the difference between |ERA,”GAMES“ (“GAMES” is then a filtering pattern) and |ERA,”GAMES/“ (“GAMES” is then an explicit directory). In the first case, the directory “GAMES” and its contents are deleted, in the second case only the contents of the directory “GAMES” will be deleted.

Always use |ERA carefully; it is impossible to recover a deleted file or directory.

|REN

Identical to |REN ROM from AMSDOS, the only difference is that paths are handled.

Please note that |REN can also move files from a directory to another on devices supporting it.supportant.

|PROTECT

Syntax: |PROTECT,”path“

Set write protection on files and directories matching the provided path (path can contain wildcards).

|UNPROTECT

Syntax: |UNPROTECT,”path“

Remove write protection from files and directories matching the provided path (path can contain wildcards).

|HIDE

Syntax: |HIDE,”path“

Hide from the catalog files and directories matching the provided path (path can contain wildcards).

|SHOW

Syntax: |SHOW,”path“

Show again in the catalog files and directories matching the provided path (path can contain wildcards).

|INFO

Syntax: |INFO,”path“

Identical to |DIR but with a detailled display and also including hidden files.

The output follow this pattern:

              SIZE      LOAD LOGL ENTRY
BASIC   .BASphFULLSIZE $LOAD LOGL NTRY
BINARY  .   phFULLSIZE &LOAD LOGL NTRY
LINK    .   phFULLSIZE .LOAD LOGL NTRY
ASCII   .   phFULLSIZE  ---- ---- ----
DIR     .   phDir

Where stand 8 columns which display:

  1. The name of the file or directory.
  2. p: tag for write protection; “*” if protected, empty otherwise.
  3. h: tag for visibility; ”!“ if hidden, empty otherwise.
  4. FULLSIZE: physical size of the file; displayed as 32-bit hexadecimal value.
  5. Type of the file:
    • $ for a Basic file.
    • & for a binary file.
    • , for a symbolic link.
    • Empty for ASCII files12) or a directory13).
  6. LOAD: loading address of the file; displayed as 16-bit hexadecimal value.
  7. LOGL : logical size of the file; displayed as 16-bit hexadecimal value.
  8. NTRY : execution address of the file; display as 16-bit hexadecimal value.

Syntax: |MAKELINK,”LINK“,”TARGET“

Create a symbolic link named “LINK” pointing to the target path “TARGET”.

The target path can be a path to a drive, a directory, a file or even another symbolic link. It do not need to exist at the link creation, only at link reading.

With one parameter

Syntax: |READLINK,”LINK“

Display the target of the symbolic link named “LINK”.

|READLINK,"SCREENS"
UMS:FILES/PICTURES/
With two parameters

Syntax: |READLINK,”LINK“,@var$

Returns the target of the link in the variable var$.

var$=SPACE$(255)
|READLINK,"SCREENS",@var$
PRINT vars$
UMS:FILES/PICTURES/

|COPY

Syntax: |COPY,”SOURCE“,”DEST“

Copy a file from “SOURCE” to “DEST”.

“SOURCE” and “DEST” can be paths to any directory of any drive, but with the following considerations:

  • “SOURCE” shall be a plain file name (wildcards are not allowed yet).
  • If “DEST” does not exist or is a file then the source file is renamed to this new name during copy (existing file is overwritten).
  • If “DEST” is a directory then the source file is copied inside this directory (keeping its original name).
  • If “DEST” is an explicit directory name (ending with a ”/“) then copy will fail if a file with this name already exists (existing file won't be overwritten), otherwise the source file will be copied inside the direcory (keeping its original name).

Copy of the file “MENU.BAS” from the path “SD:GAMES/ACTION” to the path “UMS:” whilst renaming it to “DISK.BAS”:

|COPY,"SD:GAMES/ACTION/MENU.BAS","UMS:DISK.BAS"

Copy of the file “MENU.BAS” from the path “SD:GAMES/ACTION” to the path “UMS:” whilst keeping the original name:

|COPY,"SD:GAMES/ACTION/MENU.BAS","UMS:"

Copy of the file “MENU.BAS” from the path “SD:GAMES/ACTION” to the path “UMS:COPYOF” with the option to fail if a file with this name already exists:

|COPY,"SD:GAMES/ACTION/MENU.BAS","UMS:COPYOF/"

|FORMAT

Syntax: |FORMAT,”DRIVE:“

This RSX allows you to initialize the drive DRIVE:.

For instance, |FORMAT,”IDE:“ will format the drive IDE: by creating a FAT partition on the whole disc.

|NODE

This RSX displays the installed DOS nodes and their list of supported drives.

Without parameters

Syntax: |NODE

List installed DOS nodes. These can be ROMs of type extension or background. In this later case, if the DOS node allocated some memory, its address will be displayed. ”!“ character marks the DOS node which is handling the non volatile memory.

|NODE
ROM  1:NOVA             0.10!extension
ROM  7:UNIDOS           1.32 back &A700
ROM  8:FATFS            1.21 background
ROM 27:ALBIREO          1.20 extension
ROM 28:ZERO             1.10 extension
With one parameter

Syntax: |NODE,”ROM NUMBER“

List drives which can be handled by the provided DOS node ROM number; the result depends of devices detected by the node.

Caution, this command if different from |DRIVE which is only listing drives which are actually available (which are both detected and with an inserted media).

|NODE,27
ROM  5:ALBIREO          1.20 extension
    SD: MicroSD Card
   UMS: USB Mass Storage

|LOAD

This RSX allows you to load any kind of file anywhere in memory.

It is similar to the RSX of the same name which is available in Maxam and Utopia ROMs from Arnor Ltd, and has the advantage to allow direct loading in memory of any kind of file, including ASCII files (which is normally impossible from BASIC). Also, it does not allocate the 2K memory buffer like does the BASIC LOAD command, and it ignores the HIMEM (which allows to load the file anywhere).

Eventually, this RSX can also be used to open directories, like it can be done with the BASIC LOAD command; it has the advantage not to generate an error in this case, which could be interesting when writing BASIC programs which are manipulating directories (see annexes for more details).

With one parameter

Syntax: |LOAD,”PATH“

If the path is corresponding to a file of type binary or BASIC, then it will be loaded according to information contained in its header.
If the path is corresponding to an ASCII file, then an error will occur telling that the second parameter (the loading address) shall be given (see bellow).
If the path is corresponding to a directory, then it will be opened like with the BASIC LOAD command.

With two parameters

Syntax: |LOAD,”PATH“,ADDRESS

If the file is corresponding to a file, whatever its type is, it will be loaded at the provided address.
If the file is corresponding to a directory, then the address is ignored and it will be opened like with the BASIC LOAD command.

|SAVE

This RSX allows you to save binary files.

It is similar to the RSX of the same name which is available in Maxam and Utopia ROMs from Arnor Ltd, and has the advantage not to allocate the 2K buffer like does the BASIC SAVE command.

Eventually, this RSX can also be used to create a directory, like it can be done with the BASIC SAVE command; it has the advantage not to generate an error in this case, which could be interesting when writing BASIC programs which are manipulating directories (see annexes for more details).

With one parameter

Syntax: |SAVE,”EXPLICIT PATH“

Create the directory corresponding to the provided explicit path (an explicit path is a path with an ending ”/“).

With three parameters

Syntax: |SAVE,”PATH“,ADDRESS,LENGTH

Save a binary file from the provided address and with the given size.

With four parameters

Syntax: |SAVE,”PATH“,ADDRESS,LENGTH,EXECUTION

Save a binary file from the provided address, with the given size and by specifying the execution address.

|SAVEA

This RSX allows you to save ASCII files.

It is similar to the RSX of the same name which is available in Maxam and Utopia ROMs from Arnor Ltd, and has the advantage not to allocate the 2K buffer like does the BASIC SAVE command.

Eventually, this RSX can also be used to create a directory, like it can be done with the BASIC SAVE command; it has the advantage not to generate an error in this case, which could be interesting when writing BASIC programs which are manipulating directories (see annexes for more details).

With one parameter

Syntax: |SAVEA,”EXPLICIT PATH“

Create the directory corresponding to the provided explicit path (an explicit path is a path with an ending ”/“).

With three parameters

Syntax: |SAVEA,”PATH“,ADDRESS,LENGTH

Save a binary file from the provided address and with the given size.

1)
of course, given that the program is nicely using the operating system and do not do ugly tricks
2)
except on drives of type “stream”
3)
if a “.BAK” file already exists, it is deleted and remplaced
4) , 5)
new feature specific to UniDOS
6)
you may already know this concept since it was already existing (in a primitive way) in The Rodos System from Romantic Robot
7)
a beep is then emitted to signal this reset
8)
whatever the logical drives configuration is
9)
there is then only two spaces instead of three between columns
10)
only the first 146 sorted by name will then be displayed
11)
the symbol ”>“ indicated the active logical drive
12)
in this case, next columns are empty too
13)
in this case, next columns are just containing the keyword “Dir”