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)

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%');

   DCL  ID  CHAR(100)  VAR  INIT('MODNAME  2.3  07/18/85');

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

   No id keywords (cm7)

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

   get  -r1.5.2.3  s.abc
   1.5.2.3
   234 lines

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

   get  -r9  s.abc
   7.6
   420 lines

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

   get  -r3  -t  s.abc
   3.5
   59 lines

   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:

• It checks whether the login name or group ID of the person executing get is present in the user list. The login name or group ID must be present for the user to be allowed to make deltas. (See ``admin command'' for a discussion of making user lists.)

• It checks whether the release number (R) of the version being retrieved satisfies the relation:

     floor is less than or equal to R,
     which is less than or equal to ceiling.
  

  This check determines whether the release being accessed is protected. The floor and ceiling are SCCS file flags, representing start and end of range.

• It checks whether the release number of the version being edited is locked against editing. The lock is an SCCS file flag.

• It checks whether multiple concurrent edits are allowed for the SCCS file by the SCCS file j flag.

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)

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.

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:

• SID of the retrieved version

• SID given to the new delta when it is created

• login name of the real user executing get

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 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 produces:

   1.1
   new delta 1.1.1.1
   5 lines

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.