When you define your own menu items and add them to Session Manager's
or FileView's menus, your menu items can invoke simple DCL commands
(for example, SHOW USERS) or command files that execute any number of
commands. However, if you want to make your menu items work more like
built-in menu items, you can include task messages
into your command files. Task messages are special symbols that you use
the same way you use DCL commands. For example, you can use task
messages to create a menu item that displays a corresponding dialog box.
This chapter describes Session Manager and FileView task messages and
explains how to use them. It also includes a sample command file that
shows how task messages work.
15.1 Using Task Messages in Command Files
Some built-in menu items invoke command files to execute a series of
commands. Each command file uses task messages to pass information
between Session Manager or FileView and the VMS subprocesses that
process tasks. This information includes files currently selected in
the file list and the status of the current task. Task messages also
instruct Session Manager and FileView to display a corresponding dialog
box or error message.
Task messages consist of text strings that are sent on I/O channels
called VUE$INPUT and VUE$OUTPUT. Subprocesses write messages to
VUE$OUTPUT, which Session Manager or FileView reads. For some message
types, Session Manager or FileView responds by writing messages to
VUE$INPUT, which the subprocess reads. For each task message, Session
Manager or FileView defines a DCL symbol that command files can use to
send the message. When DCL encounters this symbol in a command file, it
writes the message flag and any parameters you specify to VUE$OUTPUT.
The VUE$INPUT and VUE$OUTPUT channels are already opened in the
subprocess when your command file is invoked. You don't need to open or
close them.
You do not need to open SYS$INPUT and SYS$OUTPUT channels in your
command files. Specifically, your command files can prompt you by
including the DCL command INQUIRE, if necessary, or can run programs
that perform terminal I/O. When Session Manager and FileView detect
that text has been written to SYS$OUTPUT, they respond by assigning and
displaying a Task Output box that behaves like a terminal.
Note the following guidelines when using task messages in your command
files:
VUE$EXIT_COMMAND_LOOP
The VUE$EXIT_COMMAND_LOOP message notifies Session Manager or FileView
that the command procedure is about to exit the normal DCL command loop
by executing the DCL command STOP. If a command procedure executes the
DCL command STOP without first sending a VUE$EXIT_COMMAND_LOOP message,
the subprocess is not properly reused. The combination of
VUE$EXIT_COMMAND_LOOP and STOP is used only to obtain a Task Output
window in which you can interact directly with the DCL command line.
DCL format: VUE$EXIT_COMMAND_LOOP
VUE$GET_ALL_SELECTIONS
The VUE$GET_ALL_SELECTIONS message requests that Session Manager or
FileView return the names of all selected files in the current view as
a list whose components are separated by commas. Follow
VUE$GET_ALL_SELECTIONS with VUE$READ to allow the subprocess to receive
the returned file name list.
DCL format: VUE$GET_ALL_SELECTIONS
VUE$GET_NEXT_SELECTION
The VUE$GET_NEXT_SELECTION message requests that Session Manager or
FileView return the name of the next selected file in the current view.
VUE$GET_NEXT_SELECTION can be used iteratively to get the name of each
file that was selected when the task began. After the last file name is
returned, Session Manager or FileView returns an empty string. Follow
VUE$GET_NEXT_SELECTION with VUE$READ to allow the subprocess to receive
the returned file name.
DCL format: VUE$GET_NEXT_SELECTION
VUE$GET_QUALIFIERS
The VUE$GET_QUALIFIERS message requests that Session Manager or
FileView return a SET DISPLAY command with the parameters for the
current item to the subprocess. If a user selects Detached, the
subprocess terminates, and Session Manager or FileView reexecutes the
command file in a new detached process.
DCL format: VUE$GET_QUALIFIERS
VUE$GET_SELECTION_COUNT
The VUE$GET_SELECTION_COUNT message requests that Session Manager or
FileView return the number of selected files in the current view.
Follow VUE$GET_SELECTION_COUNT with VUE$READ to allow the subprocess to
receive the returned count.
DCL format: VUE$GET_SELECTION_COUNT
VUE$GET_SYMBOL
The VUE$GET_SYMBOL message requests that Session Manager or FileView
return the value of the specified symbol previously set by
VUE$SET_SYMBOL. Follow VUE$GET_SYMBOL with VUE$READ to allow the
subprocess to receive the returned value.
You can also use VUE$GET_SYMBOL to query the special DCL symbol
VUE$SHOW_HIDDEN_DIALOGS. Many built-in commands allow you to hide the
associated dialog box by highlighting the Hide this Dialog check button
in the command's dialog box. You can then force the box to appear by
choosing the command while pressing and holding the Shift key. If you
began the task while pressing and holding the Shift key, VUE$GET_SYMBOL
returns TRUE for the value of VUE$SHOW_HIDDEN_DIALOGS. This allows your
command files to provide a similar ellipsis feature that you can
override when you choose the command from a menu while pressing the
Shift key.
DCL format: VUE$GET_SYMBOL symbol
Example: VUE$GET_SYMBOL MY_LIBRARY
VUE$HIGHLIGHT_UPDATE
The VUE$HIGHLIGHT_UPDATE message requests that Session Manager or
FileView highlight the Apply button in the Session Manager or FileView
window by changing its label from Apply to Update. (The Update button
is used to remind you that there might have been a change to the files
in the current file list.) When you click on the Update button, the
label returns to Apply.
DCL format: VUE$HIGHLIGHT_UPDATE
VUE$INQUIRE
The VUE$INQUIRE message requests that Session Manager or FileView
display a dialog box prompting you for input text. The message includes
the prompt to be used, as well as the initial value to be placed in the
text entry box. When you click on the OK button in the dialog box, the
text is returned to the subprocess in VUE$INPUT. If you click on the
Cancel button in the dialog box, a null string is returned. Follow
VUE$INQUIRE with VUE$READ to allow the subprocess to receive the
returned text string.
Because the prompt parameter might contain spaces, be sure to enclose
both the prompt parameter and the initial text string in quotation
marks.
DCL format: VUE$INQUIRE prompt
initial-text
Example: VUE$INQUIRE """Show
file:"" ""''current_default'"""
VUE$INQUIRE_SYMBOL
The VUE$INQUIRE_SYMBOL message requests that Session Manager or
FileView display a dialog box prompting you for input text. The message
includes the prompt to be used and a symbol name. The symbol is
translated by Session Manager or FileView, and the current value is
used as the initial value in the text entry box. When you click on the
OK button in the dialog box, the symbol is redefined using the text you
entered, and the text is returned to the subprocess in VUE$INPUT. If
you click on the Cancel button in the dialog box, a null string is
returned. Follow VUE$INQUIRE_SYMBOL with VUE$READ to allow the
subprocess to receive the returned text string.
DCL format: VUE$INQUIRE_SYMBOL symbol
prompt
Example: VUE$INQUIRE_SYMBOL "MY_LIBRARY
Library:"
VUE$POPDOWN
The VUE$POPDOWN message instructs Session Manager or FileView to pop
down the Task Output box for this task, if it is displayed.
DCL format: VUE$POPDOWN
VUE$POPUP
The VUE$POPUP message instructs Session Manager or FileView to display
the Task Output box for this task, if it is not already displayed. The
Task Output box does not take input focus when it appears. Note that
the Task Output box pops up automatically when output is written to
SYS$OUTPUT. You can use this task message to force the box to appear
sooner.
DCL format: VUE$POPUP
VUE$POPUP_CONFIRM
The VUE$POPUP_CONFIRM message requests that Session Manager or FileView
pop up a confirmation box containing the specified text. The box
contains two command buttons labeled Yes and No, which allow you to
respond appropriately. Session Manager or FileView then returns either
"YES" or "NO" in VUE$INPUT. Follow
VUE$POPUP_CONFIRM with VUE$READ to allow the subprocess to receive the
returned text string. You may separate the text on multiple lines by
including the line feed (ASCII 10) character.
DCL format: VUE$POPUP_CONFIRM message
Example: VUE$POPUP_CONFIRM "File was not found.
Continue?"
VUE$POPUP_FOCUS
The VUE$POPUP_FOCUS message instructs Session Manager or FileView to
pop up the Task Output box for this task, if it is not already
displayed. The Task Output box takes input focus when it appears.
Though the Task Output box pops up automatically when output is written
to SYS$OUTPUT, it does not normally take input focus.
DCL format: VUE$POPUP_FOCUS
VUE$POPUP_HELP
The VUE$POPUP_HELP message requests that Session Manager or FileView
pop up a Help dialog box displaying help text from the specified
library on the specified topic. If Session Manager or FileView cannot
open the file or if the topic is not found, an error message dialog box
is displayed.
DCL format: VUE$POPUP_HELP library
topic
Example: VUE$POPUP_HELP
"SYS$HELP:DECW$SESSION.HLB Overview"
VUE$POPUP_MESSAGE
The VUE$POPUP_MESSAGE message requests that Session Manager or FileView
pop up a message box containing the specified text. The box also
contains an Acknowledge button, which allows you to dismiss the box.
You can separate the text on multiple lines by including the line-feed
(ASCII 10) character.
DCL format: VUE$POPUP_MESSAGE message
Example: VUE$POPUP_MESSAGE "Library build is
complete."
VUE$POPUP_QUALIFIERS
The VUE$POPUP_QUALIFIERS message requests that Session Manager or
FileView pop up a dialog box containing text entry boxes to change the
display and an option box to change how applications run. The current
settings for the command are shown in the dialog box.
When you click on OK or Apply, a SET DISPLAY command with the selected
parameters is returned to the subprocess. If a user selects Detached,
the subprocess terminates and Session Manager or FileView reexecutes
the command file in a new detached process. If a user selects Detached
and then clicks on Apply, the string DETACHED_APPLY is returned instead
of the SET DISPLAY command.
DCL format: VUE$POPUP_QUALIFIERS
VUE$POPUP_PROGRESS_BOX
The VUE$POPUP_PROGRESS_BOX message requests that Session Manager or
FileView pop up the Work in Progress dialog box, if it is not already
displayed. This box allows an optional time value, representing a
number of seconds, to be specified. If this task message is included,
the box is displayed only for the specified number of seconds and then
is automatically dismissed, unless some other entry prevents it. Also,
the task status is shown as "Starting" in the Work in
Progress dialog box if the timer is included.
You can use this task message to provide feedback that a task is
starting before the task produces any visible results. If a time value
is not included, the Work in Progress dialog box is automatically
dismissed when the current task completes, unless another entry
prevents it.
DCL format: VUE$POPUP_PROGRESS_BOX
optional-time
Example: VUE$POPUP_PROGRESS_BOX 10
VUE$READ
VUE$READ is the mechanism for receiving a value that Session Manager or
FileView returns as a result of a previous message you sent. It reads
the next record from VUE$INPUT into a symbol you specify.
For example, VUE$READ is used to read the file name returned after a
VUE$GET_NEXT_SELECTION message is sent.
DCL format: VUE$READ symbol
Example: VUE$READ NEXT_SELECTION
VUE$RESET_SELECTIONS
VUE$RESET_SELECTIONS instructs Session Manager or FileView to reset its
internal pointers to the selected file list. Normally, a task command
file iterates through the list of selected files by repeatedly calling
VUE$GET_NEXT_SELECTION. VUE$RESET_SELECTIONS allows the task to iterate
through the list again.
DCL format: VUE$RESET_SELECTIONS
VUE$SET_DONE_LABEL
The VUE$SET_DONE_LABEL message requests that Session Manager or
FileView change the label for this task to the specified text when the
task is complete. This message has no effect until the task completes.
DCL format: VUE$SET_DONE_LABEL label
Example: VUE$SET_DONE_LABEL "Library build
complete"
VUE$SET_ERROR_STATUS
The VUE$SET_ERROR_STATUS message requests that Session Manager or
FileView set the "Error" flag in the Work in Progress dialog
box entry for the current task.
DCL format: VUE$SET_ERROR_STATUS
VUE$SET_OUTPUT_TITLE
VUE$SET_OUTPUT_TITLE allows the task to specify a new title for its
Task Output box. By default, Session Manager or FileView uses the menu
item name that invoked the task as the title.
DCL format: VUE$SET_OUTPUT_TITLE
VUE$SET_SYMBOL
The VUE$SET_SYMBOL message requests that Session Manager or FileView
store a value for the specified symbol in order to reuse it later. This
mechanism allows Session Manager or FileView tasks, which are run as
subprocesses, to share the same value for a symbol or to preserve a
symbol across invocations of the same menu item. Defining a DCL symbol
in your command file does not have the same effect because it might be
run in a different subprocess the next time the command file is invoked.
DCL format: VUE$SET_SYMBOL symbol-value
Example: VUE$SET_SYMBOL "MY_LIBRARY
WORK:[JONES.LIBRARY]"
VUE$SET_TASK_LABEL
The VUE$SET_TASK_LABEL message requests that Session Manager or
FileView change the label for this task in the Work in Progress dialog
box and in the Task Output box, if one exists.
DCL format: VUE$SET_TASK_LABEL label
Example: VUE$SET_TASK_LABEL "Copying
''current_file'"
VUE$SUPPRESS_FILE_LABEL
VUE$SUPPRESS_FILE_LABEL allows a task to specify that the file labels
be omitted from its Task Output box, even if the task has requested
information about the file list.
DCL format: VUE$SUPPRESS_FILE_LABEL
VUE$SUPPRESS_OUTPUT_POPUP
The VUE$SUPPRESS_OUTPUT_POPUP message requests that Session Manager or
FileView not automatically display a Task Output box when the task
produces terminal output. You can use this task message for graphic
applications that are expected to produce output only in case of errors.
DCL format: VUE$SUPPRESS_OUTPUT_POPUP
VUE$UPDATE_FILEVIEW
The VUE$UPDATE_FILEVIEW message requests that Session Manager or
FileView automatically update the Session Manager or FileView window,
as if you had clicked on the Apply button. Use this task message with
caution because it might disrupt any interaction in progress, such as
extending a file selection.
DCL format: VUE$UPDATE_FILEVIEW
The following sample command file illustrates how to include task
messages in a FileView command file. You can define a menu item Create
Library, add it to the FileView Files menu, and associate it with this
command file to create a library in which you can store frequently used
modules of code or text.
To add Target Screen options to a user-defined menu item, modify the
command procedure that invokes the application as shown in the
following example. Your application must be invoked from a command file
to use the qualifier dialog box feature.