Documentation for each command begins with a line of text that defines the syntax for using the command. If a command has multiple syntaxes, then more than one syntax line will be present.
The syntax begins with the command itself, followed by a parameter list (if the command takes parameters). Parameters enclosed in < > are required, and parameters enclosed in [ ] are optional. Some parameters can be selected from a list of options, separated by slashes. Examples of this are "<warm/cold>" or "[on/off]". When typing these parameters, you select only one of the options. Parameters listed in regular text are keywords; parameters listed in italics are parameter names, and stand for other things such as filenames, numbers, or keywords.
Parameter Types
Certain types of parameters are understood in the same way by all commands. In order to use CD Shell to its fullest extent, you should first understand how it reads keywords, filenames and paths, and numbers.
Keywords
Keywords are typed exactly as they appear in the syntax definition for a command, with the exception that they are not case sensitive. Examples:
about MoRe
Display extended program information.
reboot cold
Execute a cold reboot.
Filenames and Paths
Filenames and paths are taken as relative to the current directory (displayed in the command prompt) unless they begin with a slash character, in which case they are taken as relative to the root directory. Unless specifically mentioned in a command's documentation, directories may be delimited by forward or backward slashes. CD Shell converts all backward slashes to the forward variety internally. The filesystem only covers the CD/DVD drive that the computer was booted from, so you cannot specify files or paths that reside on another drive or device. Swapping discs is not supported.
type files/somefile.txt # Relative to the
current directory.
chain \images\sector.bin # Relative to the root
directory.
Command List
About
C
S
basic.csm
about [more]
The about command displays information on the current version of Boot Scriptor.
If the more keyword is used, additional information is displayed.
Boot
C
S
boot.csm
boot <drive>
The boot command attempts to boot from a local disk drive. The drive parameter must be a valid BIOS disk identifier (eg. 0x00 = first floppy, 0x80 = first hard disk, etc.). You can also use some pre-defined disk identifier shortcuts: $fda, $fdb, $hda, $hdb, $hdc, and $hdd. It is usually good to verify whether or not the drive is bootable (by using the bootCheck function) before executing this command.
Call
S
script.csm
call <label>
The call command is used to call a subroutine in a script. It operates exactly the same as the goto command, except subroutines may return to the line following the call statement by using the return command. Calls can be nested up to 64 levels deep. Note that if you use the script command in a script file, the call stack is reset (you cannot return to the previous script file). If the label you specify is not found, an error will be generated and script processing will end.
Cd
C
S
basic.csm
cd <path>
The cd command changes the current directory. The current directory is used when searching for files that are given as parameters to various commands, such as chain or type. You can always see the current directory when in console mode by observing the command prompt.
The path parameter follows the same format as a filename parameter, except it specifies a directory rather than a file.
To change to the previous directory, type "cd .."
chain
C
S
boot.csm
chain <filename>
chain <filename> <address> [start]
The chain command is used to chain-load a boot sector or other such boot image file. One of the more common uses of this command is to load a Windows CD-ROM boot sector image file to make a bootable Windows installation disk. This command is not for booting images that require hardware emulation (eg. floppy or hard disk images).
The filename parameter specifies the boot image file to chain-load. The image file size is limited to 64kb.
The address parameter is a 32-bit, absolute physical memory address. It is not in segment:offset format. It specifies the address to load the image file, and must specify a load location in the lower 640kb of RAM. The boot sector can be loaded anywhere in the lower 640k of memory, but care should be taken not to copy into sensitive memory areas (eg. BIOS code or data, video memory, memory-mapped ports, etc). The address can be specified in decimal if you really want to, but most people will type it in hexadecimal format. If no address is specified, it defaults to 0x7C00.
The start parameter specifies a 32-bit offset relative to address that will be used as the starting point for the chain-loaded program. The offset specified must reside inside the loaded file. If start is not specified, CD Shell will jump into the program at offset zero from the load address. The start parameter cannot be specified without the address parameter, so if you need to load a program at offset 0x7C00 but skip the first 0x100 bytes, you will have to type "chain filename 0x7C00 0x100".
Clear
C
S
basic.csm
clear
The clear command clears the display and returns the cursor to the upper left-hand corner of the screen. It's useful to use this command following a change in the default text background color.
Cls
C
S
basic.csm
cls
The cls command clears the display and returns the cursor to the upper left-hand corner of the screen (it does the same thing as the clear command).
Dir
C
S
basic.csm
dir [d/f]
The dir command lists the files and folders contained in the current directory.
You can limit the command to displaying only files or sub-directories by using the d and f parameters. The d parameter causes only directories to be displayed, and the f parameter causes only files to be displayed.
Side note: In the script debugger, file times are always rounded to an even number of seconds.
Diskemu
C
S
diskemu.csm
diskemu <filename> [noboot] [segment]
The diskemu command is used to emulate floppy disk images using diskemu. The default operation is to emulate the floppy disk and boot from it.
If the noboot keyword is used, the emulated disk will not be booted. After issuing such a command, diskemu can be invoked a second time to allow emulation of two different floppy disks at once. Diskemu will always use the last disk image it was given as floppy disk A.
The optional segment parameter specifies the install segment of the diskemu emulator program.
Diskemu is an alternative to memdisk. The main differences are as follows:
memdisk caches the entire disk image in memory, and thus responds faster to disk I/O operations. Diskemu reads the disk image from the CD/DVD as the contents are requested, which requires more time.
memdisk also allows writing to the disk image exactly as if it was a real floppy disk (although the whatever is written will be lost when the machine is rebooted). Diskemu emulated floppies are read-only.
memdisk has the capability of booting hard disk images, while diskemu is limited to floppy disk images.
Diskemu does not require the emulated floppy disk to be booted.
Diskemu is able to emulate two floppy disks at once.
Although memdisk has clear advantages, there are some situations where it may not cooperate with certain programs. If you're having trouble getting your disk image to work with memdisk, try using diskemu and see if that helps.
Else
C
S
basic.csm
else <command>
The else command will execute its parameter if the result of the previous if command was false (zero). You can execute multiple else commands following an if command.
End
S
script.csm
end
The end command terminates script processing. Use this command in a script to return to the command console.
Exit
C
S
basic.csm
exit
The exit command is used to quit the CD Shell script debugger (ie. DOS/Windows version of CD Shell).
Font
C
S
basic.csm
font <default/filename>
The font command can be used to load a VGA text font for international language support or alternative character styles. Font files are 4096 bytes (they must specify all 256 characters at 8x16 resolution). You can find some on the internet, for example if you search Google for the archive fntcol16.zip by Joseph Gil. (the valid files in his collection end with the extension .f16)
If the default keyword is used, the original text font will be restored.
Getkey
S
script.csm
getkey [timeout] [action]
The getkey command waits for the user to press a key, and then stores that key for later processing.
You can specify a timeout value (in seconds) and a default action (any console or script command) to take if no key is pressed in the specified amount of time. You must specify a timeout value in order to use the default action capability. You do not have to specify a default action when using the timeout. Timeout can be expressed in decimal or hexadecimal, and must be a 16-bit integer.
Goto
S
script.csm
goto <label>
Use the goto command to jump to another line in a script file.
If the label you specify is not found, an error will be generated and script processing will end. Do not type the trailing colon after the label name when using this command.
Help
C
S
basic.csm
help [command]
The help command displays online help for using console commands.
By supplying a command name as the parameter (such as "help boot" or "help diskemu") you can receive detailed information on how to use a particular command.
If
C
S
basic.csm
if <expression>
The if command takes an expression as its only parameter. The then command takes a command as its parameter, and executes it if the result of the last if command was true (nonzero). The else command will execute its parameter if the result of the previous if command was false (zero). You can execute multiple then or else commands following an if command, but you can't nest if commands. Here's an example demonstrating how to use the commands.
if $textColor == 14 then print "The text color is yellow.\n" then print "Aren't you happy?" else print "The text color is not yellow.\n" else print "But that's ok."
if $vesa; then goto graphicMenu; else goto textMenu
isolinux
C
S
isolinux.csm
isolinux [command]
The isolinux command is used to pass a line of text to isolinux for processing. The text will be handled by isolinux exactly as if it was typed at the isolinux 'boot:' prompt.
If you don't type a command, then an empty string is passed to isolinux. See the Isolinux documentation for information on specific commands.
This function does not return. Also, be careful when typing paths to be sent to isolinux, because it only understands Unix-style paths (forward slashes), and CD Shell will not parse and translate backward slashes to the required format.
Keymap
C
S
basic.csm
keymap <default/filename>
The keymap command is used to load an alternative keyboard map from a file. This can be used to allow CD Shell to work with keyboards which use non-default layouts and/or character sets.
If the default keyword is used, the standard keymap will be restored.
List
C
S
basic.csm
list <commands/functions/keys/modules>
The list command will display all the commands, functions, keys, or modules that are currently available.
Loadmodule
C
S
extend.csm
loadmodule <module>
The loadmodule command is used to load a CD Shell Module (CSM). The module parameter must specify a valid CSM file.
This is a synonym for the help command, the only difference being you must specify a command to receive information on.
memdisk
C
S
isolinux.csm
memdisk <filename>
The memdisk command attempts to boot from a floppy or hard disk image file, by calling on Memdisk to emulate the hardware. The memdisk program file must be present in either the /isolinux or /boot/modules/isolinux directories.
The filename parameter specifies a floppy or hard disk image file to boot from (relative to the current directory). See the memdisk documentation for information about the types of files accepted by memdisk.
If you experience problems when booting a floppy disk using memdisk, you can try the alternative command diskemu.
memtest
C
S
memtest.csm
memtest
The memtest command loads and executes the program Memtest86+, a memory diagnostic tool. The memtest.bin program file must be present in the /boot/modules/memtest folder.
Mgetkey
S
script.csm
mgetkey [timeout] [action]
The mgetkey command waits for the user to press a key, and then stores that key for later processing.
You can specify a timeout value (in seconds) and a default action (any console or script command) to take if no key is pressed in the specified amount of time. You must specify a timeout value in order to use the default action capability. You do not have to specify a default action when using the timeout. Timeout can be expressed in decimal or hexadecimal, and must be a 16-bit integer.
This command differs from the getkey command in that it will terminate if a mouse event occurrs. If the mouse was moved, or any mouse buttons were pressed or released, the command will terminate, and the value of $lastKey will be set to key[mouse].
The part command loads and executes Ranish Partition Manager (RPM). This is a utility that allows you to work with partitions on your local hard drives. When this command is executed, CD Shell shuts down and then executes RPM. CD Shell must be restarted after RPM exits (it cannot return to where it left off). The file part.exe must be present in the /boot/modules/rpm folder for this command to function.
Disclaimer: Ranish Partition Manager (RPM) is a very powerful utility. It has the capability to wipe out all your data, so care should be taken to make sure you know what you're doing before you start using the program. It is also a beta program so there may be errors that cause inadvertent effects. You use CD Shell and Ranish Partition Manager at your own risk. The creators of CD Shell and Ranish Partition Manager are not responsible for any harm caused by their respective programs.
Print
C
S
script.csm
print [l/c/r] <message>
The print command will display a user specified message out on the screen.
The l, c, and r keywords specify left, center, or right justification respectively. The message is aligned to the left by default. If left justification is used, the message will be displayed beginning at the current cursor position. If center or right justification is used, the current cursor position is adjusted as necessary to align the text before the message is displayed. If the message contains lines longer than 80 characters, then it will be displayed in 80-character segments until the remainder is small enough to justify.
The message must be delimited by quotes ("). Any of the escape sequences listed below can be used in the message, however \t may only be used in center or right aligned messages.
\\
Backslash
\"
Double-quote character
\n
Newline
\t
Tab (see tabSize variable)
\ac
Change to center alignment and begin a new line.
\al
Change to left alignment and begin a new line.
\ar
Change to right alignment and begin a new line.
\c(#)
Change color. The color in parenthesis can be decimal or hex.
\c##
Change color. ## must be two hex digits.
\cxx
Change to the default text color.
\cXX
Change to the text highlight color.
Reboot
C
S
boot.csm
reboot [warm/cold]
The reboot command is used to reboot the computer.
If the warm or cold parameter is supplied, then a warm or cold reboot is executed, respectively. If no parameter is supplied, a warm reboot is executed.
Restart
C
S
basic.csm
restart [noscript]
The restart command restarts CD Shell.
If the noscript keyword is used, then the startup script (cdshell.ini) will be run upon restart.
Return
S
script.csm
return [here | never]
The return command returns from a called subroutine. This command must come after a call command, otherwise an error will be generated and script processing will be terminated.
The here keyword instructs CD Shell to return to this line (the line "return here" appears on) on the next subsequent return. Think of it as half of a call command, if you were to break a call into "return here" and "goto label".
If the never keyword is specified, then the return vector is popped off the call stack, and script processing resumes at the following line. Use the never keyword if you won't be returning from a procedure, or if you want to return to a higher-level procedure.
The script command instructs CD Shell to begin taking commands from a script file. See the section on script files for information about them.
The filename parameter specifies the script file to run. If this command is executed from within a script file and filename is found, then the current script file is changed to the new file and the call stack is reset. When the new script file is finished running, CD Shell returns to console mode (it does not return to the previous script file). If a script subroutine executes this command successfully, it can never return to it's caller (because the call stack was reset).
Set
C
S
macro.csm
set <variable> = ["string"]
set <variable> = [expression]
You can set the value of a variable using the set command. If the variable doesn't exist when you set it, then it will be created. Valid variable names contain only the characters a-z, A-Z, 0-9, and _.
There are two forms of the set command. The first form sets the variable to a string. The string must be delimited by quotes, but you can use the backslash to escape a character if needed.
Examples:
set variable_one = "Boot Scriptor is now" set variable_two = "called \"CD Shell\"."
The second form basically evaluates a mathmatical expression and then stores the result into the variable. All variables are represented internally as strings, so this essentially just calculates the result of the expression and then converts the number into a string.
Example:
set myVar = 1 + 2
See the Variable Reference for more detailed information concerning the set command and the use of variables.
Show
C
S
basic.csm
show console
show image <filename.bmp>
show image <filename.csi> [filename.bmp]
The show command controls what the user sees while CD Shell is running. Although the console is always active in the background, you can use the show command to specify an image to be displayed onscreen for the user to look at.
The command "show console" will switch the screen back into text mode and display the CD Shell console. This is used when you are done displaying your graphic and want to return to text mode.
The command "show image" will switch the screen into graphics mode and display an image. While the image is displayed, any output that would normally go to the console is accounted for, but cannot be seen. See the section of documentation related to displaying images for more information on the types of images Boot Scriptor can display.
The image that is shown is specified by the filename parameter. If the file is in CD Shell Image (CSI) format, a second image file, in BMP format, may be specified. This alternative image will be displayed in the event that the machine is not capable of displaying the high-resolution CSI image.
Then
C
S
basic.csm
then <command>
The then command takes a command as its parameter, and executes it if the result of the last if command was true (nonzero). You can execute multiple then commands following an if command.
Type
C
S
basic.csm
type <filename>
The type command displays the contents of a text file on the screen, pausing after each screen of data.
The filename parameter specifies the file to display. Lines longer than 255 characters are broken down into 255-character segments.
Wait
C
S
basic.csm
wait [t] [time]
The wait command pauses script processing for time seconds, or if keyword t is specified, for time timer-ticks. There are roughly 18.2 ticks per second.
time must be a 16-bit integer, specified in decimal or hex.
