get(1)								       get(1)



NAME

  get - Creates a specified version of a Source Code Control System (SCCS)
  file

SYNOPSIS

  get [-g] [-L] [-m] [-n] [-p] [-s] [-t] [-ccutoff] [-ilist] [-rSID]
  [-wstring] [-xlist] file ...	| -

  get [-aseq_num] [-b] [-e] [-k] [-s] [-t] [-ccutoff] [-ilist] [-rSID]
  [-xlist] [-l | -lp] file ...	| -

  The get command reads the specified versions of the named SCCS files, and
  creates a text file (the g-file), for each file according to the specified
  flags. The command then writes each text file to a file with the same name
  as the original SCCS file without the s. (s period) prefix.

FLAGS

  -aseq_num
      Specifies the delta sequence number of the SCCS file delta (version)
      that is be retrieved.  This keyletter is used by the comb command.

  -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 stated in the
      table SID Determination.	You can use -b 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, get
      ignores the -b flag because the file does not allow branching.

  -ccutoff
      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
      cutoff 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 non-
      numeric characters can separate the 2-digit items of the cutoff date
      and time.	 This allows you to specify a date and time in a number of
      ways, as follows:
	   -c90/9/2,9:00:00
	   -c"90/9/2 9:00:00"
	   "-c90/9/2 9:00:00"


  -e  Indicates that the g-file being created is to be edited by the user
      applying get.  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 and editing a second g-file on the same SID
      before delta 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 get without the -e flag.  The get
      -e command enforces SCCS file protection specified via the ceiling,
      floor, and authorized user list in the SCCS file (see the admin com-
      mand).

  -g  Suppresses the actual retrieval of text from the SCCS file.  Use the -g
      flag primarily to create an l-file or to verify the existence of a par-
      ticular SID.  Do not use it with the -e flag.

  -ilist
      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, as shown in the following example:
	   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 table SID Determination.	The get com-
      mand interprets partial SIDs as shown in the SID Retrieved column of
      the table.

  -k  Suppresses replacement of identification keywords in the g-file by
      their values.  The -k flag is implied by the -e flag.  If you acciden-
      tally ruin the g-file created by get with an -e flag, you can recreate
      it by reissuing the get command with the -k flag in place of the -e
      flag.

  -l[p]
      Writes a delta summary to an l-file.

      If you specify -lp, get interprets it as -L. The -lp option is
      obsolete.

  -L  Writes a delta summary to standard output and does not create an l-
      file.  All informative output that normally is written to standard out-
      put is written to standard error instead, unless the -s flag is speci-
      fied, in which case it is suppressed.  Use this flag to determine which
      deltas were used to create the g-file currently in use.

  -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 as follows:
	   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 as follows:
	   %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.  The get command sends output normally sent to
      standard output to file descriptor 2 instead.  If you specify the -s
      flag with the -p flag, output normally sent to standard output does not
      appear anywhere.	Do not use -p with the -e flag.

  -rSID
      Specifies the SCCS identification string (SID) of the SCCS file version
      to be created.  Shows what version of a file is created and the SID of
      the pending delta as functions of the SID specified.

  -s  Suppresses all output normally 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 release
      and level.  Without the -r flag, get accesses the most recent delta
      regardless of its SID.

  -wstring
      Substitutes string for the %W% keyword in g-files not intended for
      editing.

  -xlist
      Excludes a list of deltas in the creation of a file.  See the -i flag
      for the SID list format.

DESCRIPTION

  The flags and files can be specified in any order, and all flags apply to
  all named files.  If you specify a directory in place of file, get performs
  the requested actions on all the files in the directory that begin with the
  s. prefix.  If you specify a - (dash) in place of file, get reads standard
  input and interprets each line as the name of an SCCS file.  The get com-
  mand 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.

  SCCS Files

  In addition to the file with the s. prefix (the s-file), get can create
  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 dash.
  The get command names auxiliary files by replacing the leading s. in the
  SCCS filename with the proper tag, except for the g-file, which is named by
  removing the s. prefix.  So, for a file named s.sample, the auxiliary
  filenames would be sample, l.sample, p.sample, and z.sample.

  These files serve the following purposes:

  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 what
      the changes were.	 You cannot edit this file directly, because the file
      is read-only.  It contains the information needed by the SCCS commands
      to build the g-file, the file you can edit.

  g-file
      A 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
      you want to make a new delta to the file, you can then apply the delta
      command to the file.  The get command creates the g-file in the current
      directory.

      The get command creates a g-file whenever it runs, 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 the -e flag, the file is read-
      only.  If the -k or the -e flag is specified, the owner has write per-
      mission 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 (a read-only file) when the -l flag
      is specified.  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 space if the delta was applied; an * (asterisk) appears otherwise.

	+
	A space if the delta was applied or was not applied and ignored; an *
	appears if the delta was not applied and was not ignored.

	+
	A code indicating a special reason why the delta was or was not
	applied:

	   space
	       Included or excluded normally.

	   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 username of person who created the delta.

	Comments and MR data follow on subsequent lines, indented one hor-
	izontal tab character.	A blank line ends each entry.

	For example, for a delta cut off with the -c flag, the entry in the
	l-file might be:
	     **C 1.3 90/03/13 12:44:16 pat


	and the entry for the initial delta might be:
	     1.1 90/02/27 15:42:20 pat
	     date and time created 90/02/27 15:42:20 by pat


  p-file
      The get command creates the p-file when the -e or the -k flag is speci-
      fied.  The p-file passes information resulting from a get -e to a delta
      command.	The p-file also prevents a subsequent execution of get with
      an -e flag for the same SID until delta is run or the joint edit
      keyletter (j) is set in the SCCS file.  The j keyletter allows several
      gets on the same SID.  The p-file is created in the directory contain-
      ing 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 effec-
      tive user.  The p-file contains:

	+
	The current SID.

	+
	The SID of new delta to be created.

	+
	The username.

	+
	The date and time of the get.

	+
	The -i flag, if it was present.

	+
	The -x flag, if it was 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.  It con-
      tains the binary process number of the get command that created it.  It
      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 accessed and before
  the number of lines created.	If you specify more than one file, or a
  directory, or standard input, get displays the filename before each file is
  processed.  If you specify the -i flag, get lists included deltas below the
  word Included.  If you specify the -x flag, get lists excluded deltas below
  the word Excluded.

  Getting Read-Only File Versions

  The get command creates read-only versions as well as editable versions of
  a file.  Use read-only versions of files any time the application does not
  require that the file contents be changed.  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 version and a read-only version is
  important when using identification keywords.	 Identification keywords are
  symbols that are 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).

  Identification Keywords

  You can use identification keywords in your files to insert identifying
  information.	These keywords are replaced by their values in the g-file
  when get is invoked without the -e or -k flag.  The following identifica-
  tion keywords can be used in SCCS files:

  Identifying Values:

  %M% Module name: the value of the m flag in the SCCS file with the leading
      s. removed

  %I% The SID (%R%.%L%.%B%.%S%) of the g-file

  %R% Release

  %L% Level

  %B% Branch

  %S% Sequence

  %D% Date of the current get (yy/mm/dd)

  %H% Date of the current get (mm/dd/yy)

  %T% Time of the current get (hh:mm:ss)

  %E% Date newest applied delta was created (yy/mm/dd)

  %G% Date newest applied delta was created (mm/dd/yy)

  %U% Time newest applied delta was created (hh:mm:ss)

  Names:

  %F% SCCS filename

  %P% Full pathname of the SCCS file

  Flag Value:

  %Q% The value of the q flag in the file

  %Y% Module type: the value of the t flag in the SCCS file

  Line Number:

  %C% The current line number.	This keyword is for identifying messages out-
      put by the program.  It is not intended for use on every line to pro-
      vide sequence numbers.

  Constructing what Strings:

  %W% A shorthand notation for constructing what strings of the following
      type. Its value is the characters and keyletters:
	   %W% =  %Z%%M%%I%


  %Z% The 4-character string @(#) recognized by the what command.

  The following table illustrates how get determines the SID of the file it
  retrieves, and what the pending SID is.  The column SID Specified shows the
  various ways the SID can be specified with the -r flag.  The next two
  columns illustrate the various conditions that can exist, including whether
  or not the -b flag is used with the get -e.  The SID Retrieved column indi-
  cates 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
  delta is applied.

  SID Determination Table

  _______________________________________________________________________

  SID		     -b	    Other	       SID	   SID of Delta
  Specified	     Used   Conditions	       Retrieved   to be Created

  _______________________________________________________________________

  None (1)	     No	    R defaults	       mR.mL	   mR.(mL+1)
			    to mR(2)
  None (1)	     Yes    R defaults to mR   mR.mL	   mR.mL.(mB+1).1
  (R)elease	     No	    R > mR	       mR.mL	   R.1 (3)
  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		     N/A    R < mR and	       hR.mL (4)   hR.mL.(mB+1).1
			    R does not exist
  R		     N/A    R < mR and	       R.mL	   R.mL.(mB+1).1
			    R exists
  R.(L)evel	     No	    No trunk	       R.L	   R.(L+1)
			    successor
  R.L		     yes    No trunk	       R.L	   R.L(mB+1).1
			    successor
  R.L		     N/A    Trunk	       R.L	   R.L.(mB+1).1
			    successor in
			    release _ R
  R.L.(B)ranch	     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)equence   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	     N/A    Branch	       R.L.B.S	   R.L.(mB+1).1
			    successor

  _______________________________________________________________________

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

  (2) The mR indicates the maximum existing release.

  (3) Forces creation of the first delta in a new release.

  (4) The hR is the highest existing release that is lower than the speci-
  fied, nonexistent, release R.

EXAMPLES

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

   1.  To insert the current date and SID in a file, enter the following sym-
       bols in the file:
	    %H% %I%


       %H% is the symbol for the current date and %I% is the symbol for the
       SID.  When get retrieves a file as editable, it leaves the symbols in
       the file and does not do text value substitution.

   2.  The following example builds the version with the highest SID, because
       no version of the file is specified:
	    $ ls
	    s.test.c
	    $ get s.test.c
	    3.5
	    59 lines
	    $ ls
	    s.test.c test.c


   3.  In the next two command lines, 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


   4.  If you specify only the release number of the SID, get finds the file
       with the highest level within that release number:
	    $ get -r2 s.test.c
	    2.7
	    21 lines


   5.  If the SID specified is greater than the highest existing SID, get
       retrieves the highest existing SID without complaint.  If the SID
       specified is lower than the lowest existing SID, SCCS writes an error
       message and fetches nothing.  In the following example, release 2 is
       the lowest existing release:
	    $ get -r1 s.test.c
	    ERROR [s.test.c]
	    The SID specified does not exist.
	    Use the sact command to check the P-file
	    for existing SID numbers. (cm20)

   6.  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 loca-
       tion.  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


       All of the previous examples use the get command to get a read-only
       file.  To create a copy of the file that can be edited to create a new
       delta, use the -e flag.	The get command works differently when using
       the -e flag (see also the admin command).  Use unget to undo the
       effect of the get -e command and discard any changes made to the file
       before a delta is created.

   7.  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 test.c 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.

   8.  In the previous example, you could have used the -r flag to get a
       specific version.  Assuming delta 1.3 already exists and is the
       highest delta in release, the following three uses of the get command
       produce the same results:
	    $ get -e s.test.c
	    $ get -e -r1 s.test.c
	    $ get -e -r1.3 s.test.c


   9.  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 get indicates the version of the new delta that will be
       created if the delta command stores changes to the SCCS file.

       If the example did not include the -e flag, get would build the
       highest existing SID (1.3) and would not indicate a new delta, even
       though the -r2 flag requests a version 2.1.

   10. 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


       Create deltas on branches using the same methods.

       Several different editable versions of an SCCS file can exist as long
       as each one is in a different directory.	 If you try to get the same
       editable file version more than once into the same directory without
       using the delta command, SCCS writes an error message.

       To get the same editable file version more than once, set the j option
       in the SCCS file with the admin command.	 Set the j option 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.

   11. In the following example, the pwd command displays the current direc-
       tory.  Then the j option is set with the admin command:
	    $ pwd
	    /u/dan/sccs
	    $ admin -fj s.test.c


   12. Then use the get command to retrieve the latest version of the file:
	    $ get -e s.test.c
	    1.1
	    new delta 1.2
	    5 lines


   13. Change to directory /u/new and issue the get command again:
	    $ cd /u/new
	    $ get -e /u/dan/sccs/s.test.c
	    1.1
	    WARNING: 1.1 1.2 dan 90/08/21 09:03:45 is being edited.
	    This if an informational message only. (ge18)
	    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.  The p.test.c file 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.	(Note that you must have
       write permission in both directories to issue the preceding commands.)



RELATED INFORMATION

  Commands:  admin(1), cdc(1), comb(1), delta(1), prs(1), rmdel(1), sact(1),
  sccsdiff(1), sccshelp(1), unget(1), val(1), what(1).


  Files: sccsfile(4).