Current Supported Releases: Sablime® v6.0 & v5.2
NAME
nget - retrieve a version from an SBCS file
SYNOPSIS
nget [-begkpstMNRTY] [-c cutoff] [-l p] [-q seq-no] [-r sid]
[-v name] [-w string] [-G g-name] s-file ...
DESCRIPTION
nget retrieves a version from each SBCS file, or s-file,
matched by the s-file arguments. The version can be gotten
for viewing only or for editing (-e) and is known as the g-
file.
An command line begins with option arguments and ends with
s-file arguments. s-file arguments can be any mix of s-
files, directories and a single - character (see nadmin(1)).
For each valid s-file, nget generates a g-file in the
current directory and prints a two to three line message:
(1) the SBCS ID (SID) of the gotten version, (2) if the file
was gotten for edit, the line new delta followed by the
reserved SID, and (2) or (3), the size of the g-file in
characters (8 bit bytes). If the -v options was used, the
new version name follows the the SID on the new delta line.
The g-file itself has no prefix; its name is the base of the
s-file (no path) with the s. prefix removed. If a version
is gotten for edit (-e), the g-file is writable and a new
SID (Sbcs IDentifier) is reserved for the return of the
edited (new) version. If a version is gotten for viewing,
the g-file is not writable. Accordingly, nget will not
overwrite writable g-files (they may be versions gotten for
edit) but will silently overwrite nonwritable g-files.
Therefore g-file write modes should not be changed by the
user. This ensures that the user will edit only g-files with
reserved SIDs and that nget will not accidentally remove
them.
Getting a file for edit involves up to three SIDs: (1) the
specified SID from the nget command line (if none, the
default SID specified in the s-file; see nadmin(1)), (2) the
gotten SID of the version actually retrieved and (3) the new
SID reserved for the new version. If the file is gotten for
viewing only, only the first 2 SIDs apply. The relations
between these 3 SID is summarized in Table 1. A file
retrieved with nget -e is expected to be either returned as
the new version (see ndelta(1)), or ungotten (see
nunget(1)).
A delta is the difference between one version and its prede-
cessor. By default SBCS stores one complete version (the
base) and many deltas. It is, however, customary to use the
SBCS Release 1.2 Last change: 1 April 1994 1
terms version and delta interchangeably. This is particu-
larly true in SBCS where the only versions that can be got-
ten always correspond to a specific delta.
OPTIONS
-b Used with -e to request that the new version start a
new branch. This option is not necessary if the
retrieved version is not a leaf version, (the last ver-
sion of the trunk or of any branch) because SBCS has to
branch in those cases anyway. This option is ignored
with a warning if the retrieved version is a leaf ver-
sion but the s-file does not have its b flag (branch-
from-leaf) set (nadmin -fb). The behavior of this
option is modified by two sbcsenv(1) variables. If
strict_branch [= no] is reset to yes, the -b option is
needed to create any branch and the command fails if it
cannot get a branch. If allow_branch [= yes] is reset
to no, no new branches can be created with or without
-b and the command will fail if a branch is needed.
-e Get a version for editing. SBCS reserves a new SID for
the version that will be returned with ndelta and
places a record in the p-file. If the s-file does not
allow joint edits (j flag not set), this version is
locked and cannot be gotten for edit again until the
changes have been returned or the edit canceled (ndelta
or nunget). Other versions from the same s-file are
not affected. If the s-file allows joint edits (j flag
set), another edit of the same version by the same or
any other user is possible but it will start a new SID
branch. If all changes must eventually be reflected in
a same version, the branches will have to be merged.
To summarize: concurrent editing is always possible on
different versions, and it is possible on the same ver-
sion if the s-file j flag is set.
A writable g-file (gotten for edit) that is acciden-
tally damaged can be regenerated without a new p-file
record, by using nget -k. The new file is again writ-
able, but no new SID is reserved.
All s-file protections such as ceiling, floor, lock,
user list, etc... (see nadmin(1)) that apply to nget
-e are enforced on the retrieved versions.
Versions retrieved with -e or -k are writable; versions
retrieved in any other way are not writable. Only ver-
sions retrieved with -e should be edited because others
cannot easily be returned to the s-file. The p-file,
in the s-file directory, contains all the information
SBCS keeps on versions retrieved for edit. If a ver-
sion retrieved for edit is lost or is transferred to a
SBCS Release 1.2 Last change: 1 April 1994 2
different user, the p-file record can be directly
edited by the SBCS administrator.
-g No g-file. No version is actually retrieved, but the
SID that would have been gotten is printed. This can
be used to verify if a SID exists, or which SID would
actually be gotten, or to generate an l-file without a
g-file.
-k Keep the ID keywords. As with -e, the g-file ID key-
words are not expanded and the g-file is left writable.
Unlike -e, no new SID is reserved and no new p-file
record is made. This can be used to recreate an edit-
able g-file that was removed or lost. On its own, -k
does not leave the g-file in a consistent state,
because it would be writable without a p-file record.
-p Send the retrieved version to standard output instead
of creating a g-file. If used with -e, this will com-
plicate returning the file. Output that normally goes
to standard output is redirected to standard error.
nget will not allow a binary file to sent to the
screen, but this can forced by piping through cat(1),
e.g.. is a terminal.
-s Run silently. Output normally written to standard out-
put and all warnings are suppressed. Actual errors are
not affected.
-t Retrieve the latest or topmost version, trunk or
branch, matching the SID specified by -r or the default
SID. If the specified SID is R.L.B this is the default
behavior. If there is no specified or default SID, the
latest branch of the last trunk version is retrieved,
or the last trunk version itself if it has no branch.
In general, if there are no branches, -t duplicates the
default behavior. Option -t cannot be used with either
-q or -c.
-M Preserve the original file read and executable modes.
The g-file will have the read and execute permission
modes of the original version. The write modes are
always determined by nget and depend on whether the
file was retrieved with -e or not. The user's umask
may also constrain the final g-file modes to be less
than the nget defaults (444 and 644). This feature is
also be controlled by the sbcsenv variable
use_delta_mode [= no]. If this variable is reset to
yes, -M is implied for every nget issued.
-N No execution. nget simply prints the s-file and g-file
pairs it would normally process, but no processing is
SBCS Release 1.2 Last change: 1 April 1994 3
done. This is useful to preview what nget would do
when s-file arguments represent multiple files.
-R Recursive mode. For all s-file arguments that are
directories, descend recursively into all subdirec-
tories to search for s-files. The g-files are written
out in corresponding subdirectories. The sbcsenv vari-
able recursive [= no] can be reset to y to keep recur-
sive mode on at all times.
-T Preserve the original file date and time. This option
sets the g-file modification time to the original ver-
sion creation time. The g-file access time is not
affected. This feature is also controlled by the
sbcsenv(1) variable use_delta_time [= no]. If this
variable is reset to yes, -T is implied for every nget
issued.
-Y Suppress any y/n prompt that may arise by always
answering y. The sbcsenv variable answer_yes [= no]
can be reset to y to imply the -Y option for all com-
mands. See NOTES in nadmin(1) and below.
-a seq-no
Retrieve the version with this delta sequence number.
This option is provided for compatibility with previous
versions and SCCS. It has been renamed -q.
-c cutoff
Retrieve the latest version returned prior to the
date-time cutoff. The cutoff should be in the format
yy[mm[dd[HH[MM[SS]]]]]. Fields omitted default to
their maximum value. For example, -c7502 is equivalent
to -c"75/02/28 23:59:59". Nonnumeric characters may
separate the various 2 digit components. If spaces are
used, the cutoff must be quoted. If no SID is speci-
fied, only trunk versions are examined. If a SID is
specified, it must specify an incomplete SID (R or
R.L.B). If R.L.B is specified, the branch is examined
from its tip (leaf) down to where it meets the trunk,
then the remaining trunk is examined. Because the -c
and -r specify the gotten SID, there is no independent
way to specify a requested SID. Rather than arbitrarily
start a new branch off the gotten SID, the -c and -e
combination is disallowed. Option -c cannot be used
with either -t or -q.
-l p Write the delta log of the gotten version. p can be
either - or p. If it is the character -, the delta
summary is written to the l-file in the current direc-
tory. The l-file is named after the s-file by changing
the base name s. prefix to an l. prefix. If p is the
SBCS Release 1.2 Last change: 1 April 1994 4
character p, the delta summary is written to standard
output and no l-file is created. The l-file is list of
all the s-file deltas with those contributing to this
version specially (un)marked. The format is reviewed in
FILES l-file, below.
-q seq-no
Retrieve the version with this delta sequence number.
The SID interface is the usual and recommended one, but
sometimes it is useful to be able to access versions by
their delta sequence number (SEQ). The SEQ should not
be confused with the SID sequence number that is the
last number of a complete R.L.B.S specification (-r
below). The SEQ is simply the chronological rank of a
delta: the first delta made has SEQ 1, the second has
SEQ 2, etc... and the SEQ of last delta made is the
number of deltas in the s-file. Removed deltas (see
nrmdel(1)) keep their SEQ but their SID can be reused
by new versions. Only ncomb(1), by completely redoing
the s-file, can change the version SEQs.
If the -r option is also given, it must be R (release)
only, and will be used by nget to determine the new
SID. This only works if delta R.1 is available. If it
isn't, the requested release is ignored an a new branch
off the gotten SID is returned. This combination of
options is maintained for compatibility with SCCS only;
its use is otherwise discouraged. If there is a need
to take a specific version to continue a specific
branch or trunk, this is best done in two steps: an
nget -e -g to reserve the desired SID, followed by an
nget -k to get a g-file of the desired version.
Option -q cannot be used with either -c or -t.
-r sid
Get the version specified by sid. sid can be a partial
or complete SID, or a version name. A complete SID for
a delta (or version) is an identifier composed of two
or four period separated fields. A valid field is a
number between 1 and 9999. Trunk versions have two
fields: RELEASE and LEVEL, or R.L. Branch versions
have four fields: R.L and BRANCH and SEQUENCE, or
R.L.B.S. E. g., 1.2 is a trunk SID, with release 1 and
level 2; 4.2.3.1, is a branch SID off trunk SID 4.2 and
it is the first sequence of branch 3 off that node.
Note that all branches attach directly to the trunk (no
branch from branch). A branch that is created from
another branch automatically reattaches to the trunk.
nget accepts incomplete SIDs and is often used that
way. When -r is omitted altogether, nget normally gets
SBCS Release 1.2 Last change: 1 April 1994 5
the highest release and level (the highest trunk ver-
sion). If the s-file d flag is set to a default
release and a SID is not specified, nget retrieves a
SID with this release instead.
When the R is specified, but not L, nget retrieves the
highest level in that release. If the release does not
exist, nget retrieves the highest level from the next-
highest existing release. Branches are treated simi-
larly: if R.L.B is specified, nget retrieves the
highest sequence in that branch (the branch leaf).
Given the SID (or partial SID) specified by nget -e,
Table 1 shows the SID gotten for editing and the new
SID reserved for the new version.
sid can also be a version name. Version names are used
as optional mnemonic complements to SID. Different SIDs
in different s-files can have the same name and nget
can use that name to track product (multi-file) ver-
sions. A version name cannot begin with a digit or any
of the characters "+-~#"nor can it contain commas or
blank space. SBCS commands will accept version names
instead of SIDs everywhere SIDs are expected, except
where the SID must be a numerical R (release) specifi-
cation.
-v name
Used with the -e option, this reserves the name name
for the new version (see -r above). A version
retrieved with nget -v name can be returned with ndelta
-r name or, once returned, can be gotten again by nget
-r name. A version cannot be named at the time it is
returned: this could cause name conflicts difficult to
resolve when multiple files are returned. So the name
must be reserved either from the start, using nget -v
or before being returned, using ncdc -v.
-w string
Substitute string for all occurrences of the popular
%W% ID keyword when retrieving the file. The %W% ID
keyword otherwise expands to a standard what string
(see nwhat(1) and what(1)).
-G g-name
Specify an alternative name for the g-file. The g-name
name specified can also be a directory. If the s-file
argument is a directory or if the s-file arguments
evaluate to more than one actual s-file then the g-file
name specified by -G must be a directory. If the
directory does not exist, the user will be prompted for
the directory to be created. The -Y option suppresses
SBCS Release 1.2 Last change: 1 April 1994 6
prompting and provides default y answers to all such
prompts. If nget needs to prompt but the s-file argu-
ment is a - or the option -s was used, an error is
declared and nget moves on to the next s-file speci-
fied.
g-name can also be used with a leading or trailing
comma to specify a prefix or a suffix on the regular
g-file. For example,
nget -Gpfx., s.file
creates a g-file named pfx.file and
nget -G,.sfx s.file
creates a g-file named file.sfx.
COMMENTS
For each file retrieved, nget prints (1) the gotten SID, (2)
the new SID reserved and (3) the size the g-file retrieved.
If the -e option is not used, there is no new SID. If the
-g option is used there is no g-file and only (1) is
printed. If there is more than one file argument or if the
file argument is a directory or the standard input, a new-
line and the file name is printed before each file is pro-
cessed. -s suppresses this information.
SBCS Release 1.2 Last change: 1 April 1994 7
Table 1: SID Determination for nget -e
____________________________________________________________
SID* -b Other SID new SID
Specified Used- Conditions Retrieved Reserved
____________________________________________________________
none= n mR.mL mR.(mL+1)
none= y mR.mL mR.mL.(mB+1).1
R n R > mR mR.mL R.1***
R n R = mR mR.mL mR.(mL+1)
R y R > mR mR.mL mR.mL.(mB+1).1
R y/n R < mR and R
does not exist hR.mL** hR.mL.(mB+1).1
R y/n R < mR and
R exists R.mL R.mL.(mB+1).1
R.L y/n R.L does
not exist Error
R.L n R.L = mR.mL R.L R.(L+1)
R.L y R.L = mR.mL R.L R.L.(mB+1).1
R.L y/n R < R.mL R.L R.L.(mB+1).1
R.L.B y/n R.L.B does
not exist Error
R.L.B n B = mB R.L.B.mS R.L.B.(mS+1)
R.L.B y B = mB R.L.B.mS R.L.(mB+1).1
R.L.B y/n B < mB R.L.B.mS R.L.(mB+1).1
R.L.B.S y/n R.L.B.S
does not exist Error
R.L.B.S n S = mS R.L.B.mS R.L.B.(mS+1)
R.L.B.S y S = mS R.L.B.mS R.L.(mB+1).1
R.L.B.S y/n S < mS R.L.B.S R.L.(mB+1).1
____________________________________________________________
* R, L, B and S are the Release, Level, Branch and
Sequence components of the SID, and m means maximum.
For example, R.mL means the maximum level for release
R; R.L.(mB+1).1 means the first sequence number on a
new branch (i.e., maximum branch number plus one) of
release R level L. If the SID indicated is of the form
R.L, R.L.B or R.L.B.S, then all the specified com-
ponents must exist.
** hR is the highest existing release that is lower than
the specified, nonexistent, release R.
*** This option is used to create of the first version in a
new release (see nadmin -r -i).
- The -b option is effective only if the s-file has its b
flag set (see nadmin. Otherwise a warning is issued and
the -b is ignored.
SBCS Release 1.2 Last change: 1 April 1994 8
= This case applies if the s-file has no default SID
specified (see nadmin -fd). If the s-file has a
default SID then it is used as if it had been specified
on the command line, and one of the other cases
applies.
NGET ID KEYWORDS
If nget is used without -e and -k, and if the s-file does
not have its x flag set (see nadmin), the version retrieved
is considered a text file an undergoes ID keyword expansion.
The file is scanned for SBCS ID keywords and these are sub-
stituted with their actual value. The following are the
nget ID keywords:
____________________________________________________________
Keyword Value
____________________________________________________________
%A% Popular what string for non-UNIX system program
files. Equivalent to %Z%%Y% %M% %I%%Z%
%B% Branch value of this version's SID.
%C% Current line number. Used to identify source
lines in program messages that need them. In C
source the __LINE__ preprocessor macro should be
preferred.
%D% Current date, YY/MM/DD format.
%E% Date this version was created, YY/MM/DD format.
%F% SBCS file name.
%G% Date this version was created, MM/DD/YY format.
%H% Current date, MM/DD/YY format.
%I% This version's SID or SBCS R.L.B.S identifier,
equivalent to %R%.%L%.%B%.%S%.
%L% Level of this version's SID.
%M% Module name: either the value given to the s-file
m flag (see nadmin), or if absent, the name of the
SBCS s-file without the leading s. prefix.
%P% Full path name of SBCS s-file.
%Q% Value of the s-file q flag (see nadmin).
%R% Release of this version's SID.
%S% Sequence of this version's SID.
%T% Current time, HH:MM:SS format.
%U% Time this version was created, HH:MM:SS.
%V% Symbolic name of this version.
%W% Popular what string used in UNIX system program
files. Equivalent to %Z%%M%<tab>%I%.
%Y% Module type: value of the t flag in the SBCS file
(see nadmin).
%Z% The 4-character string @(#) recognized by nwhat
(and what).
____________________________________________________________
SBCS Release 1.2 Last change: 1 April 1994 9
FILES
g-file
The g-file, or gotten file, is created in the current
directory. The g-file name is the name of the s-file
without the s. prefix. It is owned by the real user
and real group, even if nget was set-UID. If -e or -k
was used, the default g-file mode is 644, otherwise it
is 444. The actual mode is modified by the process
umask value (see umask(1,2)).
l-file
The l-file is generated by the -l option and is created
in the current directory. The l-file name is the name
of the s-file with the s. prefix changed to l. . It is
owned by the real user and group, even if nget was run
set-UID. It contains a listing of all deltas in the
s-file and information to identify those applied in
calculating the companion g-file. The default l-file
mode is 444; the actual mode is modified by the process
umask value. Lines in the l-file have the following
fields, separated by blanks:
a. a leading blank,
b. a blank character if the delta was applied in
creating the g-file, and * otherwise,
c. a code of up to 3 of the following characters,
identifying the type of the delta:
D: Regular delta
R: Removed delta
b: A base version of the file
d: A delta version (i.e., not a base ver-
sion),
c: if the base or delta was compressed,
n: if the base or delta has size 0 (null del-
tas).
d. SBCS id (SID),
e. yy/mm/dd HH:MM:SS, date and time version was
created,
f. UID password name of the version author,
g. sequence number of this delta,
h. predecessor delta sequence number,
i. version name, if any.
Comments and MRs follow on subsequent lines, indented
by one horizontal tab. A blank line terminates each
entry.
p-file
A p-file always exists after an nget -e; it is created
in the s-file directory with mode 66x. The p-file name
is the name of the s-file with the s. prefix changed to
SBCS Release 1.2 Last change: 1 April 1994 10
p. . This file contains all the information SBCS keeps
on what versions have been retrieved, what versions
have been reserved, by whom and when. nget checks this
file to prevent (s-file j flag off) or warn about (s-
file j flag on) joint edits. ndelta also checks it to
see if and where a new version can be unambiguously
returned. Other commands (nunget(1),nsact(1),ncomb(1))
also use the p-file information. The p-file is
accessed and edited using the effective user and effec-
tive group permissions of the command. These permis-
sions must be enough to write in the s-file directory,
or a file cannot be retrieved for editing. The p-file
mode is 644, with only the last 2 fields (-44) modified
by the command's umask. The format of the p-file is:
a. gotten SID;
b. Blank;
c. new SID reserved;
d. Blank;
e. UID password name of author;
f. Blank;
g. Date and time nget was executed.
The p-file has as many of these records as is needed to
keep track of all the activity on the corresponding s-
file at any given time. No two records can have the
same reserved SID.
q-file
The q-file is a temporary p-file, in the s-file direc-
tory. nget copies the p-file to a new q-file and edits
the copy. Only if the command succeeds does nget sub-
stitute the q-file for the p-file.
z-file
The z-file is a transient lock file used to prevent
simultaneous changes to the s-file. It contains the
process id of the process that has secured the lock.
build.xNNNNN
Temporary files created when memory streams become too
large (around 1.2 Mbytes). These files are created in
the directory specified by one of the env variables
TMPDIR, TEMP or TMP, or the sbcsenv variable tmpdir [=
"/tmp"]. These files are removed before the command
finishes. For large g-files, a temporary g-file is
created in the current directory and later becomes the
actual g-file.
NOTES
Multiple Files
nget needs only a partial specification of the version
SBCS Release 1.2 Last change: 1 April 1994 11
to retrieve, and is therefore an effective multi-file
command.
Multi-User
nget does not modify s-files but does create or modify
p-files. When used in a multi-user project, nget needs
to be run set-UID with the SBCS administrator's permis-
sions (see nadmin(1) - MULTI USER ACCESS and
sbcsproj(1)).
Y/N Prompts
Such prompts can be unexpected and arise from (1) a
request to restore the s-file (2) a request to create a
new g-file directory. Specifying -Y provides a default
y answer. Because the user must already have write
permission in the s-file directory, any restore is
expected to succeed.
COMPARISON WITH SCCS
SCCS only:
-isid-list and -xsid-list, to selectively include and
exclude deltas. -m to tag lines with their SID and -n
to tag lines with %M%<tab>.
SBCS only:
Version names with -r and -v.
The -NRY, -M, -T options.
The -G option exists in BSD UNIX versions of SCCS and
has been generalized here to allow directories, and
prefix and suffix options.
The %V% ID keyword.
SBCS has a more general definition of s-file arguments
that includes s-file argument resolution through the
sbcsenv(1) variable source_tree.
Differences:
The %F% ID keyword in SCCS for the file name actually
includes the relative path name to the directory where
the get is done. In SBCS the ID keyword expands to the
file name only. The format fo the l-file differs
slightly from SCCS, and now includes the version name
as a last field.
DIAGNOSTICS
Warning and error messages have error codes that can be used
with nhelp for a more detailed explanation.
SEE ALSO
nadmin(1), ncdc(1), ndelta(1), nget(1), nhelp(1), nprs(1),
nrmdel(1), nunget(1), sbcsdiff(1), sbcsenv(1), sidtree(1).
SBCS Release 1.2 Last change: 1 April 1994 12
Return to SBCS Commands manpage index
Copyright © 2003
Lucent Technologies