After a bit of frustration I figured out how to make shortcuts to batch files and documents that can be pinned to the task bar or start menu. The solution wasn't obvious and the details also were difficult to get right.
Shortcuts that can be pinned to the task bar or start menu must have an executable file as a target. In my case, I had a batch file to abort a program because the program had no "close" option and would only either restart or shut down the system on closing. The problem was that if I created a shortcut with the batch file as the target, then it would never pin to the task bar or start menu, even though it was added in the correct [PinUtil] section of PeCmd.ini.
Here is what I used in the plugin that did not pin the shortcut to the task bar.
AddShortcut,StartMenu,%MenuFolder%,"%PE_Programs%\%ProgramFolder0%\KillHDM17.bat","Close Paragon HDM 17",,"%PE_Programs%\%ProgramFolder0%\HDM17Close.ico"
True,AddPin,TaskBar,Auto,"#$pStartMenu#$p\Programs\%MenuFolder%\Close Paragon HDM 17.lnk"
The #$pStartMenu#$p uses character escapes to pass the string %StartMenu% to PeCmd.ini to refer to the run time environment variable for the start menu location. Without using escape characters, the %StartMenu% in the plugin would refer to a build time variable named "StartMenu".
Here is how PeCmd.ini looked when the shortcut did not pin to the task bar.
_SUB Shortcuts
LINK %Programs%\HD Tasks\Close Paragon HDM 17,X:\Program Files\Paragon Software\Hard Disk Manager 17 Advanced\KillHDM17.bat,,X:\Program Files\Paragon Software\Hard Disk Manager 17 Advanced\HDM17Close.ico
...
[PinUtil]
TaskBar6=%StartMenu%\Programs\HD Tasks\Close Paragon HDM 17.lnk
...
The target in the properties for the resulting shortcut looked like this.
"X:\Program Files\Paragon Software\Hard Disk Manager 17 Advanced\KillHDM17.bat"
Notice that the LINK command in PeCmd.ini added quotes around the target path, so the shortcut is OK and it launches the batch file. It just cannot be pinned to the task bar because it doesn't refer to an executable file. The same problem occurs if a ".lnk" refers to a document instead of the application that opens the document. Pinning a ".bat" or ".doc" file doesn't work either, for the same reason.
The solution is to make the target of the shortcut refer to an executable file, and then use the arguments to specify the document (or batch file). To do that with a batch file, the target executable has to be "cmd.exe" and the argument has to be the batch file path. If there are other arguments needed, then add them after the batch file or document path, or wherever the target application expects them. In my case there were no batch file arguments.
Here is how the target of the shortcut should look in order for it to be pinnable.
"%SystemRoot%\System32\cmd.exe" /c "X:\Program Files\Paragon Software\Hard Disk Manager 17 Advanced\KillHDM17.bat"
The LINK command will add the quotes around the target, but it does not add quotes for any of the arguments. The quotes for the arguments have to be specified as part of the arguments.
Here are the correct statements to create the shortcut and pin it to the task bar.
AddShortcut,StartMenu,%MenuFolder%,"%SystemRoot%\System32\cmd.exe","Close Paragon HDM 17","/c #$q%PE_Programs%\%ProgramFolder0%\KillHDM17.bat#$q","%PE_Programs%\%ProgramFolder0%\HDM17Close.ico"
AddPin,TaskBar,Auto,"#$pStartMenu#$p\Programs\%MenuFolder%\Close Paragon HDM 17.lnk"
Notice that the AddPin statement didn't change at all. It was never the cause of the problem. Changing it would not have done any good, even if it was changed to specify the batch file or a document directly. The only thing that would be pinnable is a path to an executable file, but then the associated document, or in my case a batch file would not be opened.
The quotes around parameters for AddShortcut are stripped out before those parameters are passed into the macro. So, how are the quotes added in the correct places for the arguments? This is one of those cases to use the character escapes that include a character literal in a string without the character being interpreted as a "special" character. The #$q escape is used to insert a double quote in the argument string instead of it being a closing or opening quote for the macro parameter. This works the same way as the #$p did for %StartMenu%. If there are other arguments that need quotes, such as other file paths, then the quotes can be added in the same way using #$q. Spaces can be included using #$s or you can use normal space characters with enclosing quotes around the entire arguments macro parameter like I did in the example above.
Even if you don't pin your shortcuts to the task bar or start menu in your plugin, you still may want to create pinable shortcuts so that the user can right-click on the shortcut and pin it at run time. If you don't create a pinable shortcut, then the pin options do not appear in the right click menu. That is an easy way to tell if the shortcut is pinable.
Hi
other escape codes used
#$c = Comma [,]
#$p = Percent [%]
#$q = DoubleQuote ["]
#$s = Space [ ]
#$t = Tab [ ]
#$x = NewLine
## = Sharp [#]