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:

• The maximum length of any task message is 255 characters.
• If the task message includes a single parameter with no spaces, such as a symbol name or a number, do not enclose it in quotation marks (" "). If the parameter is a text string, such as message text, enclose the string in quotation marks. For task messages that include two parameters, enclose both in one set of quotation marks; do not enclose each parameter individually in quotation marks. VUE$INQUIRE, which includes two parameters that might contain spaces, is an exception to this rule. In this case, enclose each parameter individually in quotation marks, and enclose them together within quotation marks.

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.

$!+ $! This FileView command file will prompt the user for a library name, $! create the library, and insert all currently selected files $! into it. $! $! If an error occurs, go to the handler, which displays Error status. $! $ on warning then goto error_occurred $! $! First, get the number of selected files. If none, pop up a message box, $! then exit. $! $ vue$get_selection_count $ vue$read element_count $ if element_count .ne. 0 then goto get_library_name $ vue$popup_message "You must select files first!" $ exit $! $! Get the library name. Use a symbol so that this name can be $! remembered across invocations of this menu item. If the library already $! exists, prompt for confirmation that it should be used. $! $get_library_name: $ vue$inquire_symbol "my_library_name Library name:" $ vue$read my_library_name $ vue$popup_progress_box $ if "''f$search(my_library_name)'" .eqs. "" then goto create_library $ vue$popup_confirm "Library already exists. Create new version?" $ vue$read response $ if "''response'" .eqs. "NO" then goto file_loop $! $! Create a new library. Set the task label indicating action, and $! highlight the Apply button showing a new file has been created. $! $create_library: $ vue$set_task_label "Creating library ''my_library_name'" $ library/create 'my_library_name $ vue$highlight_update $! $! Get the list of selected files, and insert each into the library. $! $file_loop: $ vue$get_next_selection $ vue$read insert_file $ if "''insert_file'" .eqs. "" then goto task_exit $ vue$set_task_label "Inserting ''f$parse(insert_file,,,"NAME")'" $ library 'my_library_name 'insert_file $ goto file_loop $! $error_occurred: $ vue$set_error_status $! $! Exit from the command procedure $! $task_exit: $ exit

15.4 Adding Target Screen Options to Application Menu Items

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.

This command procedure is from VUE$LIBRARY:VUE$BOOKREADER.

$ vue$get_symbol vue$show_hidden_dialogs (1) $ vue$read show_hidden_dialogs $ $ if show_hidden_dialogs then goto select_qualifiers (2) $ $ select_qualifiers: (3) $ vue$get_qualifiers $ goto do_bookreader $ select_qualifiers: $ vue$popup_qualifiers (4) $ $ do_bookreader: $ vue$read vue$common (5) $ $ if "''vue$command'".eqs. "DETACHED_APPLY" then goto select_qualifiers $ 'vue$command (6) $ bookreader:=sys$system:decw$bookreader.exe $ vue$get_next_selection (7) $ vue$read selection $ bookreader 'selection $ vue$check_verb_loop (8) $ vue$read loop $ if "''loop'" .eqs. "TRUE" then goto select_qualifiers

1. The symbol VUE$SHOW_HIDDEN_DIALOGS is true if the ellipsis after an item is selected; otherwise it is false.
2. If the user chose the ellipsis, the dialog box is displayed.
3. The user did not choose the ellipsis; retrieve any saved values and execute the command.
4. Display the dialog box and wait for the user to click on OK or Apply.
5. Have the command returned to FileView.
6. Execute the SET DISPLAY command.
7. If a file is selected, get it from FileView and pass it to Bookreader.
8. If the user clicked on Apply, then VUE$CHECK_VERB_LOOP is true. In this case, the command procedure wants to return control to the dialog box. If the user chooses the Detached setting and then clicks on Apply, control is returned to the dialog box.