71 - Grubutils - menuset, wenv, bios, grub4dos utilities and batch files

Hits
The GrubUtils utilites can be downloaded from Chenalls site here (this includes wenv, chkpci and other utilities). See the bottom of this page for a recent version (includes 2014 version of chkpci).

There are some interesting utilities that can be called or executed from grub4dos. The documentation is difficult to find and is usually in Chinese. Here are some notes which may be helpful.

When running an external grub4dos batch file or utility executable, you need to copy the file to your boot drive and make sure that the path is specified correctly in the menu.lst file, e.g.

/menuset 0 0 0 0 0 0 10 50 5 29 35

will run the file menuset which must exist on the root of the boot drive. menuset is contained in the grubutils package.

Note: The default command path for grub4dos is the current path (set by the root command) and the /boot/grub folder - it is recommended to place all your utilities in /boot/grub on your boot drive so that grub4dos can find them without needing to set the root or define a full path.

menuset 0 0 0 0 0 0 10 50 5 29 35

will run the file menuset which must exist in the /boot/grub folder or in the current root folder (as shown by the ls command).

The alternative is to path each command - e.g. use /bin/wenv instead of just wenv and place the wenv file at /bin.

Grub4dos Batch files

Max no lines = 2048 in a batch file, Max. no. labels in a batch file =128, file must start with !BAT on first line.

Grub4dos can execute a batch file (usually given a .g4b file extension, but sometime it has a .bat extension or no extension - whereas a grub4dos executable file has a .g4e extension or no extension). The grub4dos batch file must begin with !BAT. The syntax to use in the batch file is similar to that in a menu.lst file but not quite the same. For instance when using two variables together, you must use three % signs in a batch file because any two consecutive % signs will be treated as a single % sign in a batch file:

test.bat file contents:
!BAT
set a=Fred is a
set b=GENIOUS!
echo %a%%%b%
echo Fred got 100%% in his test!

in a grub4dos commandline shell, type /test.bat
Fred is a GENIOUS!
Fred got 100% in his test!

Note that in a batch file we cannot use %a%%b% - we must add an extra % symbol and use %a%%%b%, but in a menu.lst file, echo %a%%b% will work and you don't need the extra % sign!

If want to add a SPACE before a value using set then use double-quotes:
set "C= fred"
or use double-quotes if it is possible that a variable's value (A in this case) might contain leading spaces (in batch file %%=% so we must use three % signs - %A%%%B%):
set "C=%A%%%B%"


tip: If you place all utility and batch files in the /boot/grub folder then grub4dos will find them without needing to specify a path.

tip: If you use debug 3 then you can single step a batch file (on later versions of grub4dos use debug <batchfile> <args> )

Also, if you call a grub4dos utility a lot in a batch file (for instance, in a loop or subroutine), then load it into memory first using the command insmod - e.g.
insmod /utils/wenv
wenv calc bs=%bs%-%bc2b%
will load wenv into memory so that whenever it is called later (with no path specified) it will run from memory instead of being loaded from the disk each time. Thus using insmod at the start of your batch file to load any utilities into memory will greatly improve the speed of execution! Insmod can also be called from within a menu.lst file and this will increase the speed of execution of grub4dos menus if you call a grub4dos utility within the menu.lst file, as well as any batch files you call afterwards. Use delmod <filename) to unload a file or :

::echo Checking if this batch file is loaded into memory - if not load it for faster execution
delmod -l %~nx0 || insmod %0

#Note: can only use filenames up to 11 characters (including the dot - i.e. up to 8.2 not 8.3) with insmod.

You can also call internal Function calls in a batch file using call Fn.x where x is a number and can be followed by one or more parameters - e.g.:

call Fn.0 0 "Hello" - will print Hello to the console

Here is a batch file to get lines from a text file, one at a time (redirecting bold blue lines will give a perfect copy of the file):

!BAT
insmod %0 > nul
set n=0
set l=0
:LOOP
cat --locate=\x0d\x0a --number=1 --skip=%n% /menu.lst > nul
if "%?%"=="0x0" goto :EOF
set /a l=%?% - %n% > nul
::echo -e \nFound CR at start %n% length %l%
if %l%>=1 cat --skip=%n% --length=%l% /menu.lst
echo
set /a n=%n% + %l% + 2 > nul
goto :LOOP

Tip: to get more lines on the console screen, type graphicsmode 179 first.

Here is a batch file to search for and list BIOS strings. Save the file to your grub4dos bootable disk as ShowBiosStrings.bat, boot to a grub4dos command prompt and then type:

ShowBiosStrings 0x680+0x180 CPU

and see what you get (tip: add insmod %0 to load the whole batch file into memory and speed it up a lot)!
This requires \grub\wenv. If a string is found the GOTSTR=1 is returned.


!BAT
if "%1"=="FF" goto :FF
if "%1"=="" goto :EOF

:: Requires wenv in grub folder

:: Usage: ShowBiosStrings.bat [memorystart+memoryrange] [string]
:: where memorystart and memoryrange is in units of 512 bytes

:: e.g. ShowBiosStrings.bat 0x680+0x80 CPU
:: ShowBiosStrings.bat 0x700+0x80 "cpu\ is\ present"
:: ShowBiosStrings.bat 0x780+0x80 cpu\ is\ present

:: 0x680 = D000:0 in memory and is often use for storing DMI BIOS strings
:: 0x700 = E000:0 in memory and is used for DMI string as well a BIOS code and workspace
:: 0x780 = F000:0 in memory and is usually the BIOS code but may also contain fixed strings

:: 0x680+0x180 will search all BIOS area from D000:0 to end of BIOS area (FFFF:F)
:: 0x680+0x80 will seach the 64K segment from D000:0 only
:: 0x700+0x100 will search 128K from E000:0

:: This grub4dos batch file displays all BIOS strings matching the specified string
:: Case Insensitive - if one or more matches found GOTSTR=1

:: so we don't get invaild argument if no matches
errorcheck on
debug 1
set GOTSTR=
set SLOC=%1
:: get location of strings from D000:0 to F000:FFFF in BIOS and DMI area
cat --locatei=%2 (md)%SLOC% | set a=
:: limit to 400 chars to reduce length of the for /f line below 512 chars!
set a=%a:~0,400%
if "%a%"=="" goto :EOF
:: parse the list and get first 17 locations into %i to %z - call this batch file again (%0) with FF as the first parameter so that it jumps to :FF
/grub/WENV for /f "delims= " %i in ( "%a%" ) do exec %0 FF %i %j %k %l %m %n %o %p %q %r %s %t %u %v %w %x %y

set a=
set A=
set z=
set SLOC=
goto :EOF

:: ============ SUBROUTINE =====

:FF

:: %2 %3 etc will have the first 17 locations
::echo @F 2=%2 3=%3 4=%4 5=%5 6=%6 7=%7 8=%8 9=%9
:: we may have an odd " in the string, turn off errorchecking otherwise it may abort
errorcheck off
set z=
if "%2"=="" goto :EOF
set z=%2
set z=%z:~0,5%
if %z:~-2,1%"=="" set z=%z:~,-2%
set /A A=0x%z%+0 > nul
if "%A%"=="0x0" goto :EOF
if "%A%"=="" goto :EOF
:: we can turn it on again now!
errorcheck on
:: now put the string at location %A% into memory
::cat --length=50 --skip=%A% (md)%SLOC%
cat --length=50 --skip=%A% (md)%SLOC% > (md)0x3000+1
:: remove line feeds, carriage returns, etc.
cat --locate=\x0a --replace=\x20 (md)0x3000+1 > nul
cat --locate=\x0d --replace=\x20 (md)0x3000+1 > nul
:: ensure end of string is marked
echo -e -n \x0 >> (md)0x3000+1
:: now display the modified string on the display
echo -n @(md)%SLOC% OFFSET=%A% ==>
cat (md)0x3000+1
:: throw a line
echo
:: set success - found a match!
set GOTSTR=1
:: shift %3 to %2 and loop until no more left
shift
goto :FF

Special 'command line' variables

%0 is the calling batch file name
%1 to %9 are parameters 1-9 (use shift if you have more than 9 parameters)
%* represents all parameters

call :fred mary joe
...
goto :eof

:fred
echo %2 is joe
goto :eof

IMPORTANT GOTCHA!

In batch files, %0-%9 and %* will be recognised as a command line variable, therefore the following do not work as expected in a batch file:

set /a A=%B%*2 - %* means all parameters - use set /a A=%B% *2
echo %D%1 - %1 means the first parameter - use %D%%1

Another Batch file example - use checkdate.g4b to check an Expiry Date

A simple example of an expiry date test (thanks to Wonko on reboot.pro) is:

if 20131226>[email protected]:~0,[email protected]:~5,[email protected]:~8,2% pause --wait=3 THIS SOFTWARE HAS EXPIRED - XMAS 2013 IS OVER && halt

Suppose we release a bootable CD or USB drive which has software on it that should be regularly updated. We want to warn the user when it is about to expire or if it has expired. We can use a grub4dos batch file to do this and call it from a menu.lst file like this:

# Usage: /checkdate.g4b <Release Year> <Release Month> <Release DayOfMonth> <ExpiresInDays> [<SILENT>]
# Example below: Released on 2102-12-03 Expires in 30 days
/checkdate.g4b 2012 12 3 30
# Example1 without text displayed: /checkdate.g4b 2012 12 3 30 SILENT
# Example2 without text displayed: /checkdate.g4b 2012 12 3 30 > nul
pause
if NOT "%CHECKDATE%"=="OK" reboot

This will show the following text when the grub4dos menu runs...

CheckDate: Release Date 2012-12-31 (Today is 2012-12-31)
CheckDate: This version is good for 30 days from release
CheckDate: This version expires in 29 day(s)

OR

CheckDate: Release Date 2012-12-3 (Today is 2012-12-31)
CheckDate: This version is good for 30 days from release
CheckDate: WARNING: This is older than 30 days!


The checkdate.g4b file can be found at the bottom of this page or click here. If you add the word SILENT to the call parameters then the user will have no idea why it no longer displays a nice menu and just keeps rebooting!

Note: If you are burning this to a CD or DVD, use an 8.3 filename like chkdate.g4b as checkdate.g4b is too long a name!

If you wish to 'encrypt' your menu.lst file so that it is not just a plain text file, use 7Zip to compress the menu.lst file to GZip format (menu.lst.gz) and then rename the file to menu.lst.
grub4dos will still run the compressed menu.lst file just fine but if anyone tries to read the file using a text editor they will find it hard to understand!

Set the System Date

Using the grub4dos Function 53 we can set the Real Time Clock date. The Date.g4b grub4dos batch file can be run to set the date - this might be useful for expiry date sensitive DOS utilities that check the date of the system.

run the batchfile from your menu.lst like this

# set date of system to Jan 30th 2001
/Date.g4b 2001-01-30

# OR ...
# Prompt user to set a date
/Date.g4b

Note that this will permanently change the date of the system Real Time Clock until you set back the correct time.

grub4dos variables and setlocal/endlocal

Currently there is a maximum limit of 60 variables and each can be up to 512 bytes each.
The batch file VarsLeft.g4b will tell you how many variables remain out of the 60 allowed. It is quite easy to run out if you are not careful!
If you reset them (e.g. set A= will remove the variable A from the environment) then you will free up a 'slot for another variable'.

You can use setlocal to make a copy of the current environment (e.g. variables, root path, current filespec, etc.).
When the endlocal command is run these values are restored and any variables set during the setlocal portion are lost (a copy of the current environment is made when you use setlocal and that copy is restored when you use endlocal).

e.g.

set l=1
set m=
root (hd0,0)
setlocal

root (hd1,0)
set l=2
set m=1
echo %l% is 2
endlocal

echo %l% is 1
echo %m% is empty
echo root command shows (hd0,0) is the root
root

If you want to use setlocal, but pass back a variable, you can do it by placing an && set x=y statement on the end of the same line as endlocal - like this:

set m=3
setlocal
set /a m=%m%+1
set n=4
endlocal && set m=%m% && set n=%n%
echo %m% is 4 and %n% is 4

setlocal will inherit the current variables.
If you have 30 or so variables already set, then when you use setlocal, you will already have 30 variables set - this uses up the variable space (max. 60 variables can be defined). You can clear the local variables using set * : e.g.

setlocal
set *
# now no variables set
### do stuff here
set A=1
endlocal && set fred=%A%
#now original variables restored + fred=1

There is an undocumented way of getting more than 60 variables in 2013+ versions of grub4dos - see here for details.

Global variables

grub4dos currently supports up to two user-definable global variables.

?_xxxx and ?_yyyy where xxxx and yyyy can be any user defined name - the first two that are set by the user become global, any more are ignored.

setlocal
set ?_test=test
set ?_x=x
set ?_x=
set ?_y=y
endlocal
echo %?_test% %?_x% %?_y%

will produce the result:

test y

Note: set does not list these global variables, nor does set ?_ - you can only see their values if you reference them by name.

Note that set * will also delete the global variables

setlocal @

You can also use the special parameter @ with setlocal, this will preserve all variables after an endlocal is executed
e.g.

!BAT
set doris=
set fred=9

setlocal @
set steve=3
set doris=%fred%
echo ----- level 1
set
endlocal

echo ----- level 0
set

Produces the output:

----- level 1
fred=9
doris=1
steve=3
----- level 0
fred=9
doris=9
steve=3

Another example when mixing setlocal @ with setlocal

!BAT
set a=0
setlocal @
set a=1
setlocal
set a=2
setlocal
set a=3

When the batch exits, the variable a=1

Batch files that search sub-folders

FFFName.g4b - FindFullFileName - finds the first file matching a full filename, searches all disk - e.g. /grub/FFName.g4b / explorer.exe
FFName.g4b - FindFileName - finds the first file matching a filename (without extension), searches all disk - e.g. /grub/FFName.g4b / explorer
FFExt.g4b - FindFileExtension - finds the first file matching a file extension - returns variables - e.g. /grub/FFExt.g4b /_ISO .iso
DirFile.g4b - lists all files in a single directory (does not list directories) (e.g. /grub/DirFil.g4b /_ISO DIR (to just list dir names omit DIR))
LstDir.g4b - Lists directory names in a directory (e.g. /grub/LstDir.g4b /_ISO DIR (to just list dir names omit DIR))
LstFExt.g4b - Lists all files in a single folder that match a file extension

The names must be kept to 11 characters - otherwise insmod refuses to load it (says filename too long!). Make sure there are no spaces at the end of the line after the filename or this will be counted too!

Please download FindFile.zip to obtain these batch files.

The batch file LFExt.g4b lists all files in a single speciified folder (and not below - this has been suppressed in the batch file) that match a specified extension, e.g. /LFExt.g4b /_ISO/Linux .iso will list all ISO files e.g.:

aaaaa.iso
bbbbb.iso
ccccc.iso

wenv

Wenv (available on Beta downloads page) is a grub4dos utility (a program - see grubutils section below) that you can run under the grub4dos environment. It is just like an executable that you would run under DOS (e.g. find.exe) but it runs under grub4dos. It allows you to use environment variables in your menu.lst files or to run a script file which can execute grub4dos commands. Note: The Wenv download zip file in the Beta Downloads section of this site also includes an English translation of the Chinese text help file for wenv which I have added for you to study.

For instance....

title Install Windows 7 64-bit Enterprise Edition\nRun the Windows install DVD to install a copy of Windows to your hard disk
/Imdisk/wenv set iso=/iso/en_windows_7_enterprise_with_sp1_x64_dvd_620201.iso
find --set-root/ImDisk/myiso.cmd
dd if=()/ImDisk/au.xml of=()/AutoUnattend.xml
dd if=()/ImDisk/cr.txt of=()/ImDisk/myiso.cmd
/ImDisk/wenv call write ()/ImDIsk/myiso.cmd SET MYISO=${iso}\r\n
/ImDisk/wenv call map ${iso} (0xff)
map (hd0) (hd1)
map (hd1) (hd0)
map --hook
chainloader (0xff)
    Note that line 2 sets the grub4dos environment variable 'iso' to the path of the ISO file by running the wenv executable with parameters.
    In line 6 and line 7 we can use this variable value by substituting it with ${iso}.
    Note that wenv needs to have a full path as grub4dos needs to find the wenv file which is in the /ImDisk folder in this example.
    Also note that to use environment variables and wenv with grub4dos commands, we need to 'call' the grub4dos command, this why lines 6 and 7 start with '/ImDisk/wenv call'

    If you copy the grub4dos executable file
    wenv (latest version available on grubutils download page)to the USB drive /ImDisk folder, you can make the menu.lst easier to edit and add more ISO files.

    WENV list of commands currently supported:

    SET to set/change/add/delete/display variables - for a substring use :~start,length - e.g. set a = %xyz:~10,2%%%xyz:~13,2%
    (note you need to add another % when two %% signs are used together!)

    GET display variable/variables and get length of the variable in ?_GET internal variable
    FOR similar to the windows shell FOR cmd instruction
    CALC simple calculator (priority from left to right, does not support brackets)
    ECHO Display a message or variable to the screen
    READ a file and run the commands inside - similar to a .cmd batch file (must use WENV supported commands) also supports parameters.
    CHECK check if an equation is true or false, if it returns true a command can be executed
    RESET clear/reset a variable
    CALL call the grub4dos shell to execute a grub4dos command

    Note: SET, GET, FOR, RESET, CALC and ECHO are largely redundant now as similar functions are built into the latest grub4dos versions from chenall (included in RMPrepUSB).

    For instance, if you type /wenv set in the grub4dos command console window, then wenv will display all current grub4dos environment variables.

    Here is another example of how you can use wenv (note: this time wenv is located in the root of the drive and not in the ImDisk folder):

    title Specify an iso file to run
    # list all files in the /boot/imgs folder so the user can see them
    ls /boot/imgs/
    echo
    # Ask user which iso they want (name is converted to uppercase as $U is specified)
    /WENV set ask=$U,$input,Enter iso name with no extension (e.g. dban) :
    /WENV get ask || echo No iso file specified! && configfile (bd)/menu.lst
    clear
    /WENV echo Loading /boot/imgs/${ask}.iso - please wait ...
    # run the grub4dos map command and specify the iso file we want to load
    /WENV call map --mem (bd)/boot/imgs/${ask}.iso (0xff)
    map --hook
    chainloader (0xff)

    # Examples using the RUN.bat file (included with the download)
    title Auto-make menu for /BOOT/IMGS/ folder
    # call the RUN batch file and create a configfile in the ramdrive for all image files
    /RUN.bat .Automenu
    # Load the new configfile
    configfile (md)0x3000+0x10

    title Boot dos
    # call the RUN batch file with the file we want to load in the /BOOT/IMGS folder specified
    /RUN.bat DOS622.IMA
    # Add the boot command so the user can use the cursor keys to select this menu entry
    boot

    For an example of how to make a script file which can run under grub4dos (which must begin with the text !BAT), see the file RUN.BAT example included with the wenv.zip download.

    For an example of a grub4dos batch file that uses wenv to display the MBR partition table of a drive - see jaclaz's/Wonko the Sane's mbrview.g4b batch file on reboot.pro here.

    Example output of mbrview.g4b batch file from jaclaz.

    hotkey

    Another grub4dos utility you can run is the 'hotkey' utility which allows the user to use hotkeys (e.g. F1, F2, etc.) to select a menu item and run it (use the latest chenall build of grub4dos) - see Tutorial #57 for details.

    grubutils

    'grubutils' is just a name for a collection of individual executable utilities that can run within the grub4dos environment.
    Grub4dos can call these utilities or execute them from a grub4dos batch file or from within a grub4dos menu.lst.

    Some of these will list usage syntax if you use -h switch. C sources are