Command Reference 1.2
There is online help available for a few commands in console mode, but it is far from comprehensive. The Boot Scriptor Command Reference, however, explains in detail the use and function of every command understood in console mode and in scripts.
 
Table of Contents
 
  1. Parameter Types
    1. Keywords
    2. Filenames and Paths
    3. Numbers
  2. Syntax Definitions
  3. Command List
 
Parameter Types
Certain types of parameters are understood in the same way by all commands. In order to use Boot Scriptor 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 of they can be in upper, lower, or mixed case.

Examples:

  blink OFF Disable blinking text.
  reboot cold Execute a cold reboot.
  about MoRe Display exented program information.
 
Filenames and Paths
Filenames and paths are taken as relative to 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. Boot Scriptor converts all backward slashes to the forward variety internally. The filesystem only covers the CD-ROM drive that the computer was booted from, so you cannot specify files or paths that reside on another drive or device. Swapping CD's is not supported.

Examples:

  type txtfiles/somefile.txt Relative to the current directory.
  chain \images\sector.bin Relative to the root directory.
  isolinux linux\kernel.bin Invalid (Boot Scriptor does not translate parameters to the isolinux command).
 
Numbers
Numbers can be typed in either decimal or hexadecimal format. Unless a command's documentation specifically states one form must be used, you can freely choose whichever form you want. Hexadecimal numbers begin with 0x, and the digits A~F can be typed in upper or lower case. Be mindful of the number format when typing commands; some commands that you would normally expect to take arguments in hex by default will actually take either decimal or hex parameters. For instance, typing "chain somefile 1000" is not the same as "chain somefile 0x1000".

Examples:

  color 0xF0 Sets color to white on black.
  color 10 Sets color to brightgreen on black.
 
Syntax Definitions
Documentation for each command begins with a blue bar with white text that defines the syntax for using the command. If a command has multiple syntaxes, then more than one blue syntax bar 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.
 
Command List
This is a comprehensive list of all the commands Boot Scriptor recognizes. Some commands may only be available in console or script mode exclusively. If you see the word console in the title bar of a command, then it is available in console mode. If you see the word script in the title bar of a command, then it available to be used in scripts. If both words are present, then you can use the command in both console and script modes. Using a script-only command in console mode results in an "unknown command entered" error. Certain commands may function differently in scripts than they do in console mode. If that is the case, it will specifically state the differences in the documentation for that command.
 
 
 

About

[ basic.bsm ]

- console -

 - script -

about [more]
The about command displays information on the current version of Boot Scriptor.

If the more keyword is used, additional information is displayed.
 

Blink

[ basic.bsm ]

- console -

 - script -

blink <on/off>
The blink command enables or disables blinking text. When Boot Scriptor is started, blinking text is enabled by default.

Turning blinking text on enables the blink attribute bit for displayed characters. Turning blinking text off allows high-intensity background colors to be used.
 

Boot

[ boot.bsm ]

- console -

 - script -

boot [test] <drive>
The boot command attempts to boot from a local disk drive. The drive can also optionally be forced to pass a test before booting will be attempted.

If the test parameter is omitted, then Boot Scriptor will attempt to boot the drive unconditionally. If the test parameter is a, b, or c, then the drive must pass anywhere from one to three checks before booting will be attempted. See the table below for information on what checks are performed on each test. If all checks are successful, then the test is passed. If at least one of the checks is unsuccessful, then the test is failed. Test a is good for checking floppy disks, as it only checks for a valid boot sector. Tests b and c are good for checking whether or not a hard disk is bootable; however, test c should be the usual choice as it is more thorough.

Checks Tests a b c
Check for a boot signature on the Master Boot Record. ● ● ●
Check for a bootable partition in the Master Boot Record's partition table.   ● ●
Check for a boot signature on the first bootable partition's boot sector.     ●

The drive specified must be a valid BIOS drive number. Typical values are 0 (Floppy A), 0x80 (first hard disk), and 0x81 (second hard disk).

If the device cannot be booted due to a disk read error, an error message will be displayed on the screen. If the device can't be booted due to a failed test, then either a message will be displayed on the screen (console mode) or no action will be taken (script mode).
 

