ZTree Application Menu Directives

ZTree Application Menu (F9) Directives

[UP] Macros Application Menu Configuring

Contents

Application Menu directives:

What are ZTree Application Menu Directives?
How do I code and use directives?
Security and interactivity

Directives reference:

#ZTset
#ZTsetQ
#ZTinclude
#ZTsecure
#ZTifDIR
#ZTtag
#ZTdrive
#ZThome
#ZTexe
#ZTversion
#ZTview
#ZTstart
#ZTexit

Proposals (ZEPs) for new directives

Contents

Contents
Application Menu directives: What are ZTree Application Menu Directives? How do I code and use directives? Security and interactivity Directives reference: #ZTset #ZTsetQ #ZTinclude #ZTsecure #ZTifDIR #ZTtag #ZTdrive #ZThome #ZTexe #ZTversion #ZTview #ZTstart #ZTexit Proposals (ZEPs) for new directives

What are ZTree directives?

ZTree directives are special instructions to the Application Menu pre-processor. The pre-processor will recognize them as it builds, line by line, the temporary ZTW_MENU.BAT file from a script entry stored in the Application Menu. The pre-processor will generate legal batch file command lines and strip off any directives found in the script entry.

The .BAT file thus created will be completely indistinguishable from any other .BAT files created manually.

This mechanism enhances the standard Windows batch language by giving the user more control over how a script will be executed. This also permits creating scripts that are more generic, as well as adding a certain level of interactivity -- a feature which is either missing, or inconsistent in the various Windows batch language variants.
Contents

How to code and use directives?

ZTree directives are "hidden" in the standard REM or :: statements of the batch language. (Note: It has been demonstrated that :: statements execute faster than REM statements, making them highly recommendable for heavy network use.)

Because ZTree directives are hidden, batch procedures can safely be tested and used in the standard way, i.e., from the command line prompt. It is only when run from within the ZTree Application Menu that the directives become visible and can affect the execution of a batch script.

See the Reference section for examples.

The REM (or ::) line containing the directive itself is never copied to the output file. The directives can be coded in any combination of upper and lower case, i.e., #ztSETq is the same as #ZTSetQ.
Contents

Security and interactivity

Directives eliminate the need to hard-code any sensitive information in the scripts -- this can now be supplied interactively and securely (without screen echo) at run time. There is yet another level of security: it is possible to tell ZTree to delete the ZTW_MENU.BAT file automatically once the script has been executed!
Contents

Directives Reference

ZTset Get a string from the user (with echo) and store it in an environment variable.

Syntax REM #ZTset variable prompt_text

Description Displays the prompt_text string, if specified (otherwise Input: is displayed), and accepts a string from the user. The string is then used to generate the following line in the ZTW_MENU.BAT file:
SET variable=user_string
The user_string will be null if the user only hits Enter. This will result in the line SET variable= being generated. This directive, therefore, creates a new environment variable or, potentially, redefines an existing variable in the original script.

Example REM Connect to a file share as any user (Default: fred)
REM #ZTset USER Username [fred]:
IF "%USER%"=="" SET USER=fred
@echo Connecting as user %USER%...
@NET USE * \\server\share /USER:%USER% *

NOTES 1. The input routine interprets |, < and > signs as command line redirection, making it impossible to enter some text strings. This is usually not a problem, since the strings are typically destined for the batch SET command, which refuses this syntax anyway.
2. ESC should immediately abort script processing, rather than continue prompting, since nothing will be executed anyway once an ESC is seen.
3. Generating the line SET variable= will often be desired by the user. However, a mechanism is needed to leave alone an existing variable (by not redefining it with SET). In other words, completely skip generating a SET command line, but not abort the script! For example, a script may display 5 ZTsets to the user and the user should be able to press a key (like F4) to simply skip a prompt thus leaving a variable intact (or not defined). Not generating a SET commmand would thus allow hard-coded values to be preserved, if desired.

ZTsetQ Get a string from the user (with no echo) and store it in an environment variable.

Syntax REM #ZTsetQ variable prompt_text

Description Works exactly like ZTset, except that the user's input is not echoed on the screen. Instead, a series of *'s is displayed.

Example REM Connect securely to PROJ_Z file share as any user (Default: fred)
:: #ZTset USER Username [fred]:
:: #ZTset DRIVE Drive to map to [next free letter]:
:: #ZTsetQ PASS Password:
IF "%USER%"=="" SET USER=fred
IF "%PASS%"=="" SET PASS=*
IF "%DRIVE%"=="" SET DRIVE=*
NET USE %DRIVE% \\server\PROJ_Z /USER:%USER% %PASS%
:: Delete the generated ZTW_MENU.BAT so no trace
:: of the password is left on the disk.
DEL %0

NOTES Same as with ZTset. However, some passwords may be impossible to enter

ZTinclude Includes unconditionally a line in the script

Syntax REM #ZTinclude (rest of the line)

Description Generates a line from the text that immediately follows the directive. The script writer should make sure that this is a valid batch language command.

Example REM This batch script will run normally from the command line, but
REM when run from F9, will allow the user to make a decision before
REM continuing. This is achieved via extra commands inserted on the fly.
REM #ZTinclude @echo You are running this script from the F9 menu. Since this
REM #ZTinclude @echo task will take a long time to execute (and block ZTree),
REM #ZTinclude @echo you may decide to abort it via ^C now, or...
REM #ZTinclude @Pause
...
MegaProg -loop 10:00
...

Example REM This batch script will run normally from the command line, but
REM when run from F9, will perform differently
REM #ZTinclude SET FROM_ZTW=1
...
IF %FROM_ZTW%==1 GOTO SPECIAL
:NORMAL
...
:SPECIAL
...

Example REM Use the START command when running from F9, otherwise use CMD /C.
REM Note that the START command requires the first parameter (title)
SET RUN=CMD /C
REM #ZTinclude SET RUN=START "Running from ZTree"
...
%RUN% MyProg.EXE
REM Save this file, for whatever reason...
TYPE %0>>LAST_RUN.LOG

Example REM This program may produce error messages that you want to see
MyProg.EXE
REM Pause may not be needed when the script is run in a command window,
REM but may be necessary when run from within ZTree
REM #ZTinclude @Pause

ZTsecure Deletes ZTW_MENU.BAT after execution

Syntax REM #ZTsecure

Description Sets a flag within ZTree to immediately delete the ZTW_MENU.BAT file after its execution.

Example rem Tell ZTree to delete this file after execution
rem #ZTsecure
rem #ZTsetQ PASS Password
NET USE * \\server\PROJ_Z /USER:DOMAIN_Z\Administrator %PASS%

NOTES This should be more foolproof than self-deleting the file via DEL %0. While the latter works, there is no guarantee that it will continue to work in all environments.

ZTifDIR Includes a line only when F9 is called from DIR view

Syntax REM #ZTifDIR (rest of line)

Description Generates a line from the text that immediately follows the directive, provided the menu entry was called from the DIR, rather than the FILE view. (This differs slightly from ZTInclude, which generates the line unconditionally.) This directive helps the script writer handle the DIR and FILE contexts appropriately.

Example REM #ZTifDIR @echo You are running this script from the F9 menu. The currently
REM #ZTifDIR @echo active view is DIR, so we need to be careful...
REM #ZTifDIR SET INDIR=1
IF %INDIR%==1 GOTO Exit
DESTROY.EXE %1
:Exit

ZTtag Generates a text file consisting of the currently tagged filespecs

Syntax REM #ZTtag list_file [options]

Description Generates the specified list_file consisting of filespecs of currently tagged files. Several options are available to request various formats, similar to those recognized by ZTree's Ctrl+Insert or F9 functions:

-s Delimit with SPACE (default: CR/LF)
-a Append to existing file, if any (default: overwrite)
-f[PATTERN] (default: %1) Must be the last option

Example REM Generate a new list file by overwriting (the -a switch is not present)
REM a previous version, if present.
REM Filespecs are with full paths (-f%1 is implied) and there is one
REM filespec per line (CR/LF is used)
SET list=C:\TAGGED.LIS
SET log=C:\LOGS\NETPRINT.LOG
REM #ZTtag C:\TAGGED.LIS
REM Check if it was actually created successfully
@IF not EXIST %list% GOTO Done
echo Files being processed, one by one...
@FOR /f %%%%i IN (%list%) DO NETPRINT %%%%i
REM You may want to keep a log of the above
TYPE %list%>>%log%
DEL %list%
:Done

Example :: Append to existing file, if any.
:: The file pattern will generate 2 filespecs per line
:: #ZTtag C:\TAGGED.LIS -a -f%4.%5 %4.%5_OLD
:: Check if it was actually created
IF not EXIST C:\TAGGED.LIS GOTO Done
:: Call a procedure that knows what to do
:: with two filespecs per line
echo Files being processed, one by one...
@FOR /f %%%%i IN (C:\TAGGED.LIS) DO CALL RENAME2 %%%%i
DEL C:\TAGGED.LIS
:Done

ZTdrive A token representing the disk drive of the currently running ZTW executable.

Syntax text...#ZTdrive...text

Description When encountered anywhere in the text, this token is replaced by the drive letter, without the ":", of the currently running ZTW executable.

Example :: List the root of the drive on which currrent ZTW executes.
DIR #ZTdrive:\
Pause

ZThome A token representing the path name of the currently running ZTW executable.

Syntax text...#ZThome...text

Description When encountered anywhere in the text, this token is replaced by the path of the currently running ZTW executable. This eliminates the need for an external environment variable and makes the code fully portable.

Example :: List all BAT files in ZTW home directory.
DIR #ZThome\*.BAT
Pause

ZTexe A token representing the filespec of the currently running ZTW executable.

Syntax text...#ZTexe...text

Description When encountered anywhere in the text, this token is replaced by the filespec of the currently running ZTW executable. Normally, this is ZTW.EXE, but could also be a name like ZTW149a2.EXE

Example :: ZIP the currently running version of ZTree and ZTW.INI
:: and mail it using the BLAT command line mailer
SET archiver=C:\LEGACY\PKZIP
if "%OS%"=="Windows_NT" SET archiver=#ZThome\PKZIP25
COPY #ZThome\#ZTexe %TEMP%\#ZTexe.BUG
%archiver% -a %TEMP%\BUG.ZIP %TEMP%\#ZTexe.BUG #ZThome\ZTW.INI
blat %TEMP%\BUG.ZIP -to bugs@zedtek.com -subject "Crash in F8 mode"
DEL %TEMP%\#ZTexe.BUG
DEL %TEMP%\BUG.ZIP
Pause

ZTversion Holds the current ZTW executable version ID string.

Syntax text...#ZTversion...text

Description When encountered anywhere in the text, this token is replaced by the current internal version string of the currently running ZTW.EXE executable, for example: "1.49.2z7". This is the same string as the one displayed on the ZTree window title bar, or with Alt+F1. This may come handy for script testing and debugging purposes.

Example :: Use one or both of the following lines in your scripts
echo Using #ZThome\#ZTexe, version #ZTversion
:: This batch script was generated with: #ZThome\#ZTexe, version #ZTversion
...

ZTview View the generated script file (#ZTtemp\ZTW_MENU.BAT) with the Viewer, instead of executing it.

Syntax :: #ZTview

Description A script debugging tool, but also useful for displaying scripts that contain pure text. Works exactly like the F9 Alt+V command.

ZTstart Execute asynchronously the current script and pass any parameters to the START command.

Syntax :: #ZTstart arg1 arg2 ...

Description Asynchronous execution uses the START command (see START /?), thus allowing control to be returned to the the current ZTree process immediately. This is exactly how the F9 Alt-X (eXecute) command works. However, the #ZTstart directive also allows passing parameters to the START command, thus enhancing the Alt+X command. Ctrl+Enter will also honor the #ZTstart directive and force asynchronous execution, but the directive will be ignored if Enter is used to launch a script.
The script will be run from a unique file named #ZTtemp\yyyymmddhhssmm-ZTW_MENU.BAT, thus allowing safe batch execution of many parallel batch jobs originating from ZTree.
The contents of this batch file will look like this:
@ECHO OFF
...script body...
@DEL #ZTtemp\yyyymmddhhssmm-ZTW_MENU.BAT && EXIT

Example :: #ZTstart "Compressing %1 with PKZIP..." /LOW /MIN
:: If executed with Alt+X or Ctrl+Enter, this script will be run in
:: a minimized window and with low priority.
PKZIP -a %4_%5.ZIP %1

ZTexit Forces exit from the Application Menu after current script's execution.

Syntax :: #ZTexit

Description Upon script execution, this directive unconditionally exits from the Application Menu and returns to the File or Directory window. Executing a script with Ctrl+Enter has the same effect. #ZTexit also saves the memory contents to the ZTW.ZAM disk file before exiting the Application Menu.

Contents


ZTset	Get a string from the user (with echo) and store it in an environment variable.
Syntax	REM #ZTset variable prompt_text
Description	Displays the prompt_text string, if specified (otherwise Input: is displayed), and accepts a string from the user. The string is then used to generate the following line in the ZTW_MENU.BAT file: SET variable=user_string The user_string will be null if the user only hits Enter. This will result in the line SET variable= being generated. This directive, therefore, creates a new environment variable or, potentially, redefines an existing variable in the original script.
Example	REM Connect to a file share as any user (Default: fred) REM #ZTset USER Username [fred]: IF "%USER%"=="" SET USER=fred @echo Connecting as user %USER%... @NET USE * \\server\share /USER:%USER% *
NOTES	1. The input routine interprets \|, < and > signs as command line redirection, making it impossible to enter some text strings. This is usually not a problem, since the strings are typically destined for the batch SET command, which refuses this syntax anyway. 2. ESC should immediately abort script processing, rather than continue prompting, since nothing will be executed anyway once an ESC is seen. 3. Generating the line SET variable= will often be desired by the user. However, a mechanism is needed to leave alone an existing variable (by not redefining it with SET). In other words, completely skip generating a SET command line, but not abort the script! For example, a script may display 5 ZTsets to the user and the user should be able to press a key (like F4) to simply skip a prompt thus leaving a variable intact (or not defined). Not generating a SET commmand would thus allow hard-coded values to be preserved, if desired.
ZTsetQ	Get a string from the user (with no echo) and store it in an environment variable.
Syntax	REM #ZTsetQ variable prompt_text
Description	Works exactly like ZTset, except that the user's input is not echoed on the screen. Instead, a series of *'s is displayed.
Example	REM Connect securely to PROJ_Z file share as any user (Default: fred) :: #ZTset USER Username [fred]: :: #ZTset DRIVE Drive to map to [next free letter]: :: #ZTsetQ PASS Password: IF "%USER%"=="" SET USER=fred IF "%PASS%"=="" SET PASS=* IF "%DRIVE%"=="" SET DRIVE=* NET USE %DRIVE% \\server\PROJ_Z /USER:%USER% %PASS% :: Delete the generated ZTW_MENU.BAT so no trace :: of the password is left on the disk. DEL %0
NOTES	Same as with ZTset. However, some passwords may be impossible to enter
ZTinclude	Includes unconditionally a line in the script
Syntax	REM #ZTinclude (rest of the line)
Description	Generates a line from the text that immediately follows the directive. The script writer should make sure that this is a valid batch language command.
Example	REM This batch script will run normally from the command line, but REM when run from F9, will allow the user to make a decision before REM continuing. This is achieved via extra commands inserted on the fly. REM #ZTinclude @echo You are running this script from the F9 menu. Since this REM #ZTinclude @echo task will take a long time to execute (and block ZTree), REM #ZTinclude @echo you may decide to abort it via ^C now, or... REM #ZTinclude @Pause ... MegaProg -loop 10:00 ...
Example	REM This batch script will run normally from the command line, but REM when run from F9, will perform differently REM #ZTinclude SET FROM_ZTW=1 ... IF %FROM_ZTW%==1 GOTO SPECIAL :NORMAL ... :SPECIAL ...
Example	REM Use the START command when running from F9, otherwise use CMD /C. REM Note that the START command requires the first parameter (title) SET RUN=CMD /C REM #ZTinclude SET RUN=START "Running from ZTree" ... %RUN% MyProg.EXE REM Save this file, for whatever reason... TYPE %0>>LAST_RUN.LOG
Example	REM This program may produce error messages that you want to see MyProg.EXE REM Pause may not be needed when the script is run in a command window, REM but may be necessary when run from within ZTree REM #ZTinclude @Pause
ZTsecure	Deletes ZTW_MENU.BAT after execution
Syntax	REM #ZTsecure
Description	Sets a flag within ZTree to immediately delete the ZTW_MENU.BAT file after its execution.
Example	rem Tell ZTree to delete this file after execution rem #ZTsecure rem #ZTsetQ PASS Password NET USE * \\server\PROJ_Z /USER:DOMAIN_Z\Administrator %PASS%
NOTES	This should be more foolproof than self-deleting the file via DEL %0. While the latter works, there is no guarantee that it will continue to work in all environments.
ZTifDIR	Includes a line only when F9 is called from DIR view
Syntax	REM #ZTifDIR (rest of line)
Description	Generates a line from the text that immediately follows the directive, provided the menu entry was called from the DIR, rather than the FILE view. (This differs slightly from ZTInclude, which generates the line unconditionally.) This directive helps the script writer handle the DIR and FILE contexts appropriately.
Example	REM #ZTifDIR @echo You are running this script from the F9 menu. The currently REM #ZTifDIR @echo active view is DIR, so we need to be careful... REM #ZTifDIR SET INDIR=1 IF %INDIR%==1 GOTO Exit DESTROY.EXE %1 :Exit
ZTtag	Generates a text file consisting of the currently tagged filespecs
Syntax	REM #ZTtag list_file [options]
Description	Generates the specified list_file consisting of filespecs of currently tagged files. Several options are available to request various formats, similar to those recognized by ZTree's Ctrl+Insert or F9 functions: -s Delimit with SPACE (default: CR/LF) -a Append to existing file, if any (default: overwrite) -f[PATTERN] (default: %1) Must be the last option
Example	REM Generate a new list file by overwriting (the -a switch is not present) REM a previous version, if present. REM Filespecs are with full paths (-f%1 is implied) and there is one REM filespec per line (CR/LF is used) SET list=C:\TAGGED.LIS SET log=C:\LOGS\NETPRINT.LOG REM #ZTtag C:\TAGGED.LIS REM Check if it was actually created successfully @IF not EXIST %list% GOTO Done echo Files being processed, one by one... @FOR /f %%%%i IN (%list%) DO NETPRINT %%%%i REM You may want to keep a log of the above TYPE %list%>>%log% DEL %list% :Done
Example	:: Append to existing file, if any. :: The file pattern will generate 2 filespecs per line :: #ZTtag C:\TAGGED.LIS -a -f%4.%5 %4.%5_OLD :: Check if it was actually created IF not EXIST C:\TAGGED.LIS GOTO Done :: Call a procedure that knows what to do :: with two filespecs per line echo Files being processed, one by one... @FOR /f %%%%i IN (C:\TAGGED.LIS) DO CALL RENAME2 %%%%i DEL C:\TAGGED.LIS :Done
ZTdrive	A token representing the disk drive of the currently running ZTW executable.
Syntax	text...#ZTdrive...text
Description	When encountered anywhere in the text, this token is replaced by the drive letter, without the ":", of the currently running ZTW executable.
Example	:: List the root of the drive on which currrent ZTW executes. DIR #ZTdrive:\ Pause
ZThome	A token representing the path name of the currently running ZTW executable.
Syntax	text...#ZThome...text
Description	When encountered anywhere in the text, this token is replaced by the path of the currently running ZTW executable. This eliminates the need for an external environment variable and makes the code fully portable.
Example	:: List all BAT files in ZTW home directory. DIR #ZThome\*.BAT Pause
ZTexe	A token representing the filespec of the currently running ZTW executable.
Syntax	text...#ZTexe...text
Description	When encountered anywhere in the text, this token is replaced by the filespec of the currently running ZTW executable. Normally, this is ZTW.EXE, but could also be a name like ZTW149a2.EXE
Example	:: ZIP the currently running version of ZTree and ZTW.INI :: and mail it using the BLAT command line mailer SET archiver=C:\LEGACY\PKZIP if "%OS%"=="Windows_NT" SET archiver=#ZThome\PKZIP25 COPY #ZThome\#ZTexe %TEMP%\#ZTexe.BUG %archiver% -a %TEMP%\BUG.ZIP %TEMP%\#ZTexe.BUG #ZThome\ZTW.INI blat %TEMP%\BUG.ZIP -to bugs@zedtek.com -subject "Crash in F8 mode" DEL %TEMP%\#ZTexe.BUG DEL %TEMP%\BUG.ZIP Pause
ZTversion	Holds the current ZTW executable version ID string.
Syntax	text...#ZTversion...text
Description	When encountered anywhere in the text, this token is replaced by the current internal version string of the currently running ZTW.EXE executable, for example: "1.49.2z7". This is the same string as the one displayed on the ZTree window title bar, or with Alt+F1. This may come handy for script testing and debugging purposes.
Example	:: Use one or both of the following lines in your scripts echo Using #ZThome\#ZTexe, version #ZTversion :: This batch script was generated with: #ZThome\#ZTexe, version #ZTversion ...
ZTview	View the generated script file (#ZTtemp\ZTW_MENU.BAT) with the Viewer, instead of executing it.
Syntax	:: #ZTview
Description	A script debugging tool, but also useful for displaying scripts that contain pure text. Works exactly like the F9 Alt+V command.
ZTstart	Execute asynchronously the current script and pass any parameters to the START command.
Syntax	:: #ZTstart arg1 arg2 ...
Description	Asynchronous execution uses the START command (see START /?), thus allowing control to be returned to the the current ZTree process immediately. This is exactly how the F9 Alt-X (eXecute) command works. However, the #ZTstart directive also allows passing parameters to the START command, thus enhancing the Alt+X command. Ctrl+Enter will also honor the #ZTstart directive and force asynchronous execution, but the directive will be ignored if Enter is used to launch a script. The script will be run from a unique file named #ZTtemp\yyyymmddhhssmm-ZTW_MENU.BAT, thus allowing safe batch execution of many parallel batch jobs originating from ZTree. The contents of this batch file will look like this: @ECHO OFF ...script body... @DEL #ZTtemp\yyyymmddhhssmm-ZTW_MENU.BAT && EXIT
Example	:: #ZTstart "Compressing %1 with PKZIP..." /LOW /MIN :: If executed with Alt+X or Ctrl+Enter, this script will be run in :: a minimized window and with low priority. PKZIP -a %4_%5.ZIP %1
ZTexit	Forces exit from the Application Menu after current script's execution.
Syntax	:: #ZTexit
Description	Upon script execution, this directive unconditionally exits from the Application Menu and returns to the File or Directory window. Executing a script with Ctrl+Enter has the same effect. #ZTexit also saves the memory contents to the ZTW.ZAM disk file before exiting the Application Menu.