For any browser class, only one menu can be explicitly scoped to the toolbar or pop-up menu. (See “Fast Menu Scope” to learn how to create a pull-down menu that can be appended to the toolbar.) If you choose to replace a browser's toolbar or pop-up menu, follow the procedure described in “Replacing an Existing Menu”. If you depart from this procedure, and use a group file with a different name than the standard menu, make sure the new file name sorts ahead of the existing one; xclearcase ASCII-sorts group files when it first reads them in.

The Fast scope is compatible only with menu type pulldown; Fast:popup and Fast:toolbar scopes have no effect.

The Fast menu appears only on the file browser that comes up when you execute xclearcase. It does not appear at all if no menu is scoped to it. If you close the original file browser, the Fast menu is lost for the duration of the xclearcase session (even if you start a new file browser with the Filet -> New file browser option on another browser).

The Fast menu's distinguishing feature is the Static menu option that is prepended to each menu scoped there. You can set the Static menu option to duplicate a menu as a set of “fast access” buttons below the file browser's iconic toolbar. (You could scope your “fast access” menu to File:toolbar, but since only one group file can be scoped to a browser's toolbar, the standard iconic toolbar would be displaced.)

Typical usage — “Pick and choose” a set of commonly used menu items from elsewhere in the interface, and collect them together as a “fast access” menu scoped to Fast:pulldown. When constructing the “fast access” menu, use the f.alias function to clone menu items that reside elsewhere in the interface.

Figure 18-5, Figure 18-6, Figure 18-7, and Figure 18-8 illustrate the results of scoping group files, respectively, to File:pulldown, File:toolbar, File:popup, and Fast:pulldown.

Figure 18-5. Basic Menu Scoped to File:pulldown

Note that it is the file name, not the menu name, that determines where in the menubar the View menu appears.

Figure 18-6. Basic Menu Scoped to File:toolbar

Figure 18-7. View Menu Scoped to File:popup

Figure 18-8. View Menu Scoped to Fast:pulldown

f.alias "groupFileLeafName/menuSpecifier/itemLabel"

Duplicates an existing menu item from another group file. An “aliased” item inherits the following characteristics from an existing menu item definition:

example as shown in Figure 18-9 (from file_popup.grp)

Figure 18-9. f.alias Example

---

Note: The menu name root in the second example. Use root if the menu item is defined in the target group file's RootMenu.

---

You cannot override f-dot functions in the alias definition. Also, an f.alias function cannot be combined with other f-dot functions.

f.call "builtinFunction"

Calls one of the built-in xclearcase functions. Many of these calls toggle browser display parameters. (See /usr/atria/config/ui/grp/file_pulldown_G_options.grp, for example).

There are also calls to invoke or “pop up” each of the xclearcase browsers. Others perform miscellaneous operations, like closing a browser or quitting xclearcase.

If the builtinFunction call includes an argument with literal quotes, quote the call with %QUOTE% keywords, instead of quote characters (").

Some of the f.call functions create two-state toggle buttons (rather than “push buttons”) automatically. Figure 18-10 shows iconic and textual examples of two-state toggle buttons

Figure 18-10. Two-state Toggle Buttons (Iconic and Textual)

These builtin calls exist to let you position toggle buttons using the menu scope of your choice. Note that you do not get default graphical icons if you scope a toggle item to a toolbar; supply them in the menu item definition like the ClearCase-supplied group files do.

A “customized toggle button” is any toggle button you create with an f.call whose description in Table 18-3 begins “Enable/disable”. Adhere to the following guidelines to guarantee that the state of a customized toggle button is always predictable:

Table 18-2 documents the built-in calls.

While xclearcase macros are most common in f.exec strings, they can appear in f.call arguments as well. Here is a common example:

f.call "VTREE %SELECTION()"

See the sections “Group File Processing and Macro Expansion” and “xclearcase Macros” for details on xclearcase macros.

f.exec %QUOTE%execString%QUOTE%

Executes a command line or command script. The argument to f.exec is an executable command or shell script, enclosed either by double-quotes (" ") or by %quote% keywords.

By default, /bin/sh is used. Include a first line like #!/bin/csh to specify another shell.

In a single item definition, you can combine an f.exec script with one or more additional f.calls and/or f.execs. However, if an f.exec script returns a non-zero exit status, f-dot processing terminates for the current operation.

If the execString includes an argument with literal quotes, quote the execString with %QUOTE% keywords, instead of double-quote characters ("). In general, it is highly recommended that you use %QUOTE% for complicated scripts.

Because xclearcase adds macro expansion to f.exec string processing, quoting and character escaping are different than in ordinary scripts. For details on macro expansion, and on using the specific macro themselves, see the sections “Group File Processing and Macro Expansion” and “xclearcase Macros”.

Environment Variables. If you set the environment variable clearcase_dbg_grp to a non-zero value, xclearcase sends debugging information to the transcript pad when executing commands.

If they are not already set, xclearcase sets the atriahome and grp_path environment variables to their default values when it starts up. (atriahome defaults to /usr/atria; grp_path defaults to $home/.grp:$atriahome/config/ui/grp.) This means you can rely on the existence of these variables when writing scripts.

no-label   f.separator

Inserts a separator line in a menu, or breaks the horizontal run of a toolbar button set. As for any item definition, a label is required; use the keyword no-label instead of a quoted label string.

f.menu submenuName

Specifies a submenu to include in the current menu or submenu (no effect for a menu scoped to a toolbar). The submenuName specifies a menu that is named in a Menu declaration in the same group file.

Figure 18-11 shows a “cascading” menu — the ClearCase menu, and its submenu Checkouts. Figure 18-12 shows an abbreviated version of the group file that defines the ClearCase menu.

Figure 18-11. Cascading Menu

Figure 18-12. Group File with Cascading Menus

---

Note: The submenu name, referenced in the f.menu function and in the submenu definition, is not the label that appears in the interface. As with all item definitions, the quoted label string, Checkout Info in this case, is what the user actually sees.

---

label [ bitmaps ] [ mnemonic ] [ preselectClause ] [ & ] function [ f.help "text" ]

Specifies help text, which is displayed in a popup window when the user presses rightMouse over the menu item (if it is enabled). It is good practice to supply popup help text for all items that include f.call or f.exec functions. There is no need to supply help for f.menu declarations; users cannot access help text on non-command menu items.

When supplying help text, keep each line under approximately 70 characters, to prevent lines from wrapping in the default-sized “popup help” display window.

If the helpText includes literal quotes, quote the execString with %QUOTE% keywords, instead of quote characters (").

The execution script syntax analysis is simplified if you use %quote% keywords, instead of quote characters ("), to enclose your f.exec scripts. Using %quote% eliminates the need to escape backslash characters (\\n, for example) and quote characters (\") in scripts. Inside %quote% delimiters, there is no escape character, and no need for one.

Recall that an item definition is a single logical line. Therefore, a newline (<nl>) must be escaped with the backslash “line continuation character”, unless it falls inside quotes (", ', or %QUOTE% ).

---

Note: Continue to use line continuation characters in execution scripts as required by the unix shell.

---

The percent character (%) is the xclearcase macro escape character. It is used to prefix macros, and to escape literal characters that might confuse macro processing — % (percent character) and ) (close parenthesis), in particular. If you want a % character to appear as a literal anywhere in an item definition (label string, prompt argument to an input macro, etc.) you must escape it, like this: %%.

If your f.exec script calls a second script, which itself requires input from the user, use clearprompt in the second script. Note that some cleartool commands, when run from xclearcase, invoke clearprompt automatically to get user input. For example, a checkin command in an f.exec script uses clearprompt to collect a comment (if neither a comment nor -nc is supplied on the command line).

Most input macros have an optional keyboard argument, which you can use to enable keyboard input on the prompting browser. Always supply the ENABLE argument when the operation requires input strings that cannot, or may not, appear on the browser. For example, when defining a “make new directory” menu item, use ENABLE so the user can type in a new directory name.

In addition, you may want to use ENABLE even when the user could “point and click” from a browser; the keyboard input box lets users supply pathnames with wildcards, instead of having to select many individual items. In general, enable keyboard input whenever there is a chance the user will want to type in the required data items.

Each ClearCase data type has a corresponding input macro whose job it is to prompt for that type of data as shown in Table 18-4.

The prompt from an input macro appears at the bottom of the browser display and includes Ok and Cancel buttons. After Ok or Cancel, auto-displayed browsers disappear. In general, browsers stay up when started with an f.call function; otherwise, they come and go as needed to satisfy the input macros in f.exec strings.

By default, an input macro seeks exactly one data item, and if the user selects more than one item, the operation fails with a Function not executed error message in the transcript pad.Use the optional square brackets on an input macro to collect multiple data input items. Note that the various numerical specifiers permitted inside brackets in preselect clauses do no apply to input macros.

If the user presses Ok, but the selected data does not satisfy the restrictions argument of an input macro, the transcript pad displays the script and the message Function not executed. (Note that the Ok button is not enabled until the user selects the number of data items that satisfies the [] construct.)

%ATTYPE[


preselect-count]( 


restrictions )          preselector
%ATTYPE[](


 prompt,


restrictions,


pname-in-VOB, 


keyboard ) macro
(also: %BRTYPE, %ELTYPE, %HLTYPE, %LBTYPE, %TRTYPE)

Prompt for one or more attribute, branch, element, hyperlink, label, or trigger types (see Table 18-5 and Example 18-1.)

f.exec %QUOTE%
cleartool mkbranch %BRTYPE(Which branch?,,,ENABLE) %SELECTION()
%QUOTE%

Each xxtype macro invokes a corresponding type browser on a particular VOB. Use the restrictions argument to limit the kind of data that the user can specify:

%HYPERLINK[preselect-count]( )                    preselector
%HYPERLINK[]( 


prompt,


browser )                          macro

Prompt for one or more hyperlink objects (see Table 18-6 and Example 18-2.)

f.exec %QUOTE%
cleartool rmhlink \
  %HYPERLINK[](Select merge arrows to remove:,vtree   
  %SELECTION())
%QUOTE%

%LIST[preselect-count]( )                         preselector
%LIST[]( 


prompt,


title )                                 macro

Prompt for data from a named list browser (see Table 18-7 and Example 18-3.)

f.exec %QUOTE%
%SAVE(COs,%LIST[](Select items to checkin:,My Checkouts))
cleartool checkin %RESTORE(COs)
%QUOTE%

Use %list to read list data from a named list browser, to which data was previously directed with %listout. (Only the %list macro can read the data in a list browser, and only %listout can create one.) The title argument must match the title used by %listout to create the list browser.

Use the %listout/%list combination when you need to display data and then have the user select from that data. The %listout and %list macros can appear in “back to back” f.exec scripts in the same item definition, or they can appear in separate item definitions — even in separate group files.

A list browser prompts the user to select one or more items (line of text). For each item, only the text preceding the first tab character is returned; any remainder is ignored. Pressing Ok submits the selection; pressing Cancel cancels the entire command operation. The user cannot edit the contents of a list browser.

%PNAME[preselect-count]( restrictions )           preselector
%PNAME[]( 


prompt,


restrictions,


browser,


keyboard )        macro

Prompt (with file or vtree browser) for one or more pathnames (see Table 18-8.)

In Example 18-4, the File Browser comes up in /vobs/proj1/src, not in the current working directory.

f.exec %QUOTE%
cleartool checkin \
%PNAME[](Files to checkin,
NDIR ELEM INVOB CHECKOUT RESERVED,
file /vobs/proj1/src)
%QUOTE%

Use the restrictions argument to limit the kind of data that the user can specify:

%POOL[preselect-count]( )                         preselector 
%POOL[]( 


prompt,


pname-in-vob,


keyboard )                 macro 

Prompt for one or more storage pool names (see Table 18-9 and Example 18-5.)

f.exec %QUOTE%
cleartool chpool %POOL(Select new pool:,,ENABLE) %SELECTION()
%QUOTE%

%STRING[preselect-count]( )                       preselector
%STRING[]( 


prompt,


default )                             macro

Prompt for one or more text lines (see Table 18-11 and Example 18-6.)

f.exec %QUOTE%
TAG='%STRING(Enter view tag name:)'
STGPNAME='%WILD(%STRING(Enter view storage pathname:,""))'
cleartool mkview -tag $TAG $STGPNAME
%QUOTE%

Use string browsers to prompt for simple text string arguments (for example, comments) or for other data strings— any data that cannot be captured by the more specific data type browsers.

If the %STRING macro includes square brackets, xclearcase may prompt the user for multiple lines of input. When the user presses Ok, the entire contents of the string browser is returned as a single text string: the last line is terminated with <NULL>; all other lines are terminated with <NL>.

%USERNAME[preselect-count]( )                     preselector
%USERNAME[]( 


prompt,


keyboard )                          macro

Prompt for one or more usernames (see Table 18-11 and Example 18-7.)

f.exec %QUOTE%
cleartool lscheckout -user \
  %USERNAME(Specify a user:,ENABLE) %TEXTOUT()
%QUOTE%

%VIEWTAG[preselect-count]( restrictions )         preselector
%VIEWTAG[]( 


prompt,


restrictions,


keyboard )              macro

Prompt for one or more view-tags (see Table 18-9 and Example 18-8.)

f.exec %QUOTE%
cleartool startview %VIEWTAG()
%QUOTE%

%VOBTAG[preselect-count]( restrictions )        preselector
%VOBTAG[]( 


prompt,


restrictions,


keyboard )        macro

Prompt for one or more VOB-tags (see Table 18-9 and Example 18-9.)

f.exec %QUOTE%
cleartool umount %VOBTAG(,MOUNTED,ENABLE)
%QUOTE%

---

Note: The default xclearcase interface implements this operation differently:

---

%VOBTAG(MOUNTED) f.exec "cleartool umount %SELECTION()"

%ELEMENT( pathnames )                                   macro

Strip any ClearCase annotations from pathnames, leaving standard pathname (see Table 18-11 and Example 18-10.)

f.exec %QUOTE%
cleartool checkin %ELEMENT(%SELECTION())
%QUOTE%

%ELEMSUFFIX( 


pathnames )                                macro 

Append extended naming symbol (@@) to pathnames (see Table 18-11 and Example 18-11.)

f.exec %QUOTE%
cleartool lsvtree %ELEMSUFFIX(
%ELEMENT(
%PNAME(Element whose version tree is to be listed,
INVOB ELEM)))
%QUOTE%

%MOUNT( 


pathnames )                                     macro 

Return the VOB mount points (VOB-tags) of specified pathnames (see Table 18-11 and Example 18-12.)

f.exec %QUOTE
%TEXTOUT(Mount List,"No mounted VOBs specified",6,4)
echo '%MOUNT(%PNAME[](Select VOB pathname%(s%),INVOB))'
%QUOTE%

The two parenthesis characters are escaped — %( and %) — to protect them from the macro expansion pass.

%RELATIVE( 


pathnames,


dir )                              macro 

Convert full or relative pathnames into pathnames relative to directory (see Table 18-11 and Example 18-13.)

f.exec %QUOTE%
#!/bin/sh
PATH=$PATH:$HOME/%RELATIVE(
%PNAME(Select a dir anywhere under your home dir),$HOME)
%QUOTE%

%SETVIEW( 


pathnames )                                   macro 

Convert pathnames to view-extended pathnames, based on the current set view (see Table 18-11 and Example 18-14.)

The example invokes a text editor on the selected file.

f.exec %QUOTE%
%WHICH(GRP_PATH,editor.sh) %SETVIEW(%SELECTION())
%QUOTE%

---

Note: If the argument is already a view-extended pathname, it is unchanged by %setview, regardless of the view-tag on which it is based.

---

%SORT( 


pathnames )                                      macro

Sort pathnames as shown in Table 18-11 and Example 18-15.

f.exec %QUOTE%
echo '%SORT(%PNAME[]())' %TEXTOUT(Sorted Pnames,,8,4)
%QUOTE%
%VERMOD( 


pathnames )                                    macro 

Convert standard pathnames to version-extended pathnames (see Table 18-11 and Example 18-16.)

f.exec %QUOTE%
cleartool findmerge %SELECTION() -xmerge -log /dev/null \
  -whynot -fver %VERMOD(  %PNAME(
Select 'from' version: ['to' %VERMOD(%SELECTION())],ELEM INVOB,
vtree %SELECTION())
) | grep -v "Needs Merge"  %TEXTOUT("Merge Info",,8,2)
%QUOTE%

%WHICH( 


path-ev,


filename )                              macro 

Search specified path for the first occurrence of filename (see Table 18-11 and Example 18-17.)

f.exec %QUOTE%
%WHICH(GRP_PATH,editor.sh) %SETVIEW(%SELECTION())
%QUOTE%

Like the unix which(1) command, %which returns (by searching path-EV) the full pathname of its filename argument. The %which macro exists to help support local customizations to the ClearCase-supplied .sh scripts that are installed in /usr/atria/config/ui/grp.

The ClearCase-supplied group files include a number of f.exec scripts that invoke .sh files to perform specialized processing — finding and invoking the user's preferred text editor, for example. To customize a .sh file, first copy it to another directory. Make sure this directory occurs in the path-EV, and use %which to invoke your customized file.

For example, suppose you copy the file term_display.sh to $home/.grp and customize it. If your grp_path variable is set to $home/.grp:/usr/atria/config/ui/grp (which is the default), then the macro %WHICH(GRP_PATH,term_display.sh) finds and executes your version.

%WILD( 


pathnames )                                      macro 

Expand wildcards in pathnames (see Table 18-11 and Example 18-18.)

f.exec %QUOTE%
%PNAME(%WILD(%STRING()))
%QUOTE%

%LISTOUT( 


title,


class,


persistence,


width,


height )        macro 

Redirect output to a list browser (named or unnamed) (see Table 18-11 and Example 18-19.)

f.exec %QUOTE%
cleartool lsch -short . %LISTOUT(VOB Checkouts,,,6,4)
%QUOTE%

Use %listout to capture lists of pathnames or other VOB objects into a named list browser, from which data can later be selected (see %list) and supplied to other operations.

The title argument gives the list browser a name, which %list then uses to refer to the browser when using it to collect user input.

The optional class argument specifies a list browser class. You can scope a group file to a list browser class (giving the class an arbitrary name: Scope myList:toolbar, for example), thereby providing a set of menu items for the user to choose from when such a list browser is displayed. The group file menu appears on any list browser that %listout creates with the applicable class argument.

List data entries are separated or terminated by <nl> or null characters. Furthermore, within a single list entry (one line), only the text before the first tab character is returned by %list; the rest is ignored.

By default, a list browser created with %listout stays up until the user closes it. The TRANSIENT argument forces the list browser to close after either:

%TEXTOUT( 


title,


default-text,


width,


height )             macro 

Redirect standard output to read-only text-display window (see Table 18-11 and Example 18-20.)

f.exec %QUOTE%
%TEXTOUT("Describe",,8,2)
cleartool lstype -attype -long %SELECTION() 2>&1"
%QUOTE%

Unlike %listout, %textout redirects the standard output of commands to an untyped, read-only text window. Use %textout when your only objective is to display information.

The default text argument (def-text) specifies text to be displayed if the redirected operations generate no output.

Like %listout, %textout redirects stdout for the entire f.exec script. To redirect both stderr and stdout for a given command, use the /bin/sh construct 2>&1.

For comparison with list browsers, Figure 18-15 shows a sample text output window, and Figure 18-16 shows a terminal emulation window. Neither prompts for, or accepts, user input; they are display-only devices.

Figure 18-15. A Text Output Window

Figure 18-16. A Terminal Emulation Window

The text output window was generated by the Describe button and the terminal window by menu item Report -> Find query -> Whole VOB -> Versions with Label...

You can cancel output to a terminal emulation window with <Ctrl-C>.

%SAVE( 


var-name,


string,


persistence )                    macro 

Save string into named temporary variable (can be referenced with %RESTORE (see Table 18-11 and Example 18-21.))

f.exec %QUOTE%
%SAVE(dir, %PNAME(Select target dir, DIR INVOB),KEEP)
  .
  .
DIR='%RESTORE(dir)' %REMOVE(dir)
%QUOTE%

%REMOVE( 


var-name )                                     macro 

Delete a persistent temporary variable created with %SAVE (see Table 18-11 and Example 18-22.)

f.exec %QUOTE%
%SAVE(tmp_print_file, %TMPFILE(), KEEP)
  .
  .
%REMOVE(tmp_print_file)
%QUOTE%

%RESTORE( 


var-name )                                    macro 

Retrieve the value of a temporary variable created with %SAVE (see Table 18-11 and Example 18-23.)

f.exec %QUOTE%
%SAVE(dir, %PNAME(Select target directory, DIR INVOB))
  .
  .
DIR='%RESTORE(dir)'
%QUOTE%

%SELECTION( )                                           macro 

Return the current data selection(s) from the current browser (see Example 18-24.)

f.exec %QUOTE%
cleartool uncheckout -rm %SELECTION()
%QUOTE%

The %selection() macro is replaced by the data that has been preselected by the user. %selection() can appear only in items in which the f.exec strings is preceded by an activation clause.

%DIR( )                                                 macro 

Return the pathname of the current browser's directory (see Example 18-25.)

f.exec %QUOTE%
echo "Current working dir is %DIR()"
%QUOTE%

%NAME( )	macro

Return the name associated with the current browser (see Example 18-26.)

f.exec %QUOTE%
%WHICH(GRP_PATH,term_display.sh) USE_MORE \
cleartool lshistory -long %NAME()
%QUOTE%"

For a vtree browser, expands to name of the element whose vtree is displayed. For all other browsers, expands to the current directory pathname.

%TMPFILE( )                                             macro 

Create a temporary file and return its pathname (see Example 18-27.)

f.exec %QUOTE%
%SAVE(tmp_print_file, %TMPFILE(), KEEP)
%QUOTE%

This example creates a temporary file in $TMPDIR (or /usr/tmp, if this EV is not set). The full pathname of the temporary file is placed in the xclearcase variable tmp_print_file.