cpcfs.doc

NAME
----
        CPCFS - CPCEmu Filesystem Maintenance           Version: 0.85


SYNOPSIS
--------
        CPCFS                   to invoke an interactive session
        CPCFS <commands> ...    to perform batch commands


DESCRIPTION
-----------
CPCFS is a program to copy files form a DOS filesystem to a
disk-image appropriate for CPCEmu, an emulator for the
CPC464/664/6128 homecomputer series by Amstrad.

Note:	This documentation is generated out of CPCFS' help file CPCFS.HLP.
	Some "See also"-hints can therefore be misleading!


INVOCATION
----------
Either call CPCFS in interactive mode:

	CPCFS

or in batch mode:

	CPCFS [<image>] <commands>...

where
  <image> is the name of the image on which <commands> should be applied
  <commands> are
	-g 	get	    ³	-?	usage message
	-mg	mget	    ³	-f	toggle force
	-p	put	    ³	-b	binary mode
	-mp	mput	    ³	-t	text mode
			    ³	-e	execute next commands
	<none>	dir	    ³
	-d	dir	    ³	-nd	Create a new data/system/vortex image.
	-s	stat	    ³	-ns	The imagename must immediately follow
	-x	source	    ³	-nv	this switch. (e.g. CPCFS -ND FOO)

Note: Options after -e are considered as options for CPCFS commands!
      Exitcodes are 0 (ok), 1 (error), or 2 (^C pressed)

Options are simply a shortcut for commands. The first argument can
be the name of an imagefile, all following arguments are commands.
If you omit a command and only give <image> ``dir'' is assumed.

Used environment variables:

	CPCFSHOME	directory for CPCFS.CFG and CPCFS.HLP, if differnet
			from the directory where CPCFS.EXE resides.
	PAGER		command to use for paging (default: internal pager)
	TEMP		directory for temporary files (default: current)
	COMSPEC		specifies the standard command processor for DOS

PAGER must point to a program that expects its argument on the commandline,
and not from stdin, so MORE.COM does not work. V. Buergs's famous LIST does
not work the most time, I don't know why. I recommend LESS.

You can get a listing of all enviroment variables with !SET.
See your DOS manual for further documentation about TEMP and COMSPEC.



COMMANDS
--------
All commands are case insensitive. Some commands write an informational
message, if they are invoked without an argument (mode, open, page,
prompt, verbosity,...). Some commands have more names than one. You can
use the name that you like most.

List of available commands in alphabetical order:

!	?	attrib	bye	cd	close	cls	comment	copy	del
dir	dira	dpb	dump	echo	era	exit	force	format	get
help	lcd	ldir	map	mget	mode	mput	new	open	page
prompt	put	quit	ren	source	stat	sysgen	type	user  verbosity


Commands grouped according to functionality:

General:		close	open	user
Transfer data:		get	mget	mode	mput	put	sysgen
DOS access:		!	cd	lcd	ldir
CP/M maintenance:	attrib	copy	comment	del	dir	dpb	dump
			era	format	new	ren	stat	type
User interface:		?	bye	cls	echo	exit	force	help
			verbosity	page	prompt	quit	source
Obsolete:		dira	map


Standard options for several commands:
	* -c  output to console, when default is output to a pager
	* -f  force overwriting of existing files
	* -b  transfer in binary mode
	* -t  transfer in text mode (up to first Ctrl-Z)

The f, b, and t options control the copying process and are available for
	get	mget	put	mput	type	copy
The c option controls the display mode and is available for
	type	dump	stat

See also:
	variables (PAGER)	force	mode



GENERAL commands
================

OPEN <file>
	Load an image

Closes the one in memory, if any. It appends the string ".DSK" to the
DOS filename, if no extension is given.


CLOSE
	Close the current image


USER <number>[:]
	Set user area. <number> should be in 0 .. 15.
 	The USER command itself can be left out.

Note: USER 229 does _not_ allow access to deleted files!

Example:
	USER 0			back to default user
	USER 0:			(additional colon possible)
	0:			(shortcut form, colon required)



TRANSFER commands
=================

GET <options> <cpm-filename> [<dos-filename>]
	Copies a file from CPC to DOS filesystem. If <dos-filename> is
	present, <cpm-filename> is renamed while copying.
