NAME

admin - create and administer SCCS files (DEVELOPMENT)

 SYNOPSIS

admin -i[name][-n][-a login][-d flag][-f flag][-m mrlist]
[-r rel][-t[name][-y[comment]] newfile
admin -n[-a login][-d flag][-f flag][-m mrlist][-t[name]][-y[comment]]
newfile ... 
admin [-a login][-d flag][-m mrlist][-r rel][-t[name]]
file ... 
admin -h file ... 
admin -z file ... 

 DESCRIPTION

The admin utility is used to create new SCCS files and change parameters of existing ones. If a named file does not exist, it is created, and its parameters are initialised according to the specified options. Parameters not initialised by an option are assigned a default value. If a named file does exist, parameters corresponding to specified options are changed, and other parameters are left as is.

All SCCS filenames must be of the form s.filename. New SCCS filenames are given read-only permission mode. Write permission in the parent directory is required to create a file. All writing done by admin is to a temporary x-file , named x.filename (see get ) created with read-only mode if admin is creating a new SCCS file, or created with the same mode as that of the SCCS file if the file already exists. After successful execution of admin, the SCCS file is removed (if it exists), and the x-file is renamed with the name of the SCCS file. This ensures that changes are made to the SCCS file only if no errors occur.

The admin utility also uses a transient lock file (named z.filename) which is used to prevent simultaneous updates to the SCCS file. See get for further information.

 OPTIONS

The admin utility supports the XBD specification, Utility Syntax Guidelines  , except that the -i, -t and -y options have optional option-arguments. These optional option-arguments cannot be presented as separate arguments. The following options are supported:

-n

Create a new SCCS file. When -n is used without -i, the SCCS file is created with control information but without any file data.

-i[name]

Specify the name of a file from which the text for a new SCCS file is to be taken. The text constitutes the first delta of the file (see -r option for delta numbering scheme). If the -i option is used, but the name option-argument is omitted, the text is obtained by reading the standard input. If this option is omitted, the SCCS file is created with control information but without any file data. The -i option implies the -n option.

-r rel

Specify the release into which the initial delta is inserted. If the -r option is not used, the initial delta is inserted into release 1. The level of the initial delta is always 1 (by default initial deltas are named 1.1).

-t[name]

Specify the name of a file from which descriptive text for the SCCS file is to be taken. In the case of existing SCCS files (neither -i nor -n is specified):

• A -t option without a name option-argument causes the removal of descriptive text (if any) currently in the SCCS file.
• A -t option with a name option-argument causes the text (if any) in the named file to replace the descriptive text (if any) currently in the SCCS file.

-f flag

Specify a flag, and, possibly, a value for the flag, to be placed in the SCCS file. Several -f options may be supplied on a single admin command line. The allowable flags and their values are:

b

Allow use of the -b option on a get command to create branch deltas.

cceil

Specify the highest release (that is, ceiling), a number less than or equal to 9999, which may be retrieved by a get command for editing. The default value for an unspecified c flag is 9999.

ffloor

Specify the lowest release (that is, floor), a number greater than 0 but less than 9999, which may be retrieved by a get command for editing. The default value for an unspecified f flag is 1.

dSID

Specify the default delta number (SID) to be used by a get command.

istr

Treat the "No id keywords" message issued by get or delta as a fatal error. In the absence of this flag, the message is only a warning. The message is issued if no SCCS identification keywords (see get) are found in the text retrieved or stored in the SCCS file. If a value is supplied, the keywords must exactly match the given string; however, the string must contain a keyword, and no embedded newlines.

j

Allow concurrent get commands for editing on the same SID of an SCCS file. This allows multiple concurrent updates to the same version of the SCCS file.

llist

Specify a list of releases to which deltas can no longer be made (that is, get -e against one of these locked releases fails). The list has the following syntax:

<list> ::= <range> |  <list>, <range>
<range> ::= SID | a

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

n

Cause delta to create a null delta in each of those releases (if any) being skipped when a delta is made in a new release (for example, in making delta 5.1 after delta 2.7, releases 3 and 4 are skipped). These null deltas serve as anchor points so that branch deltas may later be created from them. The absence of this flag causes skipped releases to be non-existent in the SCCS file, preventing branch deltas from being created from them in the future.

qtext

Substitute user-definable text for all occurrences of the %Q% keyword in the SCCS file text retrieved by get.

mmod

Specify the module name of the SCCS file substituted for all occurrences of the %M% keyword in the SCCS file text retrieved by get. If the m flag is not specified, the value assigned is the name of the SCCS file with the leading s. removed.

ttype

Specify the type of module in the SCCS file substituted for all occurrences of the %Y% keyword in the SCCS file text retrieved by get.

vpgm

Cause delta to prompt for modification request (MR) numbers as the reason for creating a delta. The optional value specifies the name of an MR number validation program. (If this flag is set when creating an SCCS file, the m option must also be used even if its value is null.)

-d flag

Remove (delete) the specified flag from an SCCS file. Several -d options may be supplied on a single admin command. See the -f option for allowable flag names. (The flag gives a list of releases to be unlocked. See the -f option for further description of the l flag and the syntax of a list.)

-a login

Specify a login name, or numerical group ID, to be added to the list of users who may make deltas (changes) to the SCCS file. A group ID is equivalent to specifying all login names common to that group ID. Several -a options may be used on a single admin command line. As many logins, or numerical group IDs, as desired may be on the list simultaneously. If the list of users is empty, then anyone may add deltas. If login or group ID is preceded by a !, the users so specified are denied permission to make deltas.

-e login

Specify a login name, or numerical group ID, to be erased from the list of users allowed to make deltas (changes) to the SCCS file. Specifying a group ID is equivalent to specifying all login names common to that group ID. Several -e options may be used on a single admin command line.

-y[comment]

Insert the comment text into the SCCS file as a comment for the initial delta in a manner identical to that of delta. In the POSIX locale, omission of the -y option results in a default comment line being inserted in the form:

"date and time created %s %s by %s", <date>, <time>, <login> where <date> is expressed in the date utility's %y/%m/%d format, <time> in the date utility's %T format and <login> is the login name of the user creating the file.

-m mrlist

Insert the list of modification request (MR) numbers into the SCCS file as the reason for creating the initial delta in a manner identical to delta. The v flag must be set and the MR numbers are validated if the v flag has a value (the name of an MR number validation program). Diagnostics will occur if the v flag is not set or MR validation fails.

-h

Check the structure of the SCCS file and compare the newly computed checksum (the sum of all the characters in the SCCS file except those in the first line) with the checksum that is stored in the first line of the SCCS file. Appropriate error diagnostics are produced.

-z

Recompute the SCCS file checksum and store it in the first line of the SCCS file (see -h above). Note that use of this option on a truly corrupted file may prevent future detection of the corruption.

 OPERANDS

The following operands are supported:

file

A pathname of an existing SCCS file or a directory. If file is a directory, admin behaves as though each file in the directory were specified as a named file, except that non-SCCS files (last component of the pathname does not begin with s.) and unreadable files are silently ignored.

newfile

A pathname of an SCCS file to be created.

If a single instance file or newfile is specified as -, the standard input is read; each line of the standard input is taken to be the name of an SCCS file to be processed. Non-SCCS files and unreadable files are silently ignored.

 STDIN

The standard input is a text file used only if the -i is specified without an option-argument or if a file or newfile operand is specified as -. If the first character of any standard input line is SOH (binary 001), the results are unspecified.

 INPUT FILES

The existing SCCS files are text files of an unspecified format. The file named by the -i option's name option-argument is a text file; if the first character of any line in this file is SOH (binary 001), the results are unspecified.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of admin:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files).

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and the contents of the default -y comment.

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

Not used.

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

Any SCCS files created are text files of an unspecified format. During processing of a file, a locking z-file, as described in get, may be created and deleted.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

It is recommended that directories containing SCCS files be writable by the owner only, and that SCCS files themselves be read-only. The mode of the directories should allow only the owner to modify SCCS files contained in the directories. The mode of the SCCS files prevents any modification at all except by SCCS commands.

 EXAMPLES

None.

 FUTURE DIRECTIONS

A version of admin that fully supports the XBD specification, Utility Syntax Guidelines  may be introduced in a future issue.

 SEE ALSO

delta, get, prs, what.