ZTree Application Menu (F9) Directives

[UP] Macros Application Menu Configuring

  1. Application Menu directives:
  2. Directives reference:
  3. 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.

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.

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!

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=*
:: 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
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)
REM #ZTinclude SET RUN=START "Running from ZTree"
%RUN% MyProg.EXE
REM Save this file, for whatever reason...
Example REM This program may produce error messages that you want to see
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...
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)
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%
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
:: 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
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:\
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
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
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"
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:
...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.

ZTree Internal Use Only. Updated: 20060822
Copyright 2004 vujnovic@free.fr. All rights reserved.