Adding TSO commands to menus with Menu Manager

Menu Manager lets you create actions that specify programming and user interfaces.

To create an action:

1. In the left pane of the Preferences window, double-click Menu Manager, and click Actions and Menus.
   The Actions and Menus panel opens.
2. Do one of the following steps:
   • From the File Selection list, select the file that you want to create the action in.
   • To create a file for the action, click New.
   • To import a file for the action, click Import.
3. On the Actions tab of the Actions and Menus panel, click New Local/Remote Action.
   The Menu Manager New Action Wizard opens.
4. In the New Action Page panel, complete the following steps:
   1. In the Name field, type the name that you want to be displayed for the action in the pop-up menu.
   2. Optional: In the Comment field, type a short description that you want to be displayed as tooltip text when you hover over this action in the pop-up menu.
   3. In the Context drop-down list, select from the context in which this action is visible.
      For example, if you choose z/OS UNIX Subprojects, this action shows up only on z/OS UNIX System Services files. If you choose MVS files in z/OS Projects, this action shows up only for data sets within an MVS file in a z/OS project. The default is All.
      Note: Depending on the context that is chosen, properties that are available on subsequent panels of the new action wizard might be different.
   4. Click Next.
      The File Associations panel opens.
5. In the File Associations panel, complete the following steps:
   1. To select the file types to associate with this file action, do one of the following steps:
      • To select all the listed file types, click Add All.
      • Select the file type that you want to associate with the file action and click Add.
      • To select all files that contain a file-name extension, select *.* and click Add.

      Restriction: The simple local file action that you create is displayed on the pop-up menu only if each of the selected files corresponds to an associated file type specified in the File Associations panel.
   2. Optional: To add a file type to the list of associated file types:
      1. Click File Types. The File Type Manager panel opens.
      2. In the Existing Types section, click Add. The New File Type Information panel opens.
      3. In the Enter File Extension field, type the file name extension for the file type that you want to add to the list, and then click OK.
      4. Click Finish.
   3. Optional: To remove a file type from the list of associated file types:
      1. Click File Types. The File Type Manager panel opens.
      2. In the Existing Types section, select a file type, and click Remove.
      3. Click Finish.
   4. Click Next.
      The Data Set Filters panel opens.
6. In the Data Set Filters panel, complete the following steps:
   1. Optional: To add a data-set filter, type a filter pattern, for example, INPT*, in the Data set filter field, and click Add.
   2. Optional: To remove a data-set filter, select a data-set filter, and click Remove.
   3. Click Next.
      The Run Options panel opens.
