Using Replaceable Parameters (The Registrar's Preprocessor)


For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

Replaceable parameters allow a Registrar's client to specify run-time data. To do this, the Registrar maintains a replacement map into which it enters the values associated with the replaceable parameters in your script. The Registrar makes these entries at run time.

The ATL Control Wizard automatically generates a script that uses %MODULE%. ATL uses this replaceable parameter for the actual location of your server's DLL or EXE.

Another use of the preprocessor is to concatenate run-time data with script data. For example, suppose an entry is needed that contains a full path to a module with the string ", 1" appended at the end. First, define the following expansion:

'MySampleKey' = s '%MODULE%, 1'  

Then, before calling one of the script processing methods listed in Invoking Scripts, add a replacement to the map:

   TCHAR szModule[_MAX_PATH];
   ::GetModuleFileName(_AtlBaseModule.GetModuleInstance(), szModule, _MAX_PATH);
   p->AddReplacement(OLESTR("Module"), T2OLE(szModule));   

During the parsing of the script, the Registrar expands '%MODULE%, 1' to c:\mycode\mydll.dll, 1.

System_CAPS_ICON_note.jpg Note

In a Registrar script, 4K is the maximum token size. (A token is any recognizable element in the syntax.) This includes tokens that were created or expanded by the preprocessor.

System_CAPS_ICON_note.jpg Note

To substitute replacement values at run time, remove the call in the script to the DECLARE_REGISTRY_RESOURCE or DECLARE_REGISTRY_RESOURCEID macro. Instead, replace it with your own UpdateRegistry method that calls CAtlModule::UpdateRegistryFromResourceD or CAtlModule::UpdateRegistryFromResourceS, and pass your array of _ATL_REGMAP_ENTRY structures. Your array of _ATL_REGMAP_ENTRY must have at least one entry that is set to {NULL,NULL}, and this entry should always be the last entry. Otherwise, an access violation error will be generated when UpdateRegistryFromResource is called.

System_CAPS_ICON_note.jpg Note

When building a project that outputs an executable, ATL automatically adds quotation marks around the path name created at run time with the %MODULE% registrar script parameter. If you do not want the path name to include the quotation marks, use the new %MODULE_RAW% parameter instead.

When building a project that outputs a DLL, ATL will not add quotation marks to the path name if %MODULE% or %MODULE_RAW% is used.

Creating Registrar Scripts