When I do this, registering of the dll fails with 80002009. Any help?
If I change it to

val HandlerPath = s 'C:\windows\system32\awesome.dll'.

then the registration succeeds (but of course now contains
a hard-coded path).

A common problem people have when asking a question is assuming
that the person reading your question has knowledge that is a
strict superset of what you know.
As a result, people omit details like
the answer to the question
"How did you register your RGS file?"

If all else fails read the documentation
(which happens to be the #1 hit for "rgs file", or at least was
at the time of this writing).
And the documentation explains
how the % works.
And it's not for environment variable expansion.

As the documentation says,
you need to use the
_ATL_REGMAP_ENTRY macro to
create the mapping for replacement variables.

This type of question reflects a certain mentality which is
cute when kids do it,
but frustrating when demonstrated by programmers,
namely, that features exist
merely because you expect them to,
rather than because there's any documentation that
suggests that they exist.

People that expect environment variables to be expanded everywhere doesn't understand that it, too, would make the % sign illegal everywhere… including this comment! Fortunately, it works the other way: the default is not to expand environment variables, but there are some specific places where they are expanded.

Maybe they should add a feature to make, so if make game is executed and there is no feasible target "game", it runs some game. Perchance the original adventure/colossal cave as it can run everywhere make can.

From the problem statement, it was obvious to me that whatever system handles .rgs files doesn't do environment variable expansion. And I figured that out without having the foggiest notion what an .rgs file is!

I've seen similar questions pop up on StackOverflow where people wonder why things like fopen() can't understand file paths with tildes in them ("~/file.txt"). They don't realize that it's the *shell* which expands tildes, environment variables, etc., not the C standard library or OS.

Never heard of an RGS file before today; from what I can tell it's something related to ATL.

I wonder how long ago this was written. I don't see that MSDN article on the first page of any of the search results for "rgs file" (with or without quotes) with either Bing or Google. This 2002 KB article (support.microsoft.com/…/220836) shows up, but it's rather unenlightening.

On topic: I hadn't heard of RGS files before, but then again I'm not now, nor ever have been, an ATL or even a C++ programmer. Still, I had the same though as @DWalker – clearly whatever interprets RGS files doesn't do environment variable expansion. If cmd.exe ran it, then maybe I'd expect it, or if it was a REG_EXPAND_SZ (probably typed that wrong) but otherwise you can't just assume and hope. Although, as @Lockwood alluded to, it's worth at least trying and being pleasantly surprised :) (but then Raymond gets stuck supporting undocumented features that someone ended up relying on in code!)

Completely off-topic: I never could get around the idea behind the registrar in ATL. Writing text that's incompatible with standard *.reg, putting it into registry, parsing it to get registered, just so that one could write a bunch of registry entries!? I know of three libs that do COM (registration included), and only ATL choose the "parsing the text", and IMHO, it caused the most grief due to misunderstanding, misspellings and what have you. A classic example of over-engineering.

You mean Windows doesn't have a good thread scheduler today because of all the wishful thinking during the 90's? I guess my wishful thinking of SkyDrive letting me move files into folders on windows 8 is a lost cause, too, then. Don't crush my wishful thinking!

It would be helpful with a friendly error message explaning that the %windir% environment variable cannot be expanded to C:Windows (or what it currently is defined as) because the developer was to lazy. But it would probably not be much easier than implementing environment expansion in the first place.

"People that expect environment variables to be expanded everywhere doesn't understand that it, too, would make the % sign illegal everywhere… including this comment!"

The fact that they are expanded in (for example) the shell file open dialog – along with the fact that so many windows environment variables are directory names – leads people to the not unreasonable though entirely incorrect assumption that they will be accepted anywhere a filename is specified.