Call

[ script.bsm ]

   - script -

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

[ basic.bsm ]

- console -

 - script -

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

[ boot.bsm ]

- console -

 - script -

chain <filename> [address]

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 (i.e. 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 (i.e. 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, Boot Scriptor 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".
 

Check

[ boot.bsm ]

- console -

 - script -

check <test> <drive>

(console mode)

check <test> <drive> <p/f> [action]

(script mode)

The check command checks to see if a drive seems bootable and displays or acts upon the result. There are three levels of testing available.

See the table below for information on what checks are performed on each test. If all checks are successful, then the test is passed. If at least one of the checks is unsuccessful, then the test is failed. Test a is good for checking floppy disks, as it only checks for a valid boot sector. Tests b and c are good for checking whether or not a hard disk is bootable; however, test c should be the usual choice as it is more thorough.

Checks Tests a b c
Check for a boot signature on the Master Boot Record. ● ● ●
Check for a bootable partition in the Master Boot Record's partition table.   ● ●
Check for a boot signature on the first bootable partition's boot sector.     ●

The drive specified must be a valid BIOS drive number. Typical values are 0 (Floppy A), 0x80 (first hard disk), and 0x81 (second hard disk).

If this command is executed while in console mode, the result of the test is displayed on the screen.

If the command is executed while in script mode, then the action parameter specifies an action to be taken based on the result of the test. If the condition keyword is p, then action will be executed if all checks in the test were passed. If condition keyword is f, then action will be executed if at least one of the checks in the test have failed.

The action parameter can be any Boot Scriptor command and it's parameters.
 

Clear

[ basic.bsm ]

- console -

 - script -

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 color declaration.
 

Color

[ basic.bsm ]

- console -

 - script -

color [h/t/o] <value>
The color command sets various color attributes used by Boot Scriptor.

If keyword h is specified, the color Boot Scriptor uses to highlight text is changed to value, where value is an 8-bit integer where the upper 4 bits represent the background color (and blink attribute, if blinking is enabled), and the lower 4 bits represent the text color.

If keyword t is specified (or if the [h/t/o] parameter is omitted), the default text color is changed to value. The value parameter has the same format as when specifying the highlight color.

If keyword o is specified, value must be an 8-bit DAC register address to be used for the display's overscan color. If neither keyword t nor o is specified, then the operation defaults to setting the text color.

All numbers can be in decimal or hexadecimal form.
 

Cls

[ basic.bsm ]

- console -

 - script -

cls
This is a synonym for the clear command.
 

Dir

[ basic.bsm ]

- console -

 - script -

dir [d/f]
The dir command lists the contents of 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.

In the script debugger, file times are always rounded to an even number of seconds.
 

Diskemu

[ diskemu.bsm ]

- console -

 - script -

diskemu <filename> [segment]
The diskemu command emulates a floppy disk image using Diskemu, and attempts to boot from it. The optional segment parameter specifies the install segment of the Diskemu emulator program.

Diskemu is an alternative to Memdisk. The main difference between the two is: 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 is read-only. Finally, Memdisk has the capability of booting hard disk images, while Diskemu is limited to floppy disk images.

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.
 

End

[ script.bsm ]

   - script -

end
The end command terminates script processing. Use this command in a script to return to console mode.
 

Getkey

[ script.bsm ]

   - script -

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 can specify a timeout of zero seconds to execute the default action immediately, although the logic behind such use is questionable) 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.

Note to Diskemu users: Diskemu allows you to specify a default keycode to be returned if no key is pressed when a timeout is reached. You can accomplish the same thing here by using setkey as the default action.
 
 

Goto

[ script.bsm ]

   - script -

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

[ basic.bsm ]

- console -

 - script -

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 color") you can receive detailed information on how to use a particular command.
 

Hotkey

[ hotkey.bsm ]

- console -

 - script -

hotkey <action/activate/description/flags/keycode/testkey> [extra parameters]
The hotkey command is broken down into several sub-commands, each indicated by a keyword following the hotkey command name and each having different syntax (defined below). A user-defined hotkey is created by setting its attributes through multiple hotkey commands, and then activated by issuing the "hotkey activate" command.

Here is an example of how to create a user-defined hotkey that will automatically switch to the /bscript directory when a user presses Ctrl-H:

/> hotkey name Ctrl-H
/> hotkey description Switch to the /bscript directory.
/> hotkey keycode 0x0008
/> hotkey flags 4
/> hotkey action cd /bscript
/> hotkey activate

Note that you can define as many hotkeys as you want simply by reloading the hotkey.bsm module for each additional key you want to define.

hotkey action [action]
The action subcommand assigns a one-line command to be executed when the user-defined hotkey is pressed. The command can be any console command. If no action is specified, then any action defined by a previous "hotkey action" command is erased.

hotkey activate
The activate subcommand creates a user-defined hotkey based on the attributes defined by previous calls to the hotkey command, and then disables further use of the hotkey command. This should be called last, after setting up the key by using the other subcommands of hotkey.

Although name, description and flags are optional, you must have defined an action and keycode before calling activate. If either an action or keycode have not been defined when activate is called, an error will be generated.

hotkey description [description]
The description subcommand assigns a description to the hotkey that will be displayed when a user types "list keys". The description can be no longer than 54 characters. Setting a description is not necessary, and the description is not even used unless a name is defined (see below). If no description is specified, then any description defined by a previous "hotkey description" command is erased.

hotkey flags [eithershift] [tflags] [mflags]
The flags subcommand sets the flags used to determine the ctrl/alt/shift key state that is required to execute the key's action. If no parameters are given, then any flags set by a previous "hotkey flags" command are erased.

If the eithershift keyword is present, then the key will be activated as long as one of the two shift keys are pressed. It won't matter whether it's the right or left shift key used to activate the hotkey.

The tflags parameter sets the test flags. If a test flag is set, then the hotkey will be executed only if the corresponding modifier key is pressed. If a test flag is not set, then the hotkey will be executed only if the corresponding modifier key is not pressed. See below for the flag definitions. If tflags are not specified, they default to 0 (no flags set).

The mflags parameter sets the mask flags. If a mask flag is set, then the corresponding tflag comparison is enabled. If a mask flag is not set, then the state of the corresponding modifier key does not matter when determining whether or not to execute the hotkey's action. If mflags are not specified, they default to 0xF (all flags set). In order to set the mflags, you must also set the tflags in the same hotkey command.
 

tflags and mflags individual flag definitions
Modifier key Bit position Decimal value
Right-shift 0 1
Left-shift 1 2
Control 2 4
Alt 3 8

Note: To calculate tflags or mflags, just add up the decimal value of the flags you want set.

hotkey keycode [keycode]
The keycode subcommand sets the keycode of the key that will activate the hotkey. If you are unsure what the keycode is for a particular key, you can use the testkey subcommand, defined below. If no keycode is specified, then any keycode defined by a previous "hotkey keycode" command is erased.

hotkey name [name]
The name subcommand assigns a name to the hotkey that will be displayed when a user types "list keys". The name can be no longer than 18 characters. Setting a name is not necessary; if you don't supply one the hotkey will not be in the list of keys. If no name is specified, then any name defined by a previous "hotkey name" command is erased.

hotkey testkey
The testkey subcommand is used to get the keycode and tflags for a key that you want to assign an action to. Just type "hotkey testkey" and then press whatever key it is that you want to define, and the corresponding keycode and flags will be displayed.
 

Isolinux

[ isolinux.bsm ]

- console -

 - script -

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 Boot Scriptor will not parse and translate backward slashes to the required format.
 

List

[ basic.bsm ]

- console -

 - script -

list <commands/keys/modules>
The list command will display all the commands, keys, or modules that are currently installed.
 

Loadmodule

[ extend.bsm ]

- console -

 - script -

loadmodule <module>
The loadmodule command is used to load a Boot Scriptor Module (BSM). The module parameter must specify a valid BSM file.
 

Ls

[ basic.bsm ]

- console -

 - script -

ls [d/f]
This is a synonym for the dir command.
 

Man

[ basic.bsm ]

- console -

 - script -

man <command>
This is a synonym for the help command, the only difference being you must specify a command to receive information on.
 

Memdisk

[ isolinux.bsm ]

- console -

 - script -

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 the /bscript/modules/isolinux directory.

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.
 

Onkey

[ script.bsm ]

   - script -

onkey <key> <action>
The onkey command checks the last key the user pressed, and if it matches key, then an action is performed. If the keys do not match, then no action is performed and script processing continues on the next line.

key can be any single character (except a semicolon), or a 16-bit hexadecimal keycode (must be hex). It can also be any of the following mnemonics:
F1, F2,...,F11, F12 Function Keys
AF1, AF2,...,AF11, AF12 Alt-Function Keys
CF1, CF2,...,CF11, CF12 Ctrl-Function Keys
SF1, SF2,...,SF11, SF12 Shift-Function Keys
back Backspace
esc Escape
enter Enter
del Delete
ins Insert
home Home
end End
pgup Page-up
pgdn Page-down
up Up-arrow
down Down-arrow
left Left-arrow
right Right-arrow
semi Semicolon
space Space
tab Tab
 

Part

[ rpm.bsm ]

- console -

 - script -

part
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, Boot Scriptor shuts down and then executes RPM. Boot Scriptor must be restarted after RPM exits (it cannot return to where it left off). The file part.exe must be present in the /bscript/modules 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 Boot Scriptor and Ranish Partition Manager at your own risk. The creators of Boot Scriptor and Ranish Partition Manager are not responsible for any harm caused by their respective programs.
 

Print

[ script.bsm ]

- console -

 - script -

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 if you use \t in a center or right aligned message it will throw off the formatting. Therefore the \t escape sequence should really only be used in left aligned messages.
\\ Backslash
\" Double-quote character
\n Newline
\t Tab (see tab command)
\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. ## must be two hex digits.
\cxx Change to the default text color (see the color command)
\cXX Change to the text highlight color (see the highlight command)
 

Quit

[ basic.bsm ]

- console -

 - script -

quit
The quit command is used to exit the Boot Scriptor script debugger (i.e., DOS/Windows version of Boot Scriptor).
 

Reboot

[ boot.bsm ]

- console -

 - script -

reboot [cold/warm]
The reboot command is used to reboot the computer.

If the cold or warm parameter is supplied, then a cold or warm reboot is executed, respectively. If no parameter is supplied, a warm reboot is executed.
 

Restart

[ basic.bsm ]

- console -

 - script -

restart [noscript]
The restart command restarts Boot Scriptor.

If the noscript keyword is used, then no startup scripts will be run upon restart.
 

Return

[ script.bsm ]

 

 - script -

return [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.

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.
 

Rpm

[ rpm.bsm ]

- console -

 - script -

rpm
This is a synonym for the part command.
 

Script

[ script.bsm ]

- console -

 - script -

script <filename>
The script command instructs Boot Scriptor 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, Boot Scriptor 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).
 

Setkey

[ script.bsm ]

- console -

 - script -

setkey <key>
Use the setkey command to simulate a user keypress. After you've set a key using setkey, you can do operations based on that key by using the onkey command.

key must conform to the same usage as in the onkey command.
 

Setpos

[ script.bsm ]

   - script -

setpos <x/xpos> <y/ypos>
The setpos command positions the cursor at the specified coordinates.

xpos must be an integer between 1 and 80 (inclusive), and ypos must be an integer between 1 and 25 (inclusive). Numbers can be typed in decimal or hexadecimal form.

If the keyword x or y is specified instead of a numerical position, then the current x or y position is left unchanged.
 

Show

[ basic.bsm ]

- console -

 - script -

show console

show image <filename.bmp>

show image <filename.bsi> [filename.bmp]
The show command controls what the user sees while Boot Scriptor 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 Boot Scriptor 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 Boot Scriptor Image (BSI) 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 BSI image.
 

Tab

[ basic.bsm ]

- console -

 - script -

tab <distance>
The tab command sets the tab distance (for use with the print command). When Boot Scriptor starts up this value is initially set to four.

distance must be less than or equal to 80, and can be in decimal or hexadecimal format.
 

Type

[ basic.bsm ]

- console -

 - script -

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

[ script.bsm ]

   - script -

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 hexadecimal format.