MX_SHORTCUT
Updated September 2014
xcall MIAMEX, MX_SHORTCUT, target, lnkspec {, descr, workdir, icon, iconidx, status}
MX_SHORTCUT (MIAMEX 173) creates a shortcut, on the desktop or in any other folder.
This function has both a subroutine and a print tab implementation.
Parameters
target (String) [in]
should be set to the object or command line that the shortcut links to. Any %ENV% vars will be pre-resolved, i.e. at the time the link is created (rather than when it is clicked on). Examples:
TARGET = """%MIAME%\bin\ashw32.exe"" -i ""%MIAMEFILE% abc"""
TARGET = "http://www.microsabio.com"
TARGET = """c:\company shared folders\readme.txt"""
Note: as shown above in the first and third example, you must supply literal quotes as needed to enclose any path compoents of the target command line that may contain embedded spaces. (In the first example, we don't know if %MIAME% or %MIAMEFILE% will contain embedded spaces, so we quote them to be safe.)
lnkspec (String) [in]
should be set the full filespec of the shortcut itself. The default extension is ".lnk"; any other extension may fail to be recognized by the Explorer as a shortcut (or "Shell Link"). lnkspec does not require literal quoting even if contains embedded spaces. Example:
LNKSPEC = "C:\vm\miame\test shortcut.lnk"
Note that the filename (minus the .lnk extension and directory) will appear under the icon when in icon view, i.e. "test shortcut" in the above example.
To put the icon on the user's desktop, you can use the %USERPROFILE% environment variable, e.g.:
LNKSPEC = "%USERPROFILE%\Desktop\check this out.lnk"
For the common or "all users" desktop, use "%ALLUSERSPROFILE% instead of %USERPROFILE%, but beware that the operation may be blocked by a variety of security restrictions, and will require elevation under Vista.
See Comments, below.
descr (String) [in]
may specify a description to be embedded within the shortcut properties.
workdir (String) [in]
may specify the starting working directory for the process when the target is launched. It does not require quoting.
icon (String) [in]
may specify a separate file from which the display icon should be taken. It does not require quoting. If not specified, then the first icon of the executable associated with the target will be used. (If you want to user another icon from that executable, you must specify the module name again here.)
iconidx (Num) [in]
may specify the icon index (0,1,2,...) of the icon within the file (default is 0, the first icon). Ignored unless icon is not blank.
status (F) [out]
the return status. 0=ok. Positive numbers are Windows system error codes. (See MX_ERRNOMSG to display text). -1 indicates no GUI support available (requires Windows or ATE), and -15 indicates that ATE did not respond..
Comments
Note that any %ENV% environment variables will be resolved relative to the computer on which this function is invoked. In the case of ATE, that would be the server, whereas you probably want it to be relative to the client desktop. To solve that, you will have to use the AG_GETENV command separately (preferably via MX_AGWRAPPER) to resolve client-specific environment variables, such as %USERPROFILE%, and then pass the resolved value.
Example
The following would work on either local A-Shell Windows or ATE to create a shortcut on the client desktop, called "test shortcut" which executes the specified ATE launch command. Note for simplicity we are assuming here that the directory c:\ate contains an installation of ATE. To be more general you would need to use additional inquiry commands to determine the environment and the installed location of ATE, if applicable.
program shortcut,1.0(100) ! create shortcut
++include ashinc:ashell.def
map1 misc
map2 cmd$,s,260
map2 icon$,s,260
map2 status,f
map2 lnkspec$,s,260
icon$ = "ashell1_t.ico" ! borderless A-Shell icon
cmd$ = "c:\ate\bin\ashw32.exe -i c:\ate\miame.ini -g "+icon$+" -atecfg ?"
icon$ = "c:\ate\icons\" + icon$
! note: for ATE, we have to first resolve any client-side env vars,
! in this case, %USERPROFILE%...
! (extra step is harmless in local Windows case)
xcall MIAMEX, MX_AGWRAPPER, AG_GETENV, "%USERPROFILE%,1",lnkspec$
! put the shortcut on the users's desktop
lnkspec$ += "\Desktop\test shortcut.lnk"
? "Creating shortcut ";lnkspec$
xcall MIAMEX, MX_SHORTCUT, cmd$, lnkspec$, &
"Description of shortcut", "c:\ate", icon$, 0, status
? "Status: ";status
end
See Also
History
2014 September: Added "Comments" and "Example"