GET <options> <cpm-filename>... <dos-path>
	Copies some files form CPC to a DOS directory. <dos-path> must
	end with a backslash (otherwise GET ONE PATH would be ambigous)

Example:
	GET FOO			copies to .\FOO
	GET FOO DOSFOO		copies to .\DOSFOO
	GET FOO BAR ..\		copies to ..\FOO and ..\BAR

See also:
	options		filenames


MGET <options> <cpm-filespec>...
	Same as GET, but works with wildcards instead of names (m = multiple)
	Renaming on the fly and getting to other directories is not
	possible here.

See also:
	options		filenames


PUT <options> <dos-filename> [<cpm-filename>]
	Copies a file from DOS to CPC filesystem. If <cpm-filename> is
	present, <dos-filename> is renamed to that name.
PUT <options> <dos-filename> <userarea>:
	Copies *one* file from DOS to a user area of the CP/M filesystem.
	The colon after <userarea> is important!

See also:
	options		filenames


MPUT <options> <dos-filespec>...
	Same as PUT, but works with wildcards instead of names (m = multiple).
	Renaming on the fly and putting to other user areas is not
	possible here.

See also:
	options		filenames


MODE <mode>
	Set transfer mode to either Binary, Text, or Auto.
	  * Binary	the whole file is processed
	  * Text	the file is processed up to the first Ctrl-Z
	  * Auto	Binary or Text processing depends on the analysis
			of the file (>70% printable => Text, otherwise Bin)

See also:
	options

Printable characters are newlines (10,13) and characters between space (32)
and tilde (126). <mode> can be abbreviated to its first character B, T, or A.


SYSGEN <file>
	Writes the CP/M-System from <file> to current image.

Note: The image must be in system format!

It only works, if the image was formatted with two system tracks (e.g.
system or vortex format). See STAT, if you want to know the format or
whether CP/M is already in the image.

To obtain a CP/M-image you can use the accompanying BASIC program
GETCPM.BAS. It runs on a CPC and copies the system tracks off a real CPC
disk to the file SYSTEM.CPM. Then transfer the file to DOS.

If you want to "sysgen" your vortex image, you must prepare CP/M first
(see your vortex documentation). WARNING: I do not own a vortex drive
nor its documentation, so I cannot tell if it works. Feedback is
highly appreciated!!!


DOS ACCESS commands
===================

!<command>
	Execute a DOS command or open a shell, if there is no <command>

See also:
	variables (COMSPEC)	ldir	cd

Executes the program <command> in a DOS-Shell. If only a "!" is
typed, CPCFS invokes the interactive shell given in the %COMSPEC%
environment variable or C:\COMMAND.COM if the variable isn't set. You
must type EXIT to return from the shell to CPCFS. Contrary to other
commands there is no space needed behind the "!".


CD <dos-drive&path>
LCD <dos-drive&path>
	Change the current DOS drive and/or directory.
	This is *not* equivalent to !CD.

Example:
	CD C:\TEMP


The "L" in LCD (as well as in LDIR) reminds you, that this command
affects the local filesystem of DOS.


LDIR <dos-filespec>
	Print the current DOS directory.
	Equivalent to !DIR.

Example:
	LDIR *.DSK

See also:
	!



CP/M MAINTENANCE commands
=========================

Informational
-------------

DIR <options> <cpm-filespec>
	Print the directory of the current user area.
	<options> are:
	 <none>	(default)	two files per line
	  -w	(wide)		four files per line
	  -l	(long)		including a lot of information
	  -a	(amshead)	including Amsdos Header, if available
	  -u	(unsorted)

The amount of output:
wide    = name, size
default = wide + user, R/O attribute, more-attributes-mark, alloc. entries
long    = default + all attrib., detected mode, alloc. blocks, alloc. records
amshead = default + Amsdos Header

Note: -a, -l, and -w are mutually exclusive!
      Use DIR *:*.* to see all user areas.

See also:
	filenames


STAT
	Print status information about
	  * Format of current image
	  * Allocation
	  * Internal variables

See also:
	comment		dpb


DPB
	Prints the contents of the current Disk Parameter Block plus
	geometrical information about the image.

See also:
	stat	background

Record:		the smallest piece of data accessible by CP/M (128 bytes)
Block:		the smallest allocation entity (1024 bytes, vortex: 4096 bytes)
Directory:	the first blocks of the filesystem
Dir.entry:	32 bytes containing the filename and blockpointers
Blockpointer:	one or two bytes pointing to a block of data
Extent:		the amount of blockpointers pointing to 16k of data


COMMENT -d
	(DEFAULT) Place CPCEMU's default comment into the image (e.g. for CPE)
COMMENT -n
	(NOW) Places a timestamp in the comment field. This is the default
	for newly created images.
COMMENT <string>
	Set the comment field to an arbitrary string of at least 40 characters.

Example:
	COMMENT -D	replacement for DROP_TAG.EXE, see DROPTAG.BAT

See also:
	percent


TYPE <options> <cpm-filename>
	Writes the content of a file to the screen. If in binary mode or
	binary mode is detected, the content is translated to hexadecimal.

Example:
	TYPE TEXT		assumes detected textmode
	TYPE -B TEXT		force the text to hexdump

Options:
	-f <dos-filename>	write output to a file, instead of screen

See also:
	options (except of -f)


DUMP <options> -d	Dump the complete directory structure
DUMP <options> -m	Dump an allocation map
DUMP <options> [ -b# | -h# | -t# | -s# | -1 | -2 ]	Dump some data blocks

Directory dump -- shows:
    entry number, first-entry tag ">", user area, name, extent, records,
    attributes, block-pointer, last-entry tag "<<<" or next-entry-pointer ">##"

Allocation dump -- shows for each sector:
    $$	CP/M			      ³	<num>	Used for file in entry <num>
    DD	Directory		      ³	--	Not used

Data dump -- options:
    -b<block-number>		      ³	-h<head-number>
    -1	next is start pos (def 0)     ³	-t<track-number>
    -2	next is last pos (def start)  ³	-s<sector-number>

Overall options:
    -c  to stdout/console	      ³	-f <dos-filename> to a file

Example:
	DUMP -B0 -2 -B2		       	first three blocks
	DUMP -H0 -T0 -S0 -2 -H1 -Fside	hexdump of one side to a file

Note: Options for DUMP can be packed, but this can be confusing
      E.g. DUMP -B0 -2B5 for blocks 0 to 5
      or   DUMP -12	 for blocks form beginning (1) to the same block (1)


Changing files
--------------

NEW [-s | -d | -i | -v]  <imagename>
FORMAT ...
	Build a new empty image file
	The available formats are
	  * -s  SYSTEM		169k net capacity + CP/M tracks
	  * -d  DATA		178k net capacity		(default)
	  * -i	IBM		154k net capacity + CP/M tracks
	  * -v  VORTEX		708k net capacity + CP/M tracks

Note: To access a vortex image from a CPC emulator you need the vortex ROMS!

See also:
	sysgen	stat	dpb


DEL [-f] <cpm-filespec>...
ERA [-f] <cpm-filespec>...
	Delete files.
	Ask for permission, if a file is R/O. Do not ask if -f is given.

Example:
	DEL *.C *.H	\ Deletes all .C and .H file
	DEL *.[CH]	/
	DEL -f *:*.*	  Deletes the whole image!
	DEL 1: 2:	  Deletes user 1 and 2


REN <from-cpm-filespec> <to-cpm-filespec>
REN <from-cpm-filespec>... <userarea>
        Rename a file or shift a set of files to another user area.

Example:
	REN FOO.BAR SENSIBLE.NAM
	REN A.LOT OF FILES.* 1:

REN uses the well-known DOS order for renaming (think of the word TO
between the filenames) and not the (possibly expected) CP/M order (think
of ":=" between the filenames)


ATTRIB <attributes>... <cpm-filespec>...
	Set or reset attributes of files.

Attributes are:
	R/O		readonly			(i.e. R=ON)
	R/W             readwrite			(i.e. R=OFF)
	DIR		appears in directory		(i.e. S=OFF)
	SYS		system file (used for CP/M 3.0)	(i.e. S=ON)
	A		Archive "on" or "off" (used for CP/M 3.0)
	<extended>	there are 8 extended attributes F1..F8, that can
			be either "on" or "off".

Change the R/O, R/W, DIR, and SYS by simply mentioning them with prefixed "-".
Set A and F1..F8 with -A=ON, -F1=OFF, etc.

Note: F5..F8 are officially reserved for CP/M!

Example:
	ATTRIB -R/O -DIR -F1=ON *.C *.H


COPY <options> <from-cpm-filename> <to-cpm-filename>
COPY <options> <cpm-filespec>... <userarea>
	The first form copies a file to a second file.
	The second form copies a set of files to another user area with the
	same name.

Example:
	COPY FOO.BAR SENSIBLE.NAM
	COPY A.LOT OF FILES.* 1:

See also:
	options




USER INTERFACE comamnds
=======================

# <any-text>
	This is a comment. Everything upto the next command is ignored.


BYE
EXIT
QUIT
	Leaves CPCFS.
	You can also type Ctrl-Z as a shortcut.

Quits CPCFS. You can hit Ctrl-Z to achieve the same purpose, only faster!
(The Unix version uses Ctrl-D as shortcut for Quit)


HELP <topic>
	Gives help about a command or about a general topic.
	Type help alone to see these topics.

The following special characters are used to describe the syntax
	  <___>		identifier
	  [___]		optional
	  __|__		alternative
	  (___)		grouping
	  ___...	repetition

The following special identifier are used:
	<cpm-filename>, <dos-filename>	a filename without wildcards
	<cpm-filespec>, <dos-filespec>	a filename with/without wildcards
	<userarea>			a user number out of 0..15

See also:
	filenames	options

The startup helppage is:
-----------------------------------------------------------------------------
Type
	HELP <commandname>

for information on that command or

	HELP <topic>

on one of the following general topics:
	commands	options		values		filenames
	percent		variables	invocation	editing
	about		background	bugs

-----------------------------------------------------------------------------

SOURCE <scriptfile>
	Execute the commands in <scriptfile>. The script CPCFS.CFG is
	automatically executed at startup of CPCFS.

Example:
	SOURCE MY.CFG


ECHO <string>
	Write the string.
	If you have ANSI.SYS loaded, you can use ANSI sequences (see example).

Note: Parameters of ANSI sequences must be separated by %s, and not ";"!

Example:
	ECHO "The current image is %i"
	ECHO "%e[31%s1mBright Red%e[0m and back to normal"

See also:
	percent		values


PROMPT <string>
	Set the prompt. You may use percent expansion.

Example:
	PROMPT "Image %i is %a%% full. What now? "

See also:
	percent		echo	values


CLS
	Clear screen.


FORCE
	Toggle ``Ask on overwrite'' switch.

The ``Overwrite?'' question appears, if you try to overwrite DOS or CP/M
files with PUT, GET, COPY, REN or if you try to DEL a readonly file.

To see the current Force status use STAT.


VERBOSITY <level>
	Set verbosity of CPCFS:
	  -1	no output at all
	  0	only requested output
	  1	+ prompt + error messages
	  2	+ success messages
	  3	+ progress messages
	Default=9.

Note: Verbosity level > 9 are for debugging purposes and require ANSI.SYS!

Example:
	VERBOSITY 0	may be sensible in batch processing



PAGE <lines>
	If you are using the internal pager (i.e. the environment variable
	PAGER is not set), this command sets the number of lines the pager
	should display per screen.

See also:
	variables (PAGER)

CPCFS has an internal pager for commands like DUMP, TYPE, and so on.
With the PAGE command you can set the number of lines of your screen
(the default is 25). If you set PAGE 0, you bypass the internal pager
and things are displayed without stops.



FILENAMES
---------
DOS filenames: <drive>:<path>\<root>.<extension>
	* and ?, the normal DOS wildcards, are possible in <root>
	and <extension>.

CP/M filenames: <userarea>:<root>.<extension>
Wildcards:
	*		any sequence of characters
	?		a single character
	[a-z123]	a set of characters
	[^0-9]		a negative set

Note:	* may appear as user number => all users

Example: Files = {ABC.1, ABC.2, ABC.X, X.ABC, 1:USER.ONE}

	*:*.*		matches all five files
	*.*		matches ABC.1, ABC.2, ABC.X, X.ABC
	*.?		matches ABC.1, ABC.2 ABC.X
	*.[0-9] 	matches ABC.1 ABC.2
	[ab]*.[^0-9]	matches ABC.X
	1:*.*		matches 1:USER.ONE
	1:		sometimes like 1:*.*


EDITING
-------
The following keystrokes are possible while editing a commandline:
	* Curser-Left, -Right
	  Ins, Del, <--
	  Home, End		have the obvious meaning
	* Cursor-Up, -Down	walk thru the history list
	* Ctrl-Home, -End	delete to start/end of line
	* Ctrl-Z		leave CPCFS
	* ESC			delete commandline

The traditonal EMACS contol codes are also possible (^B, ^F, ^V, ^D, ^H,
^A, ^E, ^P, ^N, ^K, ^U).


VALUES & PERCENT EXPANSION
--------------------------
Numbers:	in C syntax, i.e. decimal, octal with leading "0",
		hexadecimal with leading "0x".
		Example: USER 15 = USER 017 = USER 0xF

Strings:	Surrounded by `"'
		Example: ECHO "Hello World"

See also:
	percent

Percent expansions can be used anywhere in strings. They are replaced by
some runtime dependend values:

	%u  current user area
	%i  filename of image			%I  including full path
	%f  free space in percent		%F  in blocks
	%a  allocated space in percent		%A  in blocks
	%c  current working directory of DOS
	%v  current version			%V  plus compilation info

	%%  the percent sign (%)
	%_  an explicit space
	%#  the hash character (#)
	%e  the escape character
	%q  the quote character (")
	%s  the semicolon character (;)

Some expansions show `#', if there is no image loaded!

Used in commands:
	comment		echo	prompt



FILES
-----
CPCFS.CFG
	The commands in this file are executed every time CPCFS starts in
	interactive mode. You can set the PROMPT here or open an often
	used image or ...

	CPCFS looks for it at first in the current directory and then in the
	directory where CPCFS.EXE resides.
	If the environment variable CPCFSHOME is set, then CPCFS looks here.

*.DSK
	This is the default extension for imagfiles

*.CPM
	This is the default extension for CP/M tracks saved by GETCPM.BAS
	and needed by SYSGEN.

SEE ALSO
--------
GETCPM.BAS, a Locomotive BASIC program to copy CP/M tracks off a
diskette and save them to a file. Simply type it in your *original* CPC
(you can leave out REMarks and PRINTs) and run it on a CP/M system disk.
It creates a file, that you have to transfer in some way to DOS (read
the CPCEmu documentation for various ways, how to arrange it). Finally
use CPCFS' SYSGEN command to create a diskimage with CP/M.

DROPTAG.BAT, a batch file replacing DROPTAG.EXE of the former distribution.

RELATED WORKS
-------------
CPCEmu
	(C) Marco Vieth (ali@uni-paderborn.de)
	Current version:    1.3b
	Available on:       ftp://oak.oakland.edu/Simtel/msdos/emulator
			    or any other Simtel site

CPE
	(C) Bernd Schmidt (crux@pool.informatik.rwth-aachen.de)
	Current Version:    5.0
	Available on:       ftp://oak.oakland.edu/Simtel/msdos/emulator
			    or any other Simtel site

comp.sys.amstrad.8bit
	A usenet newsgroup for discussing CPC related topics

http://arachnid.cm.cf.ac.uk/User/K.E.W.Thacker/Amstrad
	A WWW page with a lot of CPC stuff.

ftp://ftp.ibp.fr/pub/amstrad/amstrad.faq
ftp://rtfm.mit.edu/pub/usenet/comp.sys.amstrad.8bit
	The Amstrad FAQ


BUGS
----
The following inconsistencies are intentional:

	* weird formats (with interleave or copy protection) are not possible
	* sparse files are not possible	(sometimes created by CP/M programs)
	* wrong setting of environment variables can cause funny errors
	* error messages can be confusing if your DOS disk becomes full
	* your image file must not be readonly


LEGAL STUFF
-----------
CPCFS - CPCEmu Filessystem Maintenance, Version 0.85

Copyright (c) 1997-2016, Derik van Zuetphen
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Please send bug reports to
	dz@426.ch


Trademarks:
	"CPC", "Amsdos" is from Amstrad
	"CP/M" is from Digital Research (now Novell)
	"Borland C" is from Borland
	"ACTlib 1.7" is public domain and written by Marc Stern


AUTHOR
------
	Derik van Zuetphen

	email:  dz@426.ch
	www:    http://www.426.ch

	The latest version of CPCFS and recent patches can be found in my
	Github repository on https://github.com/derikz/cpcfs