TOC PREV NEXT INDEX DOC LIST MASTER INDEX




View > Format > Define

The View > Format > Define command displays a dialog box which allows you to define and modify display formats for directory and versions viewer windows.

The dialog for versions viewer windows Define Versions Format is slightly different from that for directory viewer windows Define Directory Format. In particular, the Define Versions Format dialog does not have the Alignment point check box, the Menu String field and the Make this the default display format check box. The Save Format button in the Define Versions Format dialog is similar to the Define Format button in the Define Directory Format dialog.

This dialog is used to iteratively construct a display format string and then define the format. For a newly defined directory viewer format, a new menu item is automatically created at the end of the Format menu. The label on that menu item can be specified in the Menu String: input area. The internal name of the format will be of the form user_formatN where N = 1,2,3... up to a limit of 15.

For a versions window format, new View > Format menu entries cannot be specified, however, the predefined formats may be changed. For example, the "Standard" format may be changed to produce a different desired format. Also, a user-defined format can be selected in the Control > Show > Versions (Apex/Summit) dialog before a versions window is displayed. The format can be changed after a versions window is displayed by invoking this command, setting the Format Name field to indicate the desired format, and pressing the Try Format button

Format String

A format is defined by building a format string. The format string indicates the data to be presented and how it should be laid-out. The kinds of data fields permitted are listed in the Format field choices list box. The Add Field at Cursor button maybe used to add a selected field to the format string. Fields may also be entered manually.

The format string consists of three kinds of items

The syntax of a field format in a format string is

where

%
(percent sign) format keyword indication
<keyword>
a format keyword (see tables below)
(<name>)
the name of an attribute or function (for the %attribute and %function formats only)
<alignment>
R | C for right or centered; default is left
<size>
a positive integer
A
show all of field; the default is to truncate the field to <size>

The expression in square brackets can be added as a suffix to the keyword to specify a field size and field justification within the column - left, right or centered. If a field's value is larger than the field size, the default is to truncate on the right. To have the entire field always shown, even if it exceeds the field size, a final A can be given. For example,

%Owner[8] - a fixed size 8 character field.

%Size[R8A] - a fixed size 8 character field, right justified and if the value exceeds 8 characters it will all be shown.

If fixed size fields are used, then all columns will line up.

In addition, certain keywords lead to fields which are always a fixed size without needing that to be specified explicitly. For example, UNIX acls (%Acls) and file update times (%Time).

To achieve alignment with variable size fields there is a keyword which specifies that an alignment point should occur for the next character in the display line. For a multi-line display, the next character for all lines will occur at the same column, which is the one after the longest line up to that point. For example, the Cmvc_Attributes format starts

This causes the History column for all lines to start after the longest value in the preceding name column. For performance reasons, alignment point should only be used when necessary. For example, the File_Attributes format uses all fixed size fields, before the last one, and needs no alignment points.

In a versions window, all fields are aligned by default, so the %Align keyword is not used. No %Align is required for the first field in a format string.

Since the directory display allows multiple levels of subdirectories to be expanded in place, there is a keyword called, %Indent, which inserts the indent spaces based on the nesting level of the item.

To define a new format, iteratively pick a field kind from the field choices list at the top of the dialog and use the Add button to add it to the end of the format string. The field kinds from the choices list are mapped into a single or multiple keyword sequence. To add to the middle of the format string, move the cursor within the format string by clicking the mouse at the desired spot and then press Add.

The Alignment point check box may be used to specify an alignment point before the next field added to the format string. No alignment point is added before the first field, since that field is aligned by default.

The Column Size field may be used to specify a fixed size for the field. In this case, the internal alignment of the field is specified in the Justify options menu by selecting Left, Center, or Right.

While making changes to a format string, there are convenience buttons to Replace and Delete segments of the format string. Adjustments to the format string can also be made by directly editing the format string, for example, to insert more space characters between fields.

Defining or Saving the Format

To define or save a format string, select the Define Format or Save Format button. A format name must be specified in the Format Name field. The set of format names for directory windows is fixed, but any name may be specified for the corresponding menu item. A versions windows format can be given any unique name specified in the Format Name field.

To change the format, simply edit the format string as described above and push the Define Format or Save Format button again.

Format Keywords

The following format keywords are available for directory windows:

Table 1 Format Keywords for Directory Windows
name
Directory or file name
indent
Indentation according to directory level
lname
Target pathname of a link
mark
File/directory type indication (*, / , ->)
attribute(<name>)
Extended version attribute with the specified <name> (Apex/Summit)
default_attributes
Extended attributes visible in current subsystem
acls
Access control list
size
File size in bytes
time
Last modify time
owner
File owner
group
File group
history
CM history containing version
status
CM current status - controlled, checked-in/out
verbose_status
CM current/latest status
simple_status
CM single letter status (U, O)
version
CM current version number
verbose_version
CM current/latest version numbers
comments
CM comments if not latest version
verbose_comments
CM comments for latest version
current_comments
CM comments for current version
dash
CM out-of-date hyphen (-)
model
model for containing view or subsystem
storage
storage directory
notes
Apex/Summit version notes
tasks
Summit/TM tasks associated with Summit/CM version
access
CM view/subsystem access mode
view_kind
CM view kind (Apex/Summit)
architecture
CM view target hardware architecture
language
CM view/subsystem programming language
target_acls
Access control list for target of a link
target_size
Size in bytes of target of a link
target_time
Last modify time for target of a link
target_owner
Owner of target of a link
extension
File or directory name extension
no_extension
Simple file or directory name without extension
kind
Kind of file or directory (for example, ascii text)
rci_attributes
RCI attributes for ada units and views (Ada only)
unit_state
Ada unit compilation state
subclass
Ada subclass
align
Align the next character of all lines with format
function(<name>)
Invokes an apex_shell function called <name>

The following format keywords are available for versions windows:

Table 2 Format Keywords for Versions Windows (Apex/Summit)
current_mark
Dash indicating current version in view
number
Version number (always right justified)
attribute(<name>)
Extended version attribute with specified <name>
default_attributes
Extended attributes visible in current subsystem
co_word
If checked-out, "Out"
co_date
Checked-out date
co_time
Checked-out time of day
co_user
Checked-out by user
ci_word
If checked-in "In"
ci_date
Checked-in date
ci_time
Checked-in time of day
ci-user
Checked-in by user
status
CM status
date
Date of latest check-in or check-out
time
Time of latest check-in or check-out
user
User for latest check-in or check-out
where
View in version was created
ancestor
Parent version
tasks
Summit/TM tasks associated with Apex/Summit version
notes
Summit/CM notes for version
function(<name>)
Invokes an apex_shell function called <name>

Version Attribute Formats (Apex/Summit)

Special formats are provided for displaying extended version attributes associated with a file or version.

If there are attributes defined in the subsystem in which the Format > Define dialog was invoked, or if there are attributes defined globally via the APEX_VERSION_ATTRIBUTES_KEY switch, the Format field choices list will contain formats for each attribute. These format choices have the form

Attribute - <attribute name>

where <attribute name> is the name of a specific attribute. They display the values of the corresponding attributes. There is also special format for displaying any extended attribute:

Attribute - <name>

When this format is added to the format string via the Add Field at Cursor button, the name of the attribute to be displayed must be entered.

To display all attributes, you may use the format choice:

Attributes (default)

This format displays the values of all attributes visible in the subsystem containing the version. The attribute values are sorted by the attribute names (which are not displayed).

Finally, the format choice

Attributes (current default)

will display those attribute which are visible in the current context in which the format is defined.

Invoking Apex Shell Formatting Functions (%function)

An apex_shell function can be invoked in a format string. The syntax for a function call is

The %function keyword invokes the name apex_shell function.

The string value returned by the function will be inserted into the display line.

For a directory window format, the pathname of the directory entry is passed to the function as an argument.

$1 (pathname) the full pathname of the directory entry

For a versions window format, the following arguments are passed

$1
(repository) the name of the repository containing the version (Summit or ClearCase)
$2
(subsystem) the full pathname of the subsystem containing the version
$3
(element) the element name of the version
$4
(history) the name of the history or branch containing the version
$5
(version) the version number of the version

To have acceptable performance when using this option, the function given should be written so that all of it's statements are interpretively executed with no forking of Unix executables. For example, to add the UNIX group_id to the File_Attributes display, a new format could be defined (or the existing one redefined) as the following

and the following function added to the file $HOME/.Rational/directory_rules.

Additional Topics

For more information, click on a topic:


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS