SAS Companion for the OpenVMS Operating Environment

Using the SAS ToolBox

For all of the operating environments that the SAS System runs under, you can enter commands from many SAS windows. For information about commands that are available under OpenVMS, see Commands and the SAS commands section in the SAS online Help. On many hosts, including OpenVMS, you can use the SAS ToolBox command window to enter commands.

The SAS ToolBox has two parts, as illustrated in SAS ToolBox:

A command window that enables you to quickly enter any command.
A toolbar that contains several tool icons. When you select a tool icon, SAS immediately executes the command that is associated with that icon. The toolbar and the tool icons are completely customizable. (See Using the Tool Editor.)

SAS ToolBox

[IMAGE]

Under OpenVMS, the default ToolBox automatically appears at the bottom of the SAS windows by default. To control its configuration, you use the Preferences dialog box. (See Modifying the Toolbox and Command Window Settings.)

The name of the active window is displayed in the title bar of the toolbox. For example, if the Log window were active, the title bar would say ToolBox: Log instead of ToolBox: Program Editor.

If the toolbox is not displayed automatically when the SAS System initializes, it is due to one of the following reasons:

You executed your SAS job in a nonwindowing mode such as batch.
The SAS.defaultToolBox resource is set to False. The default value is True. For more information about the resources that control the toolbox, see Specifying Toolbox X Resources.
You deselected Display tools window in the Preferences dialog box. (See Using the Preferences Dialog Box to Modify X Resource Settings.)

If you invoke an application that does not have a toolbox that is supplied by the SAS System, then the default toolbox is displayed for that application. If you then customize the toolbox for that application, the customized toolbox is stored in SASUSER.PROFILE.<entry>.TOOLBOX, where <entry> is the same entry name as the PMENU entry for the application window.

Customizing Toolboxes and Toolsets

You can customize toolboxes

through the Preferences dialog box. The Preferences dialog box allows you to customize the appearance and behavior of toolboxes. For information about using the Preferences dialog box, see Using the Preferences Dialog Box to Modify X Resource Settings and Specifying Toolbox X Resources.
by specifying X resources in your resource file. For more information about X resources that affect toolboxes, see Specifying Toolbox X Resources.
through the Tool Editor dialog box. The Tool Editor allows you to customize the individual tools in a toolbox. For more information, see Using the Tool Editor.

The Tool Editor also allows you to create custom toolsets for your SAS applications. A toolset is a set of predefined tools that is associated with an application. Toolsets make it easier for individual users to customize their application toolboxes. If you create a toolset for an application, users can simply choose the tools they want to appear in their toolboxes and do not have to define the icons, commands, tip text, and IDs for those tools. For example, you can define a default toolbox for your application that includes tools for opening files, cutting, copying, and pasting text, and saving files. You can define a toolset that includes those tools and tools for opening the Preferences dialog box, opening the Replace dialog box, and entering the RECALL command. These additional tools will not appear in the users' toolbox unless a user adds them to their toolbox with the Tool Editor. You can view the TOOLSET contents by opening the Tool Editor dialog box and clicking on [Actions...], provided that the TOOLSET name has the same name as the TOOLBOX you are editing. For more information, see Changing an Existing Tool and Creating or Customizing an Application- or Window-Specific Toolset.

Specifying Toolbox X Resources

You can control the behavior of toolboxes with the following resources:

SAS.defaultToolBox: [True | False]: controls opening the default toolbox when the SAS System is invoked. The default is True.
SAS.isToolBoxPersistent: [True | False]: controls whether the toolbox stays open when you close the Program Editor window. The default value is True, which means that the toolbox remains open whenever you close the Program Editor window.
SAS.toolBoxAlwaysOnTop: [True | False]: controls whether the toolbox is always on top of the window stack. The default value is True, which may cause problems with window managers that are not Motif window managers or other applications that want to be on top of the window stack. If you have such a situation, set this resource to False.
SAS.toolBoxTipDelay: delay-in-milliseconds: sets the delay in milliseconds before displaying the toolbox tip. The default is 750.
SAS.useCommandToolBoxCombo: [True | False]: controls whether the command window and toolbox are joined or separated. The SAS.defaultToolBox and SAS.defaultCommandWindow resources control whether the toolbox and command window are displayed. If both are displayed, this resource controls whether they are joined or separated. The default is True.
SAS.useLargeToolBox: [True | False]: controls whether tool icons in the toolbox are displayed as 48x48 pixels or 24x24 pixels. The default is False (24x24 pixels).
SAS.useShowHideDecorations: [True | False]: controls whether the combined command/toolbox window has arrows at the left and right. You can use these arrows to hide or show portions of the window as they are needed. The default is False.
SAS.useToolBoxTips: [True | False]: determines if toolbox tip text is displayed. Some window managers, such as tvtwm, may place the toolbox tip behind the toolbox. If this happens in your environment, set this resource to False. The default is True.

Using the Tool Editor

The Tool Editor dialog box enables you to modify the contents and appearance of your toolboxes, as shown in Tool Editor Dialog Box. To invoke the Tool Editor dialog box, do one of the following:

From the Tools menu in the active window, select Options, and then select Edit Toolbox....
Issue the TOOLEDIT command in the command window (described in the command TOOLEDIT).
Click on the window menu button in the upper-left corner of the toolbox and select Edit Toolbox.... The Edit Toolbox... item is displayed when you use the Motif window manager. Contact your system administrator for more information about the Motif window manager.

Tool Editor Dialog Box

[IMAGE]

By default, the Tool Editor dialog box edits the current toolbox. To edit a different toolbox, invoke the Tool Editor dialog box and click on [Open...]. Then specify the libref, catalog, and entry name for the toolbox that you want to edit. Click on [OK].

After you invoke the Tool Editor dialog box, the toolbox goes into "preview mode." In preview mode, clicking on a tool icon makes that icon the current icon and displays its associated commands in the Command: field. The current icon always appears selected.

Changing the Appearance of the Entire ToolBox

The items in the ToolBox area of the Tool Editor dialog box affect the entire toolbox:

Name:: displays the catalog entry that you are editing. The default toolbox is named SASUSER.PROFILE.DMS.TOOLBOX.
Max tools per row:: specifies how the icons in the toolbox are arranged. The default size creates a horizontal toolbox. One tool per row creates a vertical toolbox.

Changing an Existing Tool

When you open the Tool Editor dialog box, the first icon in the toolbox is the current icon (the icon appears selected), and its information appears in the Button: area of the dialog box. To change an existing tool, you can select a tool from the toolset displayed by clicking on [Actions...] or you can modify the fields individually.

Note: Clicking on [Actions...] will display a toolset only if a toolset is associated with (has the same entry name as) the toolbox that you are editing. For more information, see Saving Changes to the Toolbox or Toolset. [cautionend]

To use [Actions...], select the tool that you want to change, and then select [Actions...]. The Tool Editor displays the toolset associated with the toolbox. If you select a tool from this toolset, the Tool Editor enters the appropriate information into the button fields for you.

To modify the fields individually, perform the following steps:

Select the icon you want to change.
Click in and change the Button: area fields as appropriate:

Command:

specifies the SAS windowing environment command or commands that you want executed when you select the icon. You can use any SAS command that is available under OpenVMS. For information about commands, see Commands and the SAS commands section in the SAS online Help. For example, you could create an icon to open the Change Directory dialog box by using the DLGCDIR command, which is described in DLGCDIR.
Separate commands with a semicolon (;).

Help Text:

is used for applications that are designed to be run under Microsoft Windows or OS/2. The help text is displayed in the SAS windowing environment status line on Windows and OS/2 when a toolbox is ported to and loaded on those operating environments.

Tip Text:

specifies the text that is displayed when you position the cursor over the icon.

Id:

is useful if you are creating toolboxes for SAS/AF applications. The ID is the identifier of the corresponding menu item in the application. This number is the value assigned to the item in the ID option of the ITEM statement in PROC PMENU. If you specify an ID, then the application can set the state of the PMENU item to match the state of the tool in the toolbox, and it can make the PMENU item active or inactive to match whether the PMENU item is active or inactive. If you do not specify an ID, the ID defaults to 0.
Change the icon if necessary:
1. Click on [Icon...] or double-click on an icon in the preview toolbox. The Select a Pixmap dialog box opens, which displays the icons provided with the SAS System. These icons are divided into several categories such as SAS windows; data; analysis; numbers and symbols; files, folders, and reports; and so on. To change categories, click on the arrow to the right of the Icon Category field and select a new category.
2. Select the icon you want to use and then click on [OK].
3. Save your changes as described in Saving Changes to the Toolbox or Toolset.

Adding Tool Icons to the Toolbox

To add an icon to the toolbox, perform the following steps:

Select the icon that is adjacent to where you want to add the new tool icon.
Click on [Add before] or [Add after], whichever is appropriate. The Toolbox Editor adds a new icon (labeled SAS) to the toolbox and clears the Button: area fields.
Enter the appropriate information in the Button: area fields. These fields are described in Changing an Existing Tool.
Change the icon, if desired, as described in Changing an Existing Tool.
Save your changes as described in Saving Changes to the Toolbox or Toolset.

Changing the Order of the Icons in the Toolbox

To change the position of a tool in the toolbox, select the icon, and then click on the left or right arrows in the Button: area to move the icon.

Deleting Tool Icons from the Toolbox

To delete a tool icon from the toolbox:

Select the icon that you want to delete.
Click on [Delete] in the Button: area.
Save your changes, as described in Saving Changes to the Toolbox or Toolset.

Returning to the Default Settings

To return all tools in the current toolbox to their default settings, click on [Defaults...] at the bottom of the Tool Editor dialog box. When you make this selection, any customizations that you have made are lost. It also deletes any icons that you have added to the toolbox. The Tool Editor dialog box asks you to verify your request. Click on [Yes] to restore the default settings, [No] to keep your customizations, or [Cancel] to do neither.

Saving Changes to the Toolbox or Toolset

You can save the changes to the catalog entry that is displayed in the Name: field of the Tool Editor dialog box, or you can create a new toolbox with a different name.

Note: If you are customizing a window-specific or application-specific toolbox for your personal use, save the customized toolbox in your SASUSER.PROFILE catalog by using the same entry name as the PMENU entry for the window or application. The SAS System searches for toolboxes first in SASUSER.PROFILE and then in the application catalog. [cautionend]

Click on [Save] or [Save as ...] to perform the following tasks:

[Save]

saves the toolbox information to the catalog entry shown in the Name: field.

[Save as...]

causes the Tool Editor dialog box to prompt you to enter a different libref, catalog, and entry name. The entry type for a toolbox is always TOOLBOX.

You can also choose to save the toolbox as a toolset. If you save the toolbox as a toolset, the entry type will be TOOLSET; otherwise, the entry type is always TOOLBOX. Saving a set of tools as a TOOLSET does not change your TOOLBOX entry. For more information about toolsets, see Customizing Toolboxes and Toolsets and Creating or Customizing an Application- or Window-Specific Toolset.

If you click on [Close] or [Open...] without first saving your changes, the Tool Editor dialog box prompts you to save the changes to the current toolbox before continuing. Click on [Yes] to save your changes; click on [No] to ignore any changes you made; or click on [Cancel] to do neither.

After you save the toolbox or toolset, the Tool Editor remains open for additional editing, and the Name: field changes to the name of the new entry (if you entered a new name).

Note: To SAS/AF application developers or site administrators: If you are editing a window-specific or application-specific toolbox that you want to be accessible to all users, you must save the TOOLBOX entry with the same library, catalog, and entry name as the PMENU entry for the window or application. You need WRITE access to the appropriate location. For example, to store a customized toolbox for the graphics editor, the site administrator would store the toolbox in SASHELP.GI.GEDIT.TOOLBOX. [cautionend]

Creating a New ToolBox

To create a new toolbox, you do one of the following:

Edit an existing toolbox by invoking the Tool Editor dialog box (from the Tools menu in the active window, select Options, and then select Edit Toolbox...) and making your changes. Then save the edited toolbox, as described in Saving Changes to the Toolbox or Toolset.
Copy an existing TOOLBOX entry. You can copy a toolbox by opening the CATALOG window, specifying the appropriate catalog, and then entering the COPYITEM command. For example, to copy the default toolbox, enter the following commands in the command window:
```
catalog sasuser.profile
   copyitem dms.toolbox
            newtools.toolbox
```

Next, edit the new toolbox by using the Tool Editor dialog box (from the Tools menu in the active window, select Options, and then select Edit Toolbox...). Click on [Open...]. Then specify the libref, catalog, and entry name of the new toolbox. Click on [OK] to create the new toolbox.

Loading a Different ToolBox

To load a toolbox, issue the TOOLLOAD command in the command window:

TOOLLOAD <libref.catalog.entry>

Creating or Customizing an Application- or Window-Specific ToolBox

If you are an application developer and want to create or edit an application TOOLBOX, follow these steps:

Delete any existing TOOLBOX entry in your SASUSER.PROFILE for the window or application that you want to customize. When you delete the copy of the toolbox in your SASUSER.PROFILE catalog, you automatically receive a copy of the toolbox that is supplied with the SAS System when you invoke the Tool Editor dialog box.
Create or edit the application toolbox, as described in Creating a New ToolBox or Using the Tool Editor.
Save the edited toolbox, as described in Saving Changes to the Toolbox or Toolset.
Inform your users that you have changed the window or application toolbox. If they want to use the new toolbox, they must delete the corresponding TOOLBOX entry from their SASUSER.PROFILE. The new toolbox will then be automatically loaded when the window or application is invoked. If users do not delete the corresponding TOOLBOX entry from their SASUSER.PROFILE catalog, that copy of the toolbox will be loaded instead of the new toolbox.

Creating or Customizing an Application- or Window-Specific Toolset

You define application- or window-specific toolsets in the same way that you create an application- or window-specific toolbox. There are only two differences:

To create a new toolset, start by defining a toolbox as described in Creating a New ToolBox.
After you have defined the toolbox, save it as a TOOLSET entry, not as a TOOLBOX entry.

Note: If you are an application developer, make sure that you delete an existing TOOLSET entry for your application as described in Creating or Customizing an Application- or Window-Specific ToolBox before you modify your application's toolset. [cautionend]

Chapter Contents
Previous
Next
Top of Page