DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
Source code control system (SCCS)

get command

The get(CP) command creates a file containing a specified version of an SCCS file. The version is retrieved by beginning with the initial version and then applying deltas, in order, until the desired version is obtained. The resulting file is called the `g-file'. It is created in the current directory and owned by the real user. The mode assigned to the g-file depends on how the get command is used.

The most common use of get is:

get s.abc

This retrieves the latest version of file abc from the SCCS file tree trunk and produces (for example) on the standard output:

   1.3
   67 lines
   No id keywords (cm7)
This means version 1.3 of file s.abc has been retrieved (assuming 1.3 is the latest trunk delta), it has 67 lines of text, and no ID keywords have been substituted in the file.

The generated g-file (file abc) is given access permission mode 444 (read only). This particular way of using get produces g-files only for inspection, compilation, and so on. It is not intended for editing (making deltas).

When several files are specified, the same information is output for each one. For example, enter:

get s.abc s.xyz

It produces:

   s.abc:
   1.3
   67 lines
   No id keywords (cm7)

s.xyz: 1.7 85 lines No id keywords (cm7)

ID keywords in SCCS

In generating a g-file for compilation, it is useful to record the date and time of creation, the version retrieved, and the module's name within the g-file. This information can eventually appear in a load module when one is created. SCCS provides a convenient mechanism for doing this automatically. Identification (ID) keywords appearing anywhere in the generated file are replaced by appropriate values according to the definitions of those ID keywords. The format of an ID keyword is an uppercase letter enclosed by percent signs (%).

%I%

In this example, I is the ID keyword replaced by the SID of the retrieved version of a file. Similarly, %H% is the current date in MM/DD/YY format and %M% is the name of the g-file. When get is executed on an SCCS file containing the following PL/1 declaration:

   DCL ID CHAR(100) VAR INIT('%M% %I% %H%');
The PL/1 declaration produces the following:
   DCL  ID  CHAR(100)  VAR  INIT('MODNAME  2.3  07/18/85');
For a complete list of the approximately 20 ID keywords provided, see get(CP).

When no ID keywords are substituted by get, the following message is issued:

   No id keywords (cm7)
This message is normally treated as a warning by get, although the presence of the SCCS file i flag causes it to be treated as an error. For a complete list of the SCCS file flags, see admin(CP).

Retrieval of different versions

The version of an SCCS file that get retrieves is the most recently created delta of the highest-numbered trunk release. However, any other version can be retrieved with get -r by specifying the version's SID. The following command retrieves version 1.3 of file s.abc and produces the sample message on the standard output:

   get  -r1.3  s.abc
   1.3
   64 lines
A branch delta can be retrieved similarly, as demonstrated with the following command and sample output:
   get  -r1.5.2.3  s.abc
   1.5.2.3
   234 lines
When an SID is specified and the particular version does not exist in the SCCS file, an error message results.

The level number can be omitted, causing the retrieval of the trunk delta with the highest level number within the given release. The following command and sample output illustrate:

   get  -r3  s.abc
   3.7
   213 lines
If the specified release does not exist, get retrieves the trunk delta with the highest level number within the highest-numbered existing release that is lower than the given release. In the following example, release 9 is specified for retrieval. However, since the specified release does not exist, trunk delta 7.6 is retrieved as the latest version of file s.abc below release 9.
   get  -r9  s.abc
   7.6
   420 lines
For details on numbering by delta's see ``Delta numbering''.

Similarly, omitting the sequence number, for example, results in the retrieval of the branch delta with the highest sequence number on the given branch. (If the given branch does not exist, an error message results.)

   get  -r4.3.2  s.abc
   4.3.2.8
   89 lines
The get -t command retrieves the latest (top) version of a particular release when no -r is used or when its value is simply a release number. The latest version is the delta produced most recently, independent of its location on the SCCS file tree. The following command (and sample output) illustrate this for a case where the most recent delta in release 3 is 3.5:
   get  -r3  -t  s.abc
   3.5
   59 lines
However, if branch delta 3.2.1.5 were the latest delta (created after delta 3.5), the same command might produce:
   3.2.1.5
   46 lines

Updating source

The get -e command indicates an intent to make a delta. First, get checks the following conditions:

A failure of any of the first three conditions causes the processing of the corresponding SCCS file to terminate.

If the above checks succeed, get -e causes the creation of a g-file in the current directory with mode 644 (readable by everyone, writable only by the owner) owned by the real user. If a writable g-file already exists, get terminates with an error. This is to prevent inadvertent destruction of a g-file while it is being edited for the purpose of making a delta. Any ID keywords appearing in the g-file are not substituted by get -e because the generated g-file is subsequently used to create another delta. Replacement of ID keywords causes them to be permanently changed in the SCCS file. As a direct result of this, get does not check for presence of ID keywords in the g-file. The following message is never output when get -e is used.

   No id keywords (cm7)
In addition, get -e causes the creation (or updating) of a p-file that is used to pass information to the delta command.

For example:

get -e s.abc

The output of this command is:

   1.3
   new delta 1.4
   67 lines

Undoing a get -e

There may be times when a file is erroneously retrieved for editing, such as when there is really no editing that needs to be done at the time. In such cases, the unget(CP) command cancels the delta reservation that was set up. For example, enter either of the following commands:

unget -r1.4 s.abc
unget s.abc

These commands produce:

   1.4

Additional get options

If get -r and/or -t keys are used together with the -e option, the version retrieved for editing is specified with -r and/or -t.

The get -i and -x commands specify a list of deltas to be included and excluded, respectively. (See get(CP) for the syntax of such a list.) Including a delta means forcing its changes to be included in the retrieved version. This is useful in applying the same changes to more than one version of the SCCS file. Excluding a delta means forcing it not to be applied. This may be used to undo the effects of a previous delta in the version to be created.

Whenever deltas are included or excluded, get checks for possible interference with other deltas. For example, two deltas can interfere when each one changes the same line of the retrieved g-file. A warning shows the range of lines within the retrieved g-file where the problem may exist.


NOTE: The user should examine the g-file to determine what the problem is and take appropriate corrective steps (such as edit the file).

The get -i and get -x commands should be used with care.

The get -k command has two uses. The first is to regenerate a g-file that may have been accidentally removed or corrupted after get -e. The second use is to generate a g-file in which the replacement of ID keywords has been suppressed. A g-file generated by get -k is identical to one produced by the get -e command. However, no processing related to the p-file takes place.

Concurrent edits of different SID

The ability to retrieve different versions of an SCCS file allows several deltas to be in progress at any given time. This means that several get -e commands may be executed on the same file unless two executions retrieve the same version or multiple concurrent edits are allowed.

The p-file created by get -e is named by automatic replacement of the SCCS filename's prefix s. with p.. It is created in the same directory as the SCCS file, given mode 644 (readable by everyone, writable only by the owner), and owned by the effective user. The p-file contains the following information for each delta that is still in progress:

The first execution of get -e causes the creation of a p-file for the corresponding SCCS file. Subsequent executions simply update the p-file with a line containing the above information. Before updating, however, get checks to assure that the SID of the version to be retrieved has not already been retrieved (unless multiple concurrent edits are allowed). If the check succeeds, the user is informed that other deltas are in progress, and processing continues. If the check fails, an error message results.

It should be noted that concurrent executions of get must be carried out from different directories. Subsequent executions from the same directory attempt to overwrite the g-file, which is an SCCS error condition. In practice, this problem does not arise because each user normally has a different working directory.

For a discussion of how different users are permitted to use SCCS commands on the same files, see ``Protection''.
``Determination of new SID'' shows the possible SID components a user can specify with get (left-most column), the version that is then retrieved by get, and the resulting SID for the delta, which delta creates (right-most column).

Determination of new SID

SID -b key- Other SID SID of delta
specified letter conditions retrieved to be created
in get* used+   by get by delta
none++ no R defaults to mR mR.mL mR.(mL+1)
none++ yes R defaults to mR mR.mL mR.mL.(mB+1).1
R no R > mR mR.mL R.1§
R no R = mR mR.mL mR.(mL+1)
R yes R > mR mR.mL mR.mL.(mB+1).1
R yes R = mR mR.mL mR.mL.(mB+1).1
R - R< mR and R hR.mL** hR.mL.(mB+1).1
    does not exist    
R - Trunk successor R.mL R.mL.(mB+1).1
    number in    
    release > R,    
    and R exists    
R.L. no No trunk R.L R.(L+1)
    successor    
R.L. yes No trunk R.L R.L.(mB+1).1
    successor    
R.L - Trunk successor R.L R.L.(mB+1).1
    in release GREATER THAN OR EQUAL TO R    
R.L.B no No branch R.L.B.mS R.L.B.(mS+1)
    successor    
R.L.B yes No branch R.L.B.mS R.L.(mB+1).1
    successor    
R.L.B.S no No branch R.L.B.S R.L.B.(S+1)
    successor    
R.L.B.S yes No branch R.L.B.S R.L.(mB+1).1
    successor    
R.L.B.S - Branch successor R.L.B.S R.L.(mB+1).1
Footnotes *, +, ++, §, and ** on next page.

Footnotes to ``Determination of new SID'':


*
R, L, B, and S mean release, level, branch, and sequence numbers in the SID, and m means maximum. For example, R.mL means the maximum level number within release R. R.L.(mB+1).1 means the first sequence number on the new branch (that is, the maximum branch number plus 1) of level L within release R. Note that, if the SID specified is R.L, R.L.B, or R.L.B.S, then each of these specified SID numbers must exist.

+
The -b option is effective only if the SCCS file b flag is present. An entry of - means `irrelevant'. See admin(CP) for a discussion of the b flag.

**
The release hR is the highest existing release that is lower than the specified, nonexistent release R.

++
This case applies if the SCCS file d (default SID) flag is not present. If the d flag is present in the file, the SID is interpreted as though specified on the command line. Therefore, one of the other cases in this figure applies.

§
This forces the creation of the first delta in a new release.

Concurrent edits of same SID

Under normal conditions, more than one get -e for the same SID is not permitted. That is, delta must be executed before a subsequent get -e is executed on the same SID.

Multiple concurrent edits are allowed if the SCCS file j flag is set. For example:

get -e s.abc

This produces:

   1.1
   new delta 1.2
   5 lines
This can be immediately followed by (without an intervening delta):

get -e s.abc

This produces:

   1.1
   new delta 1.1.1.1
   5 lines
In this case, a delta after the first get produces delta 1.2 (assuming that 1.1 is the most recent trunk delta), and a delta after the second get produces delta 1.1.1.1.

Key letters that affect output

The get -p command causes the retrieved text to be written to the standard output, rather than to a g-file. In addition, all output normally directed to the standard output (such as the SID of the version retrieved and the number of lines retrieved) is directed instead to the diagnostic output. The get -p command creates a g-file with an arbitrary name, as in:

get -p s.abc > arbitrary-filename

The get -s command suppresses output normally directed to the standard output, such as the SID of the retrieved version and the number of lines retrieved, but it does not affect messages normally directed to the diagnostic output. The get -s command prevents nondiagnostic messages from appearing on the user's terminal and is often used with -p to pipe the output, as in:

get -p -s s.abc | pg

The get -g command suppresses the retrieval of the text of an SCCS file. This is useful in several ways. It may be used to verify a particular SID in an SCCS file. For example:

get -g -r4.3 s.abc

This outputs the SID 4.3 if it exists in the SCCS file s.abc, or an error message if it does not.

Another use of get -g is in regenerating a p-file that may have been accidentally destroyed, as in:

get -e -g s.abc

The get -l command causes SCCS to create an `l-file'. It is named by replacing the s. of the SCCS filename with l., created in the current directory with mode 444 (read only) and owned by the real user. The l-file contains a table showing the deltas used in constructing a particular version of the SCCS file. See get(CP) for a description of the delta table format.

The following command generates an l-file, showing the deltas applied to retrieve version 2.3 of file s.abc.

get -r2.3 -l s.abc

Specifying p with -l, for example, results in the output being written to the standard output, rather than to the l-file.

get -lp -r2.3 s.abc

The get -g command can be used with -l to suppress the retrieval of the text. For example:

get -g -l s.abc

The get -m command identifies the changes applied to an SCCS file. Each line of the g-file is preceded by the SID of the delta that caused the line to be inserted. The SID is separated from the text of the line by a tab character.

The get -n command causes each line of a g-file to be preceded by the value of the ID keyword and a tab character. This is most often used in a pipeline with grep(C). For example, to find all lines that match a given pattern in the latest version of each SCCS file in a directory, the following can be executed:

get -p -n -s directory | grep pattern

If both -m and -n are specified, each line of the generated g-file is preceded by the value of the %M% ID keyword and a tab (the effect of -n), and is followed by the line in the format produced by -m. Because use of -m and/or -n causes the contents of the g-file to be modified, such a g-file must not be used for creating a delta. Therefore, neither -m nor -n may be specified together with get -e.


NOTE: See get(CP) for a full description of additional key letters.


Next topic: delta command
Previous topic: help command

© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003