Using Keywords in Working Files

User Help > Managing Source Files as Members > Using Keywords in Working Files

A keyword is a placeholder that can be inserted into text-based working files. This placeholder is a special variable (for example, $Date$, $Author$, $State$) used to represent textual information in a working file. Keywords can be expanded (that is, replaced with their literal values) when a revision is checked out.

To use a keyword, simply include it in a working file, surrounded by dollar signs (for example, $Date$) and check the file back into its archive.

For example, Chad wants to see information about the member he is editing as a comment in the file. Chad can do this through keywords. He decides to use the $Log$ keyword. Chad sets his preferences to enable keyword expansion on checking out a member. He then places the keyword in a member.

Your administrator may define custom keywords for your use. For information about custom keywords, contact your administrator.

The next time you check out the revision, PTC RV&S scans it for keywords and replaces them with the appropriate information, if keyword expansion is turned on.

Keyword expansion is the process of automatically adding or updating information to a keyword reference when a revision is checked out or viewed.

For example, if the $Date$ keyword is encountered, the date and time of the revision (assigned at check in) is added to the working file as part of the keyword. When expanded, the entry would look something like

$Date: 2016/08/23 20:59:27IST $

This method of adding or updating information in a keyword is called keyword expansion.

For example, if the member main.c has the keywords $Author$ and $State$ embedded within it, checking out main.c and issuing the command:

ident main.c

returns

main.c:
$Author: Taherali, Khuzema (ktaherali) $
$State: Exp $

The following PTC RV&S commands contain keyword expansion options:

• Add Members

• Check Out

• Check In

• Resynchronize

• Revert Member

• Revision Contents View (Member > Revision > View Contents)

• si annotate (CLI only)

Keyword expansion is configured using the Preferences dialog box in the GUI. The dialog boxes in the GUI can override the default settings.

• Your administrator can set a policy for PTC RV&S to ignore keywords. That policy overrides your keyword settings. PTC RV&S does not notify you if that policy is set for your project. If keywords do not expand or unexpand, and you need them to do so, contact your administrator.

• Keyword expansion applies to text files only. It is disabled for binary files.

Text before and after the keyword is preserved, making it suitable for use within expressions, as above, and within comments.

If keyword expansion is enabled and you are checking out a text file that contains the string

$Revision$

PTC RV&S, when it encounters this string, automatically adds the value of the keyword $Revision$ in the format

$Revision: value $

where

value is the appropriate value of the keyword (in this case, the revision number).

For example, including the statement

char revnum[] = "$Revision$";

in a C source file creates a character string named revnum containing the file’s revision number. The program can then be configured to display this string when it starts up, automatically presenting the current revision of the program’s source file.

Using the $Revision$ keyword to obtain the revision number of a file is one of the common applications of keywords. Other common applications include:

• The $Header$ keyword provides a one-line summary of useful information associated with a revision. Including this information in a comment makes the information available to anyone looking at the member.

• The $Log$ keyword supplies the same sort of information as $Header$ plus the revision description. The $Log$ keyword provides a complete list of changes that are that are made to the member over time.

The keyword format of $<keyword>$ causes PTC RV&S to replace between the first $ and the next $. If you use a keyword in the format $<keyword>, PTC RV&S continues to replace until it encounters another $. It is possible that PTC RV&S may not encounter another $ until the file is checked out again. This type of keyword use returns results that are similar to logging.

Turning Off Keyword Expansion

If you want keywords to remain exactly as they are in a revision, set your preferences to turn off keyword expansion.

Locating Keywords

You can use the ident command in the command line interface to locate and display keywords (expanded or unexpanded) in one or more members. For more information about the ident command, see the CLI man pages.

This command displays the name of each member that contains keywords, as well as the keywords themselves. This provides an easy way to extract identification information from source files, as well as compiled object files.