7. On the Basic tab of the Run Options panel, complete the following steps:
   1. Optional: To specify the command string that is run when this action is selected from a pop-up menu, do any of the following steps:
      • In the Command field, type the command string.
      • To browse for the location of a file on the local system that you want to include in the command string, click Browse.
        Tip: Browse is disabled when the Remote Command check box is selected.
      • To open the Substitution Variables window, click Variables. If you chose All in the New Action Page panel, select the context in which you want the command to run. The list of substitution variables depends on the context that you choose. The Substitution Variables window gives a description of each variable. Select a variable that you want to add to the command string. Click Insert > Close. The substitution variable is added to the Command field.
        Tip: When you select substitution variables to add to the command string, ensure that you select variables from the context in which the action is displayed on the pop-up menu.
   2. Optional: In the Action Properties section to display the action on the generic menu, select Show on generic menu.
      Note: If you do not select Show on generic menu, you must add the action to a menu and attach that menu to one or more resources. The action is displayed in the custom portion of the pop-up menu.
   3. Optional: To specify that you want output from the action to be displayed in a window instead of in the Console, select Show output in dialog.
      Note: To modify colors and fonts for the output dialog, open the Preferences window, and select General > Appearance > Colors and Fonts. Edit the options under the Menu Manager category.
   4. Optional: If you want to view an acknowledgment dialog when the menu manager action is selected, select Show acknowledgment dialog.
   5. In the z/OS UNIX Subprojects context, if you did not specify the command string that is run when this action is selected from a pop-up menu, you must reference an existing IAction:
      1. To use an action that is implemented as a Java™ class, select Use existing action.
      2. To open the Action Selection window, click Select.
      3. From the list of actions, select the ID of the IAction class that is called for this action. This list of actions is populated with actions that are contributed by using the com.ibm.tpf.menumanager.actions extension point. For example, com.ibm.tpf.core.make.ui.actions.LoadTPFAction.
      4. Click OK. The selected action is displayed in the ID field.
   6. In the z/OS UNIX Subprojects context or the MVS Subprojects context, to specify that you want the action to run in the foreground, select Run action in foreground.
      Tip: If the action references an existing IAction, this check box is disabled. The IAction determines whether the action runs in the foreground.
      If you select the check box, the action runs in the foreground and the main GUI is locked. To unlock the GUI and stop the execution of the action, click Cancel.
   7. To configure a remote command script:
      1. To open the Script Configuration panel, select the Remote Command check box, and then click Script Configuration.
      2. To indicate the types of files that you want to include in the remote command script, select the applicable check boxes. For example, Header, Command Header, Command Footer, and Footer.
      3. To select the files that you want to include in the remote command script, complete the following steps for each file type that you select:
         1. Type the name of the file that you want to include in the remote command script in the corresponding Filename field.
         2. Click the corresponding Variables button to open the Substitution Variables window. If you chose All in the New Action Page panel, select the context in which you want the command to run. The list of substitution variables depends on the context that you choose. The Substitution Variables window gives a description of each variable. Select the variables that you want to add to the Export Variables field. Click Insert > Close. The substitution variables are added to the Export Variables field.
            Tip: By default, export variables are enclosed in double quotation marks. If you want an export variable to be enclosed in single quotation marks, you must type single quotation marks around the variable.
            The variables in the Export Variables field are exported in the remote command script with a BBS_ prefix. For example, &RN is exported as BBS_RN. You can reference these variables in your header or footer files. Interactive substitution variables are not supported.
      4. To save the configuration information and close the Script Configuration panel, click OK.
   8. Optional: If this simple remote file action generates an events file in the same format as the z/OS compiler, select the Events File check box. Type the name of the generated events file or to browse for the location of the events file, click Browse.
      Tip: To base the events file name on the selected file name, type &RN.evt.
      The remote file action parses the events file, and then populates the Remote Error List with the messages contained in the events file.
   9. Optional: In the z/OS UNIX Subprojects context, to run a user exit program locally before you run a remote command:
      1. Select the User Exit check box.
      2. Type the path of the local program that you want to run as the user exit, or, to browse for the program, click Browse.
      The remote command script is passed to the program during the user exit. A user exit program can verify the contents of the remote command script and apply any required changes before the command runs on a remote system.
   10. Do one of the following actions:
       • To go to the next step, click the Advanced tab.
       • To skip the next step and go to the Add Actions To Menus panel, click Next.
       • To skip the next step and create the action, click Finish.
8. Optional: On the Advanced tab of the Run Options panel, complete the following steps:
   1. Optional: In the Clear console section, specify whether you want to clear the console before you run this action:
      • To use the default setting that is specified on the Menu Manager preferences window, click Use preference setting.
      • To override the default setting that is specified on the Menu Manager preferences window, click Use custom setting . To specify your custom setting to clear the console before you run the action, select Clear console before running.

      By default, messages that are generated when an action runs are appended to existing messages that are displayed in the Console view.
   2. Optional: In the z/OS UNIX Subprojects context, in the Additional action properties section to refresh the project or subproject when the action completes, select Refresh enclosing projects on action completion.
      The project is refreshed regardless of whether the action completes successfully or fails.
   3. Optional: To collect all of the file names together and run the command once for the set of selected files, select the Collect Names check box; to run the command for each selected file, clear the check box.
   4. Optional: To verify that the length of the command does not exceed the specified limit, select the Length Limit check box. Type the value of the maximum allowable command length in the Length Limit field.
      Note: If you do not select the Length Limit check box, the length of the command is unlimited.
      If the command exceeds the maximum length, it is not run.
   5. Click Next.
      The Add Actions To Menus panel opens.
9. Optional: In the Add Actions To Menus panel, complete the following steps:
   1. Click Add to menus. Then select the check box for each menu that you want to add the action to, or click Select All.
   2. To change your selections, clear check boxes or click Deselect All.
   3. Click Finish.
      The action is added to the list of actions on the Actions tab.
10. After the menu item is added to the menu, use the Menu Selection preference page to select the menu as the base file, the default file menu, or both. To access the Menu Selection preference page, open the Preferences window, and select Menu Manager > Menu Selection.

Complete one of the following steps:

• If your application does not support automated sign-on, the format of the command is just the URL of the HATS application. For example: HATSRCP=appname where appname is the name of the HATS rich client application. Or, if the application has parameters, the command might be similar to the following example: HATSPCP=appname hatsgv_userid hatsgv_password
• If your application does support automated sign-on, specify the name of the variables for the user ID and password that are to be added to the HATS command. For HATS, the global variables are specified in the following format on the HATS command: HATSPCP=appname hatsgv_userid hatsgv_password
  In addition to the user ID and password parameters, you can also specify additional parameters to be passed to HATS. In this example, the HATS Web application is invoked and the user ID and password are passed. Additionally, three other parameters (hatsgv_var1, hatsgv_var2, and hatsgv_var3) are passed, along with their corresponding values. More than three parameters can be passed.

  HATSRCP=HCmvs211Parms hatsgv_userid hatsgv_password hatsgv_var1=value1 hatsgv_var2=value2 hatsgv_var3=value3
  

• If your application does support automated signon, Developer for z/OS substitutes your user ID and password, if you specify the name of the variables for the user ID and password that are to be added to the HATS command.
  For HATS, the global variables are specified in the following format on the HATS command:

  http://hostname/appname/?parameter1=one hatsgv_userid hatsgv_password 

  There must be a space between the HATSRCP=appname and hatsgv_userid and between hatsgv_userid and hatsgv_password. The name of the global variables for user ID and password are not important (except that HATS does require the hatsgv_ prefix to know that a specified parameter is a global variable). What is important is that hastgv_userid is interpreted as the user ID and hatsgv_password will be interpreted as the password.

  In addition to the user ID and password parameters, you can also specify additional parameters to be passed to HATS. In this example, the HATS web application is started and the user ID and password are passed. Additionally, three other parameters (hatsgv_var1, hatsgv_var2, and hatsgv_var3) are passed, along with their corresponding values. More than three parameters can be passed.

  http://hostURL/myapp?tabs1=structures hatsgv_userid hatsgv_password var1=value1 var2=value2 var3=value3
  

  The following URL results from this example:

  http://hostURL/myapp?tabs1=structures&hatsgv_userid=userid&hatsgv_password=password&var1=value1&var2=value2&var3=value3
  

  For the web interface, the URL specified in the command can be with or without parameters in the URL itself. Host Connection Emulator correctly detects the presence or absence of parameters and adjusts accordingly. For example, without any parameters the following URL is generated:

  http://hostURL/myapp hatsgv_userid hatsgv_password var1=value1 var2=value2 var3=value3
  

  With parameters, the following URL is generated:

  http://hostURL/myapp?tabs1=structures&oneparm=good hatsgv_userid hatsgv_password var1=value1 var2=value2 var3=value3
  

To change an existing action definition:

1. Right-click the action that you want to change, and select Edit.
   A Properties window opens.
2. Select one of the following options:
   • Data Set Filters
   • File Associations
   • General
   • Override Info
   • Run Options
   The panel for that option is displayed.
3. Change the settings in the panel.
4. Optional: Repeat the previous two steps.
5. Click OK to save your changes or Cancel to undo your changes.