get Command

Purpose

Creates a specified version of a SCCS file.

Syntax

To Get Read-Only Versions of SCCS Files

get [ -g ] [ -m ] [ -n ] [ -p ] [ -s ] [ -c Cutoff ] [ -i List ] [ -r SID ] [ -t ] [ -x List ] [ -w String ] [ -l [ p ] ] [ -L ] File ...

To Get Editable Versions of SCCS Files

get [ -e ] [ -k ] [ -b ] [ -s ] [ -c Cutoff ] [ -i List ] [ -r SID ] [ -t ] [ -x List ] [ -l [ p ] ] [ -L ] File ...

Description

The get command reads a specified version of the Source Code Control System (SCCS) file and creates an ASCII text file according to the specified flags. The get command then writes each text file to a file having the same name as the original SCCS file but without the s. prefix (the g-file).

Flags and files can be specified in any order, and all flags apply to all named files. If you specify a directory for the File parameter, the get command performs the requested actions on all files in the directory that begin with the s. prefix. If you specify a - (minus sign) for the File parameter, the get command reads standard input and interprets each line as the name of an SCCS file. The get command continues to read input until it reads an end-of-file character.

If the effective user has write permission in the directory containing the SCCS files but the real user does not, then only one file can be named when the -e flag is used.

Note: The get command supports the Multibyte Character Set (MBCS) for the file name and string data specified with the w flag.

Getting Read-Only File Versions

The get command creates both read-only versions and editable versions of a file. Read-only versions of files should be used if the application does not require changes to the file contents. Read-only versions of source code files can be compiled. Text files can be displayed or printed from read-only versions.

The difference between an editable and a read-only version is important when using identification keywords. Identification keywords are symbols expanded to some text value when the get command retrieves the file as read-only. In editable versions, keywords are not expanded. Identification keywords can appear anywhere in an SCCS file. See the prs command for further information on identification keywords.

SCCS Files

In addition to the file with the s. prefix (the s-file), the get command creates several auxiliary files: the g-file, l-file, p-file, and z-file. These files are identified by their tag, which is the letter before the hyphen. The get program names auxiliary files by replacing the leading s. in the SCCS file name with the appropriate tag, except for the g-file, which is named by removing the s. prefix. So, for a file named s.sample, the auxiliary file names would be sample, l.sample, p.sample, and z.sample.

These files serve the following purposes:

Item	Description
s-file	Contains the original file text and all the changes (deltas) made to the file. It also includes information about who can change the file contents, who has made changes, when those changes were made, and the nature of changes made. You cannot edit this file directly because it is read-only. However, it contains the information needed by the SCCS commands to build the g-file, which you can edit.
g-file	An ASCII text file that contains the text of the SCCS file version that you specify with the -r flag (or the latest trunk version by default). You can edit this file directly. When you have made all your changes and want to make a new delta to the file, you can then run the delta command on the file. The get command creates the g-file in the current directory. Whenever it runs the get command creates a g-file, unless the -g flag or the -p flag is specified. The real user owns it (not the effective user). If you do not specify the -k or -e flag, the file is read-only. If the -k or -e flag is specified, the owner has write permission for the g-file. You must have write permission in the current directory to create a g-file.
l-file	The get command creates the l-file when the -l flag is specified. The l-file is a read-only file. It contains a table showing which deltas were applied in generating the g-file. You must have write permission in the current directory to create an l-file. Lines in the l-file have the following format: A blank character if the delta was applied; otherwise, an asterisk. A blank character if the delta was applied, or was not applied and ignored. An asterisk appears if the delta was not applied and not ignored. A code indicating a special reason why the delta was or was not applied: Blankspace Included or excluded usually I Included using the -i flag X Excluded using the -x flag C Cut off using the -c flag The SID. The date and time the file was created. The login name of person who created the delta. Comments and Modification Requests (MR) data follow on subsequent lines, indented one horizontal tab character. A blank line ends each entry. For example, for a delta cutoff with the -c flag, the entry in the l-file might be: `**C 1.3 85/03/13 12:44:16 pat` and the entry for the initial delta might be: `1.1 85/02/27 15:42:20 pat date and time created 85/02/27 15:42:20 by pat`
p-file	The get command creates the p-file when the -e or -k flag is specified. The p-file passes information resulting from a get -e command to a delta command. The p-file also prevents a subsequent execution of a get -e command for the same SID until a delta command is run or the joint edit key letter (j) is set in the SCCS file. The j key letter allows several get commands to be run on the same SID. The p-file is created in the directory containing the SCCS File. To create a p-file in the SCCS directory, you must have write permission in that directory. The permission code of the p-file is read-only to all but its owner, and it is owned by the effective user. The p-file should not be directly edited by the owner. The p-file contains: Current SID SID of new delta to be created User name Date and time of the get command -i flag, if present -x flag, if present The p-file contains an entry with the preceding information for each pending delta for the file. No two lines have the same new delta SID.
z-file	The z-file is a lock mechanism against simultaneous updates. The z-file contains the binary process number of the get command that created it. This file is created in the directory containing the SCCS file and exists only while the get command is running.

When you use the get command, it displays the SID being accessed and the number of lines created from the SCCS file. If you specify the -e flag, the SID of the delta to be made appears after the SID is accessed and before the number of lines created. If you specify more than one file, a directory, or standard input, the get command displays the file name before each file is processed. If you specify the -i flag, the get command lists included deltas below the word Included. If you specify the -x flag, the get command lists excluded deltas below the word Excluded.

The following table illustrates how the get command determines both the SID of the file it retrieves and the pending SID. The SID Specified column shows various ways the SID can be specified with the -r flag. The first column also illustrates various conditions that can exist, including whether or not the -b flag is used with the get -e command. The SID Retrieved column indicates the SID of the file that makes up the g-file. The SID of Delta to Be Created column indicates the SID of the version that will be created when the delta command is applied.

SID Determination

SID Specified	SID Retrieved	SID of Delta to Be Created
none ¹ -b Used? no Other Conditions R defaults to mR ²	mR.mL	mR.(mL+1)
none ¹ -b Used? yes Other Conditions R defaults to mR	mR.mL	mR.mL.(mB+1).1
R -b Used? no Other Conditions R>mR	mR.mL	R.1 ³
R -b Used? no Other Conditions R=mR	mR.mL	mR.(mL+1)
R -b Used? yes Other Conditions R>mR	mR.mL	mR.mL.(mB+1).1
R -b Used? yes Other Conditions R=mR	mR.mL	mR.mL.(mB+1).1
R -b Used? N/A Other Conditions R<mR and R does not exist	hR.mL ⁴	hR.mL.(mB+1) .1
R -b Used? N/A Other Conditions Trunk successor in release > R and R exists	R.mL	R.mL.(mB+1).1
R.L. -b Used? no Other Conditions No trunk successor	R.L.	R.(L+1)
R.L. -b Used? yes Other Conditions No trunk successor	R.L.	R.L(mB+1).1
R.L. -b Used? N/A Other Conditions Trunk successor in release > or = R	R.L.	R.L.(mB+1).1
R.L.B. -b Used? no Other Conditions No branch successor	R.L.B.mS	R.L.B.(mS+1)
R.L.B. -b Used? yes Other Conditions No branch successor	R.L.B.mS	R.L.(mB+1).1
R.L.B.S. -b Used? no Other Conditions No branch successor	R.L.B.S.	R.L.B.(S+1)
R.L.B.S. -b Used? yes Other Conditions No branch successor	R.L.B.S.	R.L.(mB+1).1
R.L.B.S. -b Used? N/A Other Conditions Branch successor	R.L.B.S.	R.L.(mB+1).1

Note: In the SID Determination table, the letters R, L, B, and S are the release, level, branch, and sequence components of the SID. The letter m signifies maximum.

¹ Applies only if the -d (default SID) flag is not present in the file (see the admin command).

² The mR indicates the maximum existing release.

³ Forces creation of the first delta in a new release.

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

Identification Keywords

Identifying information is inserted into the text retrieved from the SCCS file by replacing identification keywords with their value wherever they occur. The following keywords may be used in the text stored in an SCCS file:

Keyword	Value
%M%	Module name: either the value of the m flag in the file, or, if absent, the name of the SCCS file with the s. removed.
%I%	SCCS identification (SID) (%R%.%L% or %R%.%L%.%B%.%S%) of the retrieved text.
%R%	Release.
%L%	Level.
%B%	Branch.
%S%	Sequence.
%D%	Current date, formatted as YY/MM/DD.
%H%	Current date, formatted as MM/DD/YY.
%T%	Current time, formatted as HH:MM:SS.
%E%	Date newest applied delta was created, formatted as YY/MM/DD.
%G%	Date newest applied delta was created, formatted as MM/DD/YY.
01:51:20	Time newest applied delta was created, formatted as HH:MM:SS.
%Y%	Module type: value of the t flag in the SCCS file.
%F%	SCCS file name.
%P%	SCCS absolute path name.
%Q%	The value of the -q flag in the file.
%C%	Current line number. This keyword is intended for identifying messages output by the program, such as `this should not have happened` error messages. The %C% is not intended to be used on every line to provide sequence numbers.
%Z%	The four-character string `@(#)` recognizable by what.
%W%	A shorthand notation for constructing what strings: `%W% = %Z%%M%<tab>%I%`
%A%	Another shorthand notation for constructing what strings: `%A% = %Z%%Y% %M% %I%%Z%`

