


PUTBACK(1)                User Commands                PUTBACK(1)



NAME
     putback - copy files from a child workspace  to  its  parent
     workspace

SYNOPSIS
     putback [ -b ] [ -B ] [ -c comment ] [[ -f flp ] ... ]
         [ -g ] [ -n ] [ -p pws ] [ -q ] [ -v ] [ -w cws ]
         [files or dirs ...]

DESCRIPTION
     putback is the TeamWare command used to copy groups of files
     from  a child workspace to a parent workspace.  All TeamWare
     file transfer transactions are performed from  the  perspec-
     tive of the child workspace; hence the putback command "puts
     back" files to the parent from the child workspace. A  child
     workspace  is  typically created using the bringover(1) com-
     mand.

     The putback command attempts to make the  parent  and  child
     workspaces identical with respect to the set of files speci-
     fied for the putback transaction.  The  putback  transaction
     is  used after users make changes and test them in the child
     workspace.  Putting the files back into the  parent  usually
     makes them accessible to other developers.

     For example:

        example% putback -w ~/ws/mychild dir1 dir2

     finds all changed files under directories dir1 and dir2  and
     copies them to ~/ws/mychild's parent workspace.

     During a putback transaction putback may find that it cannot
     transfer  files  from  the  child  to  the  parent workspace
     without endangering the  consistency  of  the  data  in  the
     parent.  If  this  occurs,  no files are transferred and the
     putback transaction is said to be blocked.  Reasons  that  a
     putback transaction is blocked include:

     o   A file in either workspace is currently checked out from
        SCCS

     o   A file in the parent workspace contains changes not  yet
        brought over into the child workspace

      o   A  file  conflict  in  either  workspace  is  currently
        unresolved

     If any of  the  files  designated  for  transfer  cannot  be
     copied, none of the files are copied.





SunOS 5.5         Last change: 01 December 1992                 1






PUTBACK(1)                User Commands                PUTBACK(1)



     If the putback transaction is blocked, the  putback  command
     displays  the bringover command-line necessary to update the
     child workspace.  If the -b  option  is  specified,  putback
     automatically invokes the appropriate bringover transaction.

     The following table summarizes putback actions:

     File in Parent   File in Child     Action by TeamWare

     Exists           Does not exist    Block putback, notify user
     Does not exist   Exists            Create the file in the parent
     Unchanged        Unchanged         None
     Unchanged        Changed           Update file in the parent.
     Changed          Unchanged         Block putback, notify user
     Changed          Changed           Block putback, notify user
     Checked out*     Checked out*      Block putback, notify user
     Unresolved       Unresolved
     conflict*        conflict*         Block putback, notify user

     *Checked out or unresolved in  either  or  both  parent  and
     child


OPTIONS
     -B                   Do  not  backup  files  in  the  parent
                         workspace  before  changing them.  While
                         reducing the disk space occupied by  the
                         parent   workspace  and  improving  file
                         transfer  performance,  it  removes  the
                         option  of  later "undoing" the  putback
                         with the ws_undo command.

     -b                   If putback  blocks,  then  execute  the
                         bringover command to update cws.

     -c comment           Provide a comment describing  the  put-
                         back.    comment  is  written  to  pws's
                         Codemgr_wsdata/history file.   The  his-
                         tory file contains information regarding
                         file transfer transactions.  If the  - c
                         option is not specified, putback prompts
                         for a comment.

     -f flp               Execute the file list program, flp,  to
                         determine  the list of files to process.
                         flp writes a white-space separated  list
                         of  filenames  to  stdout  that  putback
                         processes as if there were specified  on
                         the  command-line.   More  than  one  -f
                         option may  be  specified.   If  an  flp
                         exits  with  a  non-zero status, putback
                         displays a message and exits.



SunOS 5.5         Last change: 01 December 1992                 2






PUTBACK(1)                User Commands                PUTBACK(1)



     -g                   Don't do SCCS gets  after  transferring
                         files.   Normally  g-files are extracted
                         after  they  are  brought  over.    This
                         option  improves  file  transfer perfor-
                         mance although it shifts  the  responsi-
                         bility to the user to do the appropriate
                         gets at a later time.

     -n                   Show what would be done  without  actu-
                         ally doing anything.

     -p pws               Names the parent workspace to  be  used
                         for that specific invocation of the put-
                         back  command.   pws   as   the   parent
                         workspace  for  the duration of the com-
                         mand.

     -q                   Quiet option.  By default, a message is
                         displayed  for each created, updated, or
                         conflicting  file.   The   -  q   option
                         suppresses these messages.  If both the
                         -q option and the -v option  are  speci-
                         fied, the last one takes precedence.

     -v                   Verbose option.  By default, a  message
                         is  displayed for each created, updated,
                         or conflicting file.   The   - v  option
                         causes  putback  to  print a message for
                         all files, including  those  that  don't
                         need  to  be  put  back.  If both the -v
                         option and the -q option are  specified,
                         the last one takes precedence.

     -w cws               Names the child workspace. If the   - w
                         option  is not specified, then the value
                         of  the   shell   environment   variable
                         CODEMGR_WS  is  used.   If CODEMGR_WS is
                         not set and  the  current  directory  is
                         contained  within  a workspace, the con-
                         taining workspace is used.

                         The parent workspace is taken from cws's
                         Codemgr_wsdata/parent    file   or   the
                         command-line as  specified  by  the  - p
                         option.

     Some notes about the file and dir arguments:

     o   The "." directory may be used to specify that the entire
        workspace be copied.

     o   To  save  users  the  trouble  of  specifying  file  and



SunOS 5.5         Last change: 01 December 1992                 3






PUTBACK(1)                User Commands                PUTBACK(1)



        directory  arguments every time the bringover and putback
        commands are  used,  the  arguments  are  cached  in  the
        cws/Codemgr_wsdata/args  file.  If  file or dir arguments
        are not specified to subsequent invocations  of  putback,
        the  arguments  are  taken  from the args file as if they
        were specified on the command-line.

        The args file is maintained by the bringover and  putback
        commands; they update the file whenever new arguments are
        specified that cause additional files to be copied.

        Note  that  if  no  arguments  are  specified,  and   the
        Codemgr_wsdata/args  file  does  not  exist, putback will
        report an error.

        Users can edit the args file at any time  to  change  its
        contents.

     o   Any valid file name that  does  not  contain  whitespace
        characters  or  a  pound  sign (#) may be specified as an
        argument to putback.  A relative file name  specified  on
        the command-line, as output of a file list program (FLP),
        or as an argument to the - f  option  is  interpreted  as
        being  relative  to the top-level (root) directory of the
        parent and child workspaces.  If an  absolute  file  name
        does  not refer to a file under one of the workspaces, it
        will  also  be  interpreted  as  being  relative  to  the
        workspace root directory.

     o   When a directory is specified as  the  argument  to  the
        command,  putback  changes  to that directory and invokes
        the default FLP: def.dir.flp.  The FLP writes a  list  of
        file  names  to  stdout that putback processes as if they
        were specified as command-line  arguments.   The  default
        version  of  def.dir.flp  as shipped with TeamWare recur-
        sively lists all files under  SCCS  control  beneath  the
        specified  directory. Note that other FLPs including ones
        written by users, may be specified via the   - f  option.
        Refer  to  the  TeamWare  User's  Guide  for more details
        regarding FLPs.

     TeamWare uses a multi-reader/single-writer locking mechanism
     and  putback  obtains a read-lock in cws and a write-lock in
     pws.  If these locks cannot be obtained, putback displays  a
     message and exits.

     TeamWare  checks  the  access_control  file  in  the  parent
     workspace  to  determine  if the user running the command is
     allowed  to  do  a  putback   into   the   workspace.    The
     access_control  file  in the child workspace is also checked
     to see if the user is allowed to  do  a  putback  from  that
     workspace.



SunOS 5.5         Last change: 01 December 1992                 4






PUTBACK(1)                User Commands                PUTBACK(1)



     putback displays status messages to stdout indicating  if  a
     file  is  new  or updated.  A copy of these messages is also
     written to pws's Codemgr_wsdata/history file.

     putback executes other TeamWare commands, such as sccsmerge,
     and  expects to find them in the user's PATH. Therefore, the
     user's  PATH  variable  must  include  the  directory  where
     TeamWare is installed.

MESSAGES
     putback tries to ensure that pws is stable  and  consistent.
     Therefore,  putback  has some restrictions on the conditions
     under which it puts back files.  If any files cannot be  put
     back, then no files are put back.

     If putback is unable to transfer files it will  display  one
     of the following messages:

     o   The following files have changed in  workspace  pws  and
        must be brought over:

        The listed files contain changes that have not  yet  been
        brought  over  into  cws.   To protect the consistency of
        pws, these changed files must be brought over and  tested
        before the putback can complete.

     o   The following files are new in workspace pws and must be
        brought over:

        The listed files exist in pws but not in cws.  They  must
        be brought over into cws before the putback can complete.

     o   The following files have different  file  types  in  the
        workspaces:

        A file name has a different file type (regular  file  vs.
        directory  vs.   symbolic link) in pws and cws.  The user
        must take whatever action  is  appropriate  to  make  the
        listed files the same type or change one of the names.

      o   The  following  files  are  currently  checked  out  in
        workspace ws:

        The named files are currently checked out in ws and  must
        be checked in before putback can complete.

     o   The following files need to be resolved in workspace ws:

        The named files are currently in conflict in ws and  must
        be resolved(1) before putback can complete.





SunOS 5.5         Last change: 01 December 1992                 5






PUTBACK(1)                User Commands                PUTBACK(1)



     Also, when a putback blocks and comments  have  been  speci-
     fied,    the    comments    are    written   to   the   file
     cws/Codemgr_wsdata/putback.cmt and putback prints  the  mes-
     sage:

     o   Your putback comments have been saved in file
        "cws/Codemgr_wsdata/putback.cmt"

ENVIRONMENT
     The following variables are used by putback.

     CODEMGR_DIR_FLP          Contains the name of the file  list
                              program  (FLP) to use in workspaces
                              if one is not explicitly  specified
                              by  means  of the -f option.  Over-
                              rides  the  TeamWare  default   FLP
                              def.dir.flp(1).

     CODEMGR_PATH_ONLY        TeamWare commands first search  for
                              other TeamWare binaries relative to
                              where their own binary  is  located
                              in   the  file  system,  they  then
                              search in the directories specified
                              in  the  PATH environment variable.
                              Setting   this   variable    causes
                              TeamWare  commands  to  search  for
                              other  TeamWare  binaries  only  in
                              PATH.

     CODEMGR_WS               Contains  the  name  of  a   user's
                              default  workspace.   The workspace
                              specified   by   CODEMGR_WS    will
                              automatically  be used if -w option
                              is not specified to a command.

     CODEMGR_WSPATH Specifies a list of workspace directories  to
     be  automatically  loaded  into the workspace pane upon tool
     startup.

          The CODEMGR_WSPATH variable can be to  set  to  one  or
          more  directories  that  contain workspace directories.
          For example, to set this variable  to  the  directories
          /export/home/ws  and  ~/projects/ws,  use the following
          command:

          example%   setenv    CODEMGR_WSPATH    "/export/home/ws
          ~/projects/ws"

     The following variables are set by putback at execution time
     for use within FLPs.

     CODEMGR_CMD              Contains the name  of  the  putback



SunOS 5.5         Last change: 01 December 1992                 6






PUTBACK(1)                User Commands                PUTBACK(1)



                              command.

     CODEMGR_WS_CHILD         Contains  the  name  of  the  child
                              workspace for this putback.

     CODEMGR_WS_DEST          Contains the name of  the  destina-
                              tion  (to)  workspace for this put-
                              back.

     CODEMGR_WS_PARENT        Contains the  name  of  the  parent
                              workspace for this putback.

     CODEMGR_WS_SRC           Contains the  name  of  the  source
                              (from) workspace for this putback.

     CODEMGR_WS_ROOT          The putback command  executes  FLPs
                              in   both   the  parent  and  child
                              workspaces.  This variable contains
                              the  name of the workspace in which
                              the FLP is currently executing.

FILES
     def.dir.flp              default FLP for directories

     cws/Codemgr_wsdata/parent
                              contains the  name  of  the  parent
                              workspace

     cws/Codemgr_wsdata/locks locks file for cws

     cws/Codemgr_wsdata/args  definition of all of cws

     cws/Codemgr_wsdata/putback.cmt
                              when putback blocks,  the  comments
                              are saved here

     pws/Codemgr_wsdata/history
                              log of the putback

     pws/Codemgr_wsdata/locks locks file for pws

SEE ALSO
     TeamWare User's Guide
     bringover(1),   def.dir.flp(1),   resolve(1),   sccs-get(1),
     twmerge(1),   ws_undo(1),  workspace(1),  access_control(4),
     args(4), children(4),  conflicts(4),  history(4),  locks(4),
     nametable(4), notification(4) parent(4)

EXIT CODES
     0         putback was successful

     1         putback failed due to an error condition



SunOS 5.5         Last change: 01 December 1992                 7






PUTBACK(1)                User Commands                PUTBACK(1)



     2         putback blocked, did not execute bringover

     3         putback blocked, executed successful bringover

     4         putback  blocked,  executed  successful  bringover
               that found files in conflict

















































SunOS 5.5         Last change: 01 December 1992                 8



