CapCLI: Variables

Variables are little stores of data, some are implicitly created for you, and some you can create for yourself

To create a variable

var <variable name> <value>

For example, to create the variable MYVAR, with the value “Today is Friday” (the quotes are important if you have spaces).

CapCLI> var MYVAR "Today is Friday"

To display a variable

echo <variable name>

For example;

CapCLI> echo $MYVAR
Today is Friday

To create a variable from data in your current ROM

You can grab chunks of the ROM and it will store the data in the variable as a hexadecimal string

CapCLI> var <aliasname> romdata <start> <size>

For example, to grab four bytes from the ROM at position 0x0C (position 12 holds the kickstart version; you can use hex start/size or decimal numbers)
Note: the start position starts at zero (i.e. the first byte is byte 0).

CapCLI> loadrom "ROMs/TOSEC.Firmware/Kickstart v2.05 r37.350 (1992-04)(Commodore)(A600HD)[!].rom"
CapCLI> var FRED romdata 0x0C 4
CapCLI> echo $FRED
0x0025015E

To take chunks out of a variable: midstring()

var <varname> mid <start> <size> 

For example, reduce the variable FRED to just two bytes starting from position three, this command changes the actual variable
Note: string positions start at 0

CapCLI> var FRED 0x0025012c 
CapCLI> var FRED mid 3 2 
CapCLI> echo $FRED
02

To add/subtract from variables

var <varname> add <value>
var <varname> subtract <value>

These commands will directly affect the variable value, you can change number variables or hex values, if you’re using hex values it will treat it as a four-byte integer, so numbers will wrap round from 0xffffffff to 0x00000000 if you add 1 (and from 0x00000000 to 0xffffffff if you subtract 1), if will also pad the result to four bytes, and if you attempt to use a longer hex number it will only take the first four bytes, e.g. if you add 1 to 0x112233445566 will be taken as 0x11223344 and result in 0x11223345 – and it will do it without any warning, attempting maths on invalid numbers will give unpredictable results.

CapCLI> var FRED 77
CapCLI> var FRED add 0xD
CapCLI> echo $FRED
90
CapCLI> var FRED 0x0025
CapCLI> var FRED subtract 16
CapCLI> echo $FRED
0x00000015

To convert variables

You can convert the representation of variables, by default, all variables are strings, even though some are implicitly numbers or hex strings, you cannot store binary values in a variable unless you store it as the hex representation – so converting between them may lose data!
Using one of these functions on a variable will change the variable

var <varname> stringtohex
CapCLI> var MYVAR "Hello World"
CapCLI> var MYVAR stringtohex
CapCLI> echo $MYVAR
0x48656c6c6f20576f726c64
Note: No end-of-line markers are added (i.e. 0x00 is not added to the string).

var <varname> hextostring
CapCLI> var MYVAR 0x3238205965617273204c61746572
CapCLI> var MYVAR hextostring
CapCLI> echo $MYVAR
28 Years Later
Note: If you have a null byte in the middle of the hex, the string will truncate there.

var <varname> inttohex
CapCLI> var MYVAR 300
CapCLI> var MYVAR inttohex
CapCLI> echo $MYVAR
0x0000012c
Note: The output is always a four-byte hex number (UINT), you can convert a negative number, but it will assume the resulting hex value is positive.

var <varname> hextoint
CapCLI> var MYVAR 0x0ff
CapCLI> var MYVAR hextoint
CapCLI> echo $MYVAR
255
Note: The output is always a positive number (assumes unsigned hex value)