[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Commands Reference, Volume 1


admin Command (SCCS)

Purpose

Creates and controls Source Code Control System (SCCS) files.

Syntax

To Create New SCCS Files

admin { -n -i[FileName ] } [ -a { User | GroupID } ] ... [ -f HeaderFlag[Value ] ... ] [ -r SID ] [ -t FileName ] [ -m ModificationRequestList ] [ -y[Comment ] ] File ...

Note: Do not put a space between a flag and an optional (bracketed) variable.

To Modify Existing SCCS Files

admin [ -a { User | GroupID } ] ... [ -e { User | GroupID } ] ... [ { -d HeaderFlag | -f HeaderFlag[Value ] ... } ] [ -m ModificationRequestList ] [ -t[FileName ] ] [ -y[Comment ] ] File ...

Note: Do not put a space between a flag and an optional (bracketed) variable.

To Check Damaged SCCS Files

admin -h File ...

To Correct Damaged SCCS Files

admin -z File ...

Description

The admin command creates new Source Code Control System (SCCS) files or changes specified parameters in existing SCCS files.

The admin command can change the parameters controlling how the get command builds the files that you can edit. The parameters can also set conditions about who can access the file and which releases of the files may be edited.

If the file specified by the File parameter exists, the admin command modifies the file as specified by the flags. If the file does not exist and you supply the -i or -n flag, the admin command creates a new file and provides default values for unspecified flags.

If you specify a directory name for the File parameter, the admin command performs the requested actions on all SCCS files in that directory. All SCCS files contain the s. prefix before the file name. If you use a - (minus sign) for the File parameter, the admin command reads standard input and interprets each line as the name of an SCCS file. An end-of-file character ends input.

You must have write permission in the directory to create a file. All SCCS file names must have the form s.Name. New SCCS files are created with read-only permission. The admin command writes to a temporary x-file, which it calls x.Name. If it already exists, the x-file has the same permissions as the original SCCS file. The x-file is read-only if the admin command must create a new file. After successful completion of the admin command, the x-file is moved to the name of the SCCS file. This ensures that changes are made to the SCCS file only if the admin command does not detect any errors while running.

Directories containing SCCS files should be created with permission code 755 (read, write, and execute permissions for owner, read and execute permissions for group members and others). The SCCS files themselves should be created as read-only files (444). With these permissions, only the owner can use non-SCCS commands to modify SCCS files. If a group can access and modify the SCCS files, the directories should include group write permission.

The admin command also uses a temporary lock file (called z.Name), to prevent simultaneous updates to the SCCS file by different users.

You can enter flags and input file names in any order. All flags apply to all the files. Do not put a space between a flag and an optional variable (variable enclosed in bracket). Header flags can be set with the -f flag and unset with the -d flag. Header flags control the format of the g-file created with the get command.

Flags


-a User or -a GroupID Adds the specified user to the list of users that can make sets of changes (deltas) to the SCCS file. The User value can be either a user name or a group ID. Specifying a group ID is the same as specifying the names of all users in that group. You can specify more than one -a flag on a single admin command line. If an SCCS file contains an empty user list, anyone can add deltas. If a file has a user list, the creator of the file must be included in the list in order for the creator to make deltas to the file. If the User or GroupID parameter is preceded by an ! (exclamation point), specified users are denied permission to make deltas. For example, enter -a !User.
-d HeaderFlag Deactivates the effects of the specified header flag within the SCCS file. You can specify this flag only with existing SCCS files. You can also specify more than one -d flag in a single admin command. Refer to the list of header flags that follows to learn more about the supported values.
-e User or -e GroupID Removes the specified user from the list of users allowed to make deltas to the SCCS file. Specifying a group ID is equivalent to specifying all User names common to that group. You can specify several -e flags on a single admin command line.
-f HeaderFlag[Value ] Activates the specified header flag and value in the SCCS file. You can specify more than one header flag in a single admin command. There are 12 header flags. Refer to the list of header flags that follows to learn more about the supported values. Do not put a space between the HeaderFlag and Value variables.
-h Checks the structure of the SCCS file and compares a newly computed checksum with the checksum that is stored in the first line of the SCCS file. When the checksum value is not correct, the file has been improperly modified or damaged. This flag helps you detect damage caused by the improper use of non-SCCS commands to modify SCCS files, as well as accidental damage. The -h flag prevents writing to the file, so it cancels the effect of any other flags supplied. If an error message is returned indicating the file is damaged, use the -z flag to re-compute the checksum. Then test to see if the file is corrected by using the -h flag again.
-i[FileName ] Gets the text for a new SCCS file from the FileName variable. This text is the first delta of the file. If you specify the -i flag but omit the file name, the admin command reads the text from standard input until it reaches an end-of-file character. If you do not specify the -i flag, but you do specify the -n flag, the command creates an empty SCCS file. The admin command can only create one file containing text at a time. If you are creating two or more SCCS files with one call to the admin command, you must use the -n flag, and the SCCS files created will be empty. Each line of the file specified by the FileName variable cannot contain more than 512 characters. The file name can include MBCS (multibyte character set) characters. Do not put a space between the flag and the FileName variable.
-m ModificationRequestList Specifies a list of Modification Request (MR) numbers to be inserted into the SCCS file as the reason for creating the initial delta. A null or empty list can be considered valid, depending on the validation program used. The v header flag must be set. The MR numbers are validated if the v header flag has a value (the name of an MR number validation program). The admin command reports an error if the v header flag is not set or if MR validation fails.
-n Creates a new, empty SCCS file. When the -n flag is used without the -i flag, the SCCS file is created with control information but without any file data.
-r SID Specifies the SCCS identification string (SID) file version to be created. The SID variable accepts a delta with four levels: release, level, branch, and sequence, for example 3.2.5.1. If only release is specified, the admin command automatically assumes level 1. If you do not specify the -r flag, the initial delta becomes release 1, level 1 (that is, 1.1). For more details on specifying the SID, refer to the SID Determination table described in the get command.

You can specify the -r flag only if you also specify the -i or -n flag. Use this flag only when creating an SCCS file.

-t [FileName] Takes descriptive text for the SCCS file from the file specified by the FileName variable. If you use the -t flag when creating a new SCCS file, you must supply a file name. In the case of existing SCCS files:
  • Without a file name, the -t flag removes any descriptive text currently in the SCCS file.
  • With a file name, the -t flag replaces any descriptive text currently in the SCCS file with text in the named file.
  • The file name can include MBCS (multibyte character set) characters.

Do not put a space between the flag and the FileName variable.

-y [Comment] Inserts the specified comment into the initial delta in a manner identical to that of the delta command. Use this flag only when you create an SCCS file. If you do not specify a comment, the admin command inserts a line of the following form:

date and time created YY/MM/DD HH:MM:SS by Login

The comments can include MBCS (multibyte character set) characters. Do not put a space between the flag and the FileName variable.

-z Re-computes the SCCS file checksum and stores it in the first line of the SCCS file (see the -h flag).

Attention: Using the admin command with the -z flag on a damaged file can prevent future detection of the damage. This flag should only be used if the SCCS file is changed using non-SCCS commands because of a serious error.
File Specifies the name of the file created or altered by the admin command. If a - (minus sign) is specified, the admin command reads from standard input. An end-of-file character ends standard input.

Header Flags

The following list contains the header flags that can be set with the -f flag and unset with the -d flag. Header flags control the format of the g-file created with the get command.

b Lets you use the -b flag of a get command to create branch deltas.
c Number Makes the Number variable the highest release number that a get -e command can use. The value of the Number variable must be greater than 0 and less than or equal to 9999. (The default value is 9999.)
d SID Makes the SID variable the default delta supplied to a get command.
f Number Makes the Number variable the lowest release number that a get -e command can retrieve. The Number variable must be greater than 0 and less than 9999. (The default value is 1.)
i [String] Treats the following informational message, issued by the get or delta command, as an error:

There are no SCCS identification keywords in the file. (cm7) 

In the absence of this flag, the message is only a warning. The message is issued if no SCCS identification keywords are found in the text retrieved or stored in the SCCS file (refer to the get command). If a string is supplied, the keywords must match exactly the given string. The string must contain a keyword and have no embedded newlines.

j Permits concurrent get commands for editing the same SID of an SCCS file. Use of the j header flag allows multiple concurrent updates to the same version of the SCCS file.
lList (lowercase L) Locks the releases specified by the List variable against editing, so that a get -e command against one of these releases fails. The list has the following syntax:

<List> : : = <Range> | <List> , <Range>
<Range> : : = SID | a

where character a in the list is equivalent to specifying all releases for the named SCCS file.

m Module Substitutes the Module variable for all occurrences of the 59 keyword in an SCCS text file retrieved by a get command. The default Module variable is the name of the SCCS file without the s. prefix. The module name can include MBCS (multibyte character set) characters.
n Causes the delta command to create a null delta in any releases that are skipped when a delta is made in a new release. For example, if you make delta 5.1 after delta 2.7, releases 3 and 4 will be null. Releases 3 and 4 will be created as null delta entries in the delta table of the s. file. The resulting null deltas can serve as points from which to build branch deltas. Without this flag, skipped releases do not appear in the SCCS file.
q Text Substitutes the specified text for all occurrences of the keyword in an SCCS text file retrieved by a get command.
t Type Substitutes specified type for all keywords in a g-file retrieved by a get command.
v [Program] Makes the delta command prompt for Modification Request (MR) numbers as the reason for creating a delta. The Program variable specifies the name of an MR-number validity-checking program. If the v flag is set in the SCCS file, the -m flag must also be used, even if its value is null. The program name can include MBCS (multibyte character set) characters.

Locating Damaged SCCS Files

Although SCCS provides some error protection, you may need to recover a file that was accidentally damaged. This damage may result from a system malfunction, operator error, or changing an SCCS file without using SCCS commands.

SCCS commands use the checksum to determine whether a file was changed since it was last used. The only SCCS command that processes a damaged file is the admin command when used with the -h or -z flags. The -h flag tells the admin command to compare the checksum stored in the SCCS file header against the computed checksum. The -z flag tells the command to re-compute the checksum and store it in the file header.

Exit Status

This command returns the following exit values:

0 Successful completion.
>0 An error occurred.

Examples

These examples use an imaginary text file called test.c and an editor such as ed to edit files.

  1. First, create an ordinary SCCS file. To create an empty SCCS file named s.test.c, enter:

    $ admin -n s.test.c
    

    Using the admin command with the -n flag creates an empty SCCS file.

  2. To convert an existing text file into an SCCS file, enter:

    $ admin -itest.c s.test.c
    There are no SCCS identification keywords in the file (cm7)
    $ ls
    s.test.c test.c
    

    If you use the -i flag, the admin command creates delta 1.1 from the specified file. Once delta 1.1 is created, rename the original text file so it does not interfere with SCCS commands:

    $ mv test.c back.c
    

    The message There are no SCCS identification keywords in the file (cm7) does not indicate an error. SCCS writes this message when there are no identification keywords in the file. Identification keywords are variables that can be placed in an SCCS file. The values of these variables provide information such as date, time, SID, or file name. See the get command for an explanation of identification keywords. If no identification keywords exist, SCCS writes the message. However, if the i header flag is set in the s. file, this message causes an error condition. This flag is set by the user.

    Give the SCCS file any name, beginning with s.. In the preceding example, the original file and the SCCS file have the same name, but that is not necessary.

    Because you did not specify a release number, the admin command gave the SCCS file an SID of 1.1. SCCS does not use the number 0 to identify deltas. Therefore, a file cannot have an SID of 1.0 or 2.1.1.0, for example. All new releases start with level 1.

  3. To start the test.c file with a release number of 3.1, use the -r flag with the admin command, as shown below, and enter:

    $ admin -itest.c -r3 s.test.c
    

    To restrict permission to change SCCS files to a specific set of user IDs, list user IDs or group ID numbers in the user list of the SCCS file by using the -a flag of the admin command. This flag may appear multiple times on the command line. These IDs then appear in the SCCS file header. Without the -a flag to restrict access, all user IDs can change the SCCS files.

  4. To restrict edit permission to the user ID dan, enter:

    $ admin -adan s.test.c
    
  5. Check SCCS files on a regular basis for possible damage. The easiest way to do this is to run the admin command with the -h flag on all SCCS files or SCCS directories, as follows:

    $ admin -h s.file1 s.file2 ...
    $ admin -h directory1 directory2 ...
    

    If the admin command finds a file where the computed checksum is not equal to the checksum listed in the SCCS file header, it displays this message:

    ERROR [s. filename]:
    1255-057 The file is damaged. (co6)
    

    If a file was damaged, try to edit the file again or read a backup copy. After fixing the file, run the admin command with the -z flag and the repaired file name:

    $ admin -z s.file1
    

    This operation replaces the old checksum in the SCCS file header with a new checksum based on the current file contents. Other SCCS commands can now process the file.

Files


/usr/bin/admin Contains the SCCS admin command.

Related Information

The delta command, ed command, get command, prs command, sccshelp command, what command.

The sccsfile file format.

List of SCCS Commands in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

Source Code Control System (SCCS) Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]