Flags

Item	Description
-b	Specifies that the delta to be created should have an SID in a new branch. The new SID is numbered according to the rules given in the SID determination table. You can use the -b flag only with the -e flag. It is only necessary when you want to branch from a leaf delta (a delta without a successor). Attempting to create a delta at a nonleaf delta automatically results in a branch, even if the b header flag is not set. If you do not specify the b header flag in the SCCS file, the get command ignores the -b flag because the file does not allow branching.
-c Cutoff	Specifies a cutoff date and time, in the form YY[MM[DD[HH[MM[SS]]]]]. The get command includes no deltas to the SCCS file created after the specified cutoff in the g-file. The values of any unspecified items in the Cutoff variable default to their maximum allowable values. Thus, a cutoff date and time specified with only the year (YY) would specify the last month, day, hour, minute, and second of that year. Any number of nonnumeric characters can separate the two-digit items of the Cutoff variable date and time. This allows you to specify a date and time in a number of ways, as follows: `-c85/9/2,9:00:00 -c"85/9/2 9:00:00" "-c85/9/2 9:00:00"`
-e	Indicates that the g-file being created is to be edited by the user applying the get command. The changes are recorded later with the delta command. The get -e command creates a p-file that prevents other users from issuing another get -e command and editing a second g-file on the same SID before the delta command is run. The owner of the file can override this restriction by allowing joint editing on the same SID through the use of the admin command with the -fj flag. Other users, with permission, can obtain read-only copies by using the get command without the -e flag. The get -e command enforces SCCS file protection specified with the ceiling, floor, and authorized user list in the SCCS file. See the admin command. Note: If you accidentally ruin the g-file created using the get -e command, you can recreate the file with the get -k command.
-g	Suppresses the actual creation of the g-file. Use the -g flag primarily to create an l-file or to verify the existence of a particular SID. Do not use it with the -e flag.
-i List	Specifies a list of deltas to be included in the creation of a g-file. The SID list format consists of a combination of individual SIDs separated by commas and SID ranges indicated by two SIDs separated by a hyphen. You can specify the same SIDs with either of the following command lines: `get -e -i1.4,1.5,1.6 s.file get -e -i1.4-1.6 s.file` You can specify the SCCS identification of a delta in any form shown in the SID Specified column of the previous table. The get command interprets partial SIDs as shown in the SID Retrieved column.
-k	Suppresses replacement of identification keywords in the g-file by their value. The -k flag is implied by the -e flag. If you accidentally ruin the g-file created using the get -e command, you can recreate the file by reissuing the get command with the -k flag instead of the -e flag.
-l[ p ]	Writes a delta summary to an l-file. If you specify -lp, the delta summary is written to standard output, and the get command does not create the l-file. Use this flag to determine which deltas were used to create the g-file currently in use. See the sccsfile file for the format of the l-file. See also the -L flag.
-L	Writes a delta summary to standard output. Specifying the -L flag is the same as using the -lp flag.
-m	Writes before each line of text in the g-file the SID of the delta that inserted the line into the SCCS file. The format is: `SID tab line of text`
-n	Writes the value of the %M% keyword before each line of text in the g-file. The format is the value of %M%, followed by a horizontal tab, followed by the text line. When both the -m and -n flags are used, the format is: `%M% value tab SID tab line of text`
-p	Writes the text created from the SCCS file to standard output and does not create a g-file. All informative output usually sent to standard output is sent to standard error, unless you specify the -s flag with the -p flag. In this case, output usually sent to standard output does not appear anywhere.
-r SID	Specifies the SCCS identification string (SID) of the SCCS file version to be created. The SID determination table shows the version of the created file and the SID of the pending delta as functions of the specified SID.
-s	Suppresses all output usually written to standard output. Error messages (written to standard error output), remain unaffected.
-t	Accesses the most recently created delta in a given release or for a given release and level.
-w String	Substitutes the String value for the %W% keyword in g-files not intended for editing.
-x List	Excludes the specified list of deltas in the creation of the g-file. See the -i flag for the SID list format.

Exit Status

This command returns the following exit values:

Item	Description
0	Successful completion.
>0	An error occurred.

Examples

The following descriptions and examples illustrate the differences between read-only and editable versions of files.

To print the current date and SID in a file, put the following symbols in the file:
```
%H% %I%
```
%H% is the symbol for the current date and %I% is the symbol for the SID. When the get command retrieves a file as editable, it leaves the symbols in the file and does not perform text value substitution.
The following example of the get command builds the version with the highest SID, because the example does not specify a version of the file:
```
$ ls
s.test.c
$ get s.test.c
3.5
59 lines
$ ls
s.test.c test.c
```

In the next two examples, the -r flag specifies which version to get:

$ get -r1.3 s.test.c
1.3
67 lines
 
$ get -r1.3.1.4 s.test.c
1.3.1.4
50 lines

If you specify just the release number of the SID, the get command finds the file with the highest level within that release number.
```
$ get -r2 s.test.c
2.7
21 lines
```
If the SID specified is greater than the highest existing SID, the get command gets the highest existing SID. If the SID specified is lower than the lowest existing SID, SCCS writes an error message. In the following example, release 7 is the highest existing release:
```
$ get -r9 s.test.c
7.6
400 lines
```
The -t flag gets the top version in a given release or level. The top version is the most recently created delta, independent of its location. In the next example, the highest existing delta in release 3 is 3.5, while the most recently created delta is 3.2.1.5.
```
$ get -t -r3 s.test.c
3.2.1.5
46 lines
```
The previous examples use the get command to get a read-only file. To create a copy of the file that can be edited and used to create a new delta, use the get command with the -e flag. Use unget to undo the effect of the get -e command and discard any changes made to the file before a delta is created. The following example shows how to use the -e flag:
```
$ ls
s.test.c
$ get -e s.test.c
1.3
new delta 1.4
67 lines
$ ls
p.test.c s.test.c test.c
```
The working file is test.c. If you edit this file and save the changes with the delta command, SCCS creates a new delta with an SID of 1.4. The file p.test.c is a temporary file used by SCCS to keep track of file versions.
In the previous example, you could have used the -r flag to get a specific version. Assuming release 1 is the highest existing release and that delta 1.3 already exists and is the highest delta in release, the following three uses of the get command are equivalent:
```
$ get -e s.test.c
$ get -e -r1 s.test.c
$ get -e -r1.3 s.test.c
```
To start using a new (higher in value) release number, get the file with the -r flag and specify a release number greater than the highest existing release number. In the next example, release 2 does not yet exist:
```
$ get -e -r2 s.test.c
1.3
new delta 2.1
67 lines
```
Notice that the get command indicates the version of the new delta that will be created if the delta command stores changes to the SCCS file.
To create a branch delta, use the -r flag and specify the release and level where the branch occurs. In the next example, deltas 1.3 and 1.4 already exist.
```
$ get -e -r1.3 s.test.c
1.3
new delta 1.3.1.1
67 lines
```
Creates deltas on branches using the same methods.
To edit a file, get the file version using the get -e command and save the changes with the delta command. Several different editable versions of an SCCS file can exist as long as each one is in a different directory. If you try to put duplicates of an editable file version into a directory (using the get command) without using the delta command, SCCS writes an error message.

To get the same editable file version more than once, set the j header flag in the SCCS file with the admin command. Set the j option by using the -f flag. You can then get the same SID several times from different directories, creating a separate file for each get command. Although the files originate from a single SID, SCCS gives each of them a unique new SID.
In the following example, the pwd command displays the current directory. Then the j option is set with the admin command:

Note: You must have write access in both directories to issue the commands in this example.
```
$ pwd
/home/marty/sccs
$ admin -fj s.test.c
```
Then use the get command to retrieve the latest version of the file:

Note: You must have write access in both directories to issue the commands in this example.
```
$ get -e s.test.c
1.1
new delta 1.2
5 lines
```
Change to the /home/new directory, and issue the get command again.

Note: You must have write access in both directories to issue the commands in this example.
```
$ cd /home/new
$ get -e /home/marty/sccs/s.test.c
1.2
new delta 1.1.1.1
5 lines
```
Notice that SCCS creates two deltas, 1.2 and 1.1.1.1, from the single original file version of 1.1. Look at the p.test.c file. It shows a separate entry for each version currently in use. The p.test.c file remains in the directory until you take care of both file versions with either the delta command or the unget command.

Files

Item	Description
/usr/bin/get	Contains the get command.