Introduction

ShellRun is used to AutoRun a CD, ie open a file automatically when the CD is inserted into a Windows computer.  Most people use ShellRun to display a web page when a CD is inserted.

The AutoRun basics page explains why ShellRun is needed, and cautions that AutoRun may have been disabled so you should always provide instructions for viewing your CD manually.  (Also see the HTML CDs article.)

This page contains the basic instructions for use of the retail version of ShellRun, along with details of how to run programs, play audio, use the "Do not reshow" feature and enable active content. 

Please consult the following pages for full configuration details:

Full list of parameters in ShRun.INF

How to display more than one file at startup, with optional conditions for each file

How to show a menu of command button options

How to configure the ShellRun display

How to cope if no viewer is available

Usage overview

1. Purchase a retail version licence and download the retail development kit.  Run this file to install ShellRun.
2. Copy the runtime file ShellRun.exe into your CD image root directory from your installation directory, eg C:\Program Files\PHD\ShellRun.
3. Write a plain text AUTORUN.INF file (see below) and put it in your CD image root directory.
4. Write a plain text ShRun.INF file (see below) and add your desired parameters to configure ShellRun.  Put it in your CD image root directory.
5. Burn a CD and try it out.

What ShellRun does

If all goes well, Windows will run ShellRun when your CD is inserted.

By default, ShellRun will display a popup window and ask Windows to show your requested file.  The popup window disappears after 15 seconds.

The popup window is shown in the top left hand corner of the screen; see the example on the right.

If the user clicks on the Info text, their default browser will be started to show the PHD Computer Consultants Ltd web site.

If you want to remove or customise the popup window (or use a splash screen instead) then see the Screen options page.

If you want to display more than one file when your CD is inserted, see below.

What can go wrong?

1. If ShellRun does not start, these are possible explanations:
   • You forgot to put ShellRun.exe, AUTORUN.INF or ShRun.INF in the root directory of your CD.
   • Your AUTORUN.INF or ShRun.INF format is incorrect - check below.

2. If ShellRun cannot find the file you requested, then it changes the bottom text line, adds an Exit button and stays on screen permanently:
   Check that the file is actually on the CD. Note that your system may be set up to hide file extensions, so a file that appears to be called test.htm may actually be called test.htm.htm

3. If there is no suitable viewer for the file you requested, then ShellRun changes the bottom text line, eg as follows for a PDF file.  Consult the viewer checking page for instructions on how to handle this situation better.

Writing an AUTORUN.INF file

If Windows finds a plain text file called AUTORUN.INF in the root directory of a CD, then it follows the instructions in this file to run a program.  See the AutoRun basics page for full details of the available commands for AUTORUN.INF.

If you want you can just use AUTORUN.INF to run ShellRun, as described in the freeware version instructions.  The only change is that filenames with spaces are supported by putting it in double quotes, eg:

[autorun]
open=ShellRun.exe "Sales Report.doc" Showing latest sales report...

However we recommend that you only use a basic AUTORUN.INF file and do all your configuration in the separate ShRun.INF plain text file.  Put this in your AUTORUN.INF:

[autorun]
open=ShellRun.exe

You can add more options on other lines in the AUTORUN.INF file, eg to set the icon for the CD - more details

Writing an ShRun.INF ShellRun Configuration file

ShellRun picks up configuration parameters from a plain text file ShRun.INF in the same directory as ShellRun.  For normal usage, this means putting ShRun.INF in the root directory of your CD.  As with AUTORUN.INF, use Windows Notepad to edit ShRun.INF.

The ShRun.INF file should contain one [Info] section header line. Each subsequent line specifies one parameter.  This example ShRun.INF was used to display the popup window shown on the right:

[Info]
filename=index.html
message=-max CD loading, please wait...
Display=XYZ Corporation
Web=http://www.phdcc.com/shellrun
WebMsg=Showing XYZ corp web site...

MsgColor=255,0,0
InfoFace=Comic Sans MS

Here's a brief description of each parameter used above:

filename	Tells Windows to display file index.html using the default browser
message	The Msg text is set to CD loading, please wait.... The browser is told to maximise its window
Display	The Info text is set to XYZ Corporation
Web	If the user clicks on the Info text, ShellRun displays http://www.phdcc.com/shellrun in the default browser
WebMsg	If the user clicks on the Info text, ShellRun displays Showing XYZ corp web site... as the Msg text.
MsgColor	The Msg colour is set to Red
InfoFace	The text font is set to Comic Sans MS

Note carefully that the message line will be replaced with an error message if ShellRun runs into any problems, eg as described above.

Running programs

You can also use ShellRun to run a program (instead of opening a file). Simply put the name of the program you want to run in the filename parameter, eg:

[Info]
filename=setup.exe

If you want to provide parameters to the program (ie as part of the command line) then put these in the param parameter, eg:

[Info]
filename=setup.exe
param=/install /user

Special filename parameters - IE kiosk mode

You can use the SpecialParam parameter to provide special handling of the filename. SpecialParam must have an executable filename, a comma, then a command line.

The following example shows how to run Internet Explorer in kiosk mode (but only if IE is the default browser). The filename is set to the web page on CD.

[Info]
filename=index.htm
SpecialParam=iexplore.exe,-k %F

If SpecialParam has been used, ShellRun looks up the name of the program that handles web pages. For Internet Explorer, the program name will end in iexplore.exe. If the executable filename matches that specified in SpecialParam, then the executable is run with specified parameters. In this case, Internet Explorer is run with the following as its command line, if the CD is on the D drive:

-k D:\index.htm

The command line in SpecialParam has variable names replaced as follows:

%f is replaced with filename

%F is replaced with the full path to filename.

Playing audio on Enhanced CDs

The Enhanced CD format is used to create CDs containing music audio and computer data - click for more details

If the data on the CD contains an AUTORUN.INF file then Windows will follow the instructions in there rather than simply play the music audio. You can tell ShellRun to play the audio by using this special filename ~AudioCD~play. For example, to show a web page and start the music put this in your ShRun.INF file. (This example uses the show more files feature, ie the filename1 parameter specifies a second file to show.)

[Info]
filename=index.htm
.
.
filename1=~AudioCD~play

Windows Media Player, Real Player and MusicMatch Jukebox work as described above. However WinAmp Lite 5.1 does not play the music audio - instead it plays any music file it can find in the computer data (I think).

---

The special filename is in fact a general feature, described fully as follows:

~assoc[~verb[~file]]

where assoc is the Windows file association name, verb is the optional action verb (default: open), and file is optional file parameter (defaults to the ShellRun directory, eg the CD drive). ShellRun currently only runs the relevant command - it does not use DDE to give full instructions to the application.

Do not re-show option

ShellRun can give your users the option of not AutoRunning the CD the next time it is inserted. A configurable checkbox labelled "Do not show again" appears in the ShellRun popup window. If the user checks this box then ShellRun does not show any files the next time the CD is inserted. If the user holds down the Ctrl key while inserting the CD, then ShellRun ignores this setting and always shows its file(s).

This is how it works. The CD does in fact always AutoRun, ie ShellRun is indeed run every time the CD is inserted. ShellRun stores the user's "Do not show again" selection in the registry. If the user has opted not to show again, then ShellRun stops straight away without showing any files or windows etc.

ShellRun uses a registry folder to store the "Do not show again" selection:
   HKEY_CURRENT_USER\Software\PHD\ShellRunCDs
You must provide the name of a key within this folder to uniquely identify your CD. If you specify "Mycorp Europe sales" then this key is used:
   HKEY_CURRENT_USER\Software\PHD\ShellRunCDs\Mycorp Europe sales
ShellRun stores an integer (REG_DWORD). If this value is non-zero then the user has opted not to show files again.

To enable this feature, add an DoNotRepeatId parameter that specifies your CD identifier. You can also optionally set DoNotRepeatText to change the "Do not show again" text and DoNotRepeatColor to set the text colour (default:blue).

You will need to give your users a chance to make a "Do not show again" selection. By default the ShellRun popup window appears for only 15 seconds and may be hidden by the displayed files. Use the ShowTime parameter to increase the time that the ShellRun popup is shown, or set it to -1 to display the popup permanently. Set the ShowOptions parameter to 1 if you want the ShellRun popup window to appear in front of all other windows to ensure that the user sees the "Do not show again" option.

[Info]
filename=index.htm
.
.
DoNotRepeatId=Mycorp Europe sales
DoNotRepeatText=Do not AutoRun CD
DoNotRepeatColor=128,0,0
ShowTime=-1
ShowOptions=1

If Message is set to -nomsg then the popup window is never shown. If this happens, then the registry key can never be set by ShellRun. However you may set the registry key with another program to stop ShellRun running again.

Windows Vista and XP SP2+ Internet Explorer Active Content Enabling

This option works by removing your CD users' security restrictions temporarily. Please inform them that this is happening.

Windows XP Service Pack 2, Windows Vista (and equivalent) by default restricts "active content" in web pages in Internet Explorer running locally, ie on My Computer and on CDs. Active Content is any JavaScript, Java applets, ActiveX controls, etc.  More info on XP SP2.

You can use ShellRun to enable active content on CDs or DVDs using the ActiveCD parameter.  This has two options all or cd.

cd corresponds to the "Allow active content from CDs to run on My Computer" option in Tools+Internet Options+Advanced.

all corresponds to the "Allow active content to run in files on My Computer" option and the cd option.

It might seem that cd is all that is required to run active content from CD.  However when just this option is used, the user still receives warnings and sees the Information Bar - although active content is indeed enabled.  To remove all warnings, use the all option.

ShellRun only implements the ActiveCD option if it is running from a CD or DVD drive.  If the required option is already set, ShellRun does nothing more.  However, if a setting change is required, then ShellRun continues to run in the background until the CD is ejected, the system is shut down or the user logs off; at this point ShellRun restores the setting to its original value.

This feature works for both XP Administrator and Limited users.  The code is run on all Windows platforms so as to ensure forward compatibility.

This option only works if ShellRun runs, ie when a CD is AutoRun. Some users may have AutoRun turned off, so they will potentially not be able to see the CD active content unless they enable it manually.

Some organisations have 'group policies' for all their computers. These policies may stop these settings being changed, or change them back at a later stage.

Very occasionally, Windows may prompt for the CD to be re-inserted after you eject the CD.  This happens because the ShellRun executable lives on the CD; if it has been removed from working memory then Windows will need to reload it so that it can run (to process the CD eject request).  A possible future solution is for ShellRun to copy itself to a temporary location on disk and run from there.

As stated above, this option lowers a user's security level while the CD is run.  ShellRun covers all normal situations to restore the user's security level; however in exceptional circumstances, eg if ShellRun is terminated or the computer loses power, then the security level may remain lowered.

Note that by default, Windows Vista will ask the user whether to AutoPlay (ie run) a CD's AutoRun program, as seen in this dialog: