Using Replaceable Parameters (The Registrar's Preprocessor)

Visual Studio 2015
 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at Using Replaceable Parameters (ATL Registrar).

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:

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

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

C++
Copy 
   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

Show: