cpcfs.hlp

~nothing~
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

~commands~
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

~options~
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

~variables~
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.

~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

~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:*.*

~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)

~about~
CPCFS - CPCEmu Filessystem Maintenance, Version 0.85 (Feb. 96-Jan 98)

This program is Freeware and copyright by Derik van Zuetphen.
You may distribute the whole package (zip-file), with or without an
appropriate charge. You may not distribute changed versions.

** This software is provided "as-is". No warranties of any kind are made! **

Please send bug reports to
	derik@t-online.de

~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

~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).

~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

~values~
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

~put~
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

~get~
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

~mput~
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

~mget~
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

~open~
OPEN <file>
	Load an image

~close~
CLOSE
	Close the current image

~new~format~
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
	
~sysgen~
SYSGEN <file>
	Writes the CP/M-System from <file> to current image.

Note: The image must be in system format!

~mode~
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

~dir~
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

~attrib~
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

~era~del~
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~
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:

~copy~
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

~type~
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)

~user~
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)

~force~
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.

~map~
The MAP command will be absent in next versions. See DUMP -M

~dira~
The DIRA command will be absent in next versions. See DUMP -D

~dump~
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
~ldir~
LDIR <dos-filespec>
	Print the current DOS directory.
	Equivalent to !DIR.

Example:
	LDIR *.DSK

See also:
	!

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

Example:
	CD C:\TEMP

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

See also:
	comment		dpb

~echo~
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

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

Example:
	SOURCE MY.CFG

~help~?~
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

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

See also:
	variables (COMSPEC)	ldir	cd

~page~
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)

~verbosity~
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


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

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

See also:
	percent		echo	values

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

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

See also:
	stat	background

~comment~
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

~cls~
CLS
	Clear screen.

~end-of-help~