1 12/08/88  copy_dir_
  2 
  3 
  4 Copies a subtree from one point in the hierarchy to another, and
  5 optionally deletes the source subtree.
  6 
  7 
  8 Entry points in copy_dir_:
  9    (List is generated by the help command)
 10 
 11 
 12 :Entry:  copy_dir_:  12/08/88  copy_dir_
 13 
 14 
 15 Function:
 16 Copies a subtree from one point in the hierarchy to another, and
 17 optionally deletes the source subtree.
 18 
 19 
 20 Syntax:
 21 dcl copy_dir_ entry(char(*), char(*), char(*), char(*), ptr, fixed
 22      bin(35));
 23 call copy_dir_ (caller, source_dir, source_ename, target_dir,
 24      target_ename, pcopy_dir_options, code);
 25 
 26 
 27 Arguments:
 28 caller
 29    is the name of the calling procedure.  (Input)
 30 source_dir
 31    is the pathname of the source directory.  (Input)
 32 source_ename
 33    is the source entry name.  (Input)
 34 target_dir
 35    is the pathname of the target directory.  (Input)
 36 
 37 
 38 target_ename
 39    is the target entry name.  (Input)
 40 pcopy_dir_options
 41    is a pointer to the copy_dir_options structure shown below under
 42    "Info Structure".  (Input)
 43 code
 44    is a standard system status code.  (Output)
 45 
 46 
 47 Info structure:
 48 The following structure is declared in copy_dir_options.incl.pl1:
 49 
 50    dcl 1 copy_dir_options        aligned based(pcopy_dir_options),
 51          2 version               fixed bin,
 52          2 entry_control         aligned,
 53            3 link                bit(1) unal,
 54            3 seg                 bit(1) unal,
 55            3 dir                 bit(1) unal,
 56            3 msf                 bit(1) unal,
 57            3 nnlk                bit(1) unal,
 58            3 pad1                bit(31) unal,
 59 
 60 
 61          2 operation_control     aligned,
 62            3 delete              bit(1) unal,
 63            3 brief               bit(1) unal,
 64            3 force               bit(1) unal,
 65            3 replace             bit(1) unal,
 66            3 update              bit(1) unal,
 67            3 acl                 bit(1) unal,
 68            3 primary             bit(1) unal,
 69            3 link_translation    bit(1) unal,
 70            3 chase               bit(1) unal,
 71            3 parent_ac_sw        bit(1) unal,
 72            3 pad2                bit(26) unal;
 73 
 74 
 75    dcl copy_dir_options_version_0 fixed bin init(0) int static options
 76         (constant);
 77    dcl pcopy_dir_options         ptr;
 78 
 79 
 80    Structure elements:
 81    version
 82       is the version number of this structure, currently
 83       copy_dir_options_version_0.
 84    link
 85       if set to "1"b then links are copied.
 86    seg
 87       if set to "1"b then segments are copied.
 88    dir
 89       if set to "1"b then inferior directories are copied.  If this is
 90       not set then the subtree is not walked.
 91    msf
 92       if set to "1"b then multisegment-files are copied.
 93    nnlk
 94       if set to "1"b then non-null links are copied.
 95 
 96 
 97    pad1
 98       is unused and must be zero.
 99    delete
100       if set to "1"b then the source_dir is deleted after the copying
101       is complete.
102    brief
103       if set to "1"b suppresses the printing of warning messages such
104       as "Bit count is inconsistent with current length" and "Current
105       length is not the same as records used".
106    force
107       if set to "1"b executes, when target_dir already exists, without
108       asking the user.  If force is not set, the user is queried.
109 
110 
111    replace
112       if set to "1"b deletes the existing contents of target_dir before
113       the copying begins.  If target_dir is non-existent or empty, this
114       control argument has no effect.  The default is to append the
115       contents of source_dir to the existing contents of target_dir.
116       Setting of replace conflicts with the setting of update, and
117       error_table_$inconsistent is returned.
118    update
119       if set to "1"b causes copying of only those entries in source_dir
120       that have comparable entries in target_dir.  Setting of update
121       conflicts with the setting of replace, and
122       error_table_$inconsistent is returned.
123 
124 
125    acl
126       if set to "1"b gives the ACL on the source_dir entry to its copy
127       in target_dir.  Although initial ACLs are still copied, they are
128       not used in setting the ACL of the new entries when not set.
129    primary
130       if set to "1"b only primary names are copied.  If not set, all
131       the names of the selected entries are copied.
132    link_translation
133       if set to "1"b then links will be translated.  If there are
134       references to the source directory in the link pathname of a link
135       being copied, the link pathname is changed to refer to the target
136       directory.
137    chase
138       if set to "1"b copies the target of a link.  Chasing links
139       eliminates link translation.
140 
141 
142    parent_ac_sw
143       if set to "1"b when target directories need creating.  The access
144       class of the target_dir is obtained from the target's parent
145       directory.  Otherwise, the access class is determined from the
146       source_dir.  This switch may be used by privileged applications
147       to make a downgraded copy of an upgraded hierarchy.  The caller
148       must have previously set the seg and dir AIM privileges in order
149       to read the contents to the upgraded hierarchy.
150    pad2
151       is unused and must be zero.
152 
153 
154 Access required:
155 Status permission is required for source_dir and all of the directories
156 in its tree.  Status permission is required for the directory
157 containing source_dir.  Read access is required on all files under
158 source_dir.  Append and modify permission are required for the
159 directory containing target_dir if target_dir does not exist.  Modify
160 and append permission are required on target_dir if it already exists.
161 
162 If acl is not specified, the system default ACLs are added, then the
163 initial ACL for the containing directory is applied (which may change
164 the system supplied ACL).  Initial ACLs are always copied for the
165 current ring of execution.
166 
167 
168 Notes:  If target_dir already exists and force is not specified, the
169 user is so informed and asked if processing should continue.  If
170 target_dir is contained in source_dir, an appropriate error message is
171 printed and the subroutine returns.
172 
173 If name duplication occurs while appending the source_dir to the
174 target_dir and the name duplication is between directories, the user is
175 queried whether processing should continue.  If the user answers yes,
176 the contents of the directory are copied (appended) but none of the
177 attributes of that directory are copied.  If the answer is no, the
178 directory and its subtree is skipped.  If name duplication should occur
179 between segments, the user is asked whether to delete the existing one
180 in target_dir.
181 
182 
183 If replace is specified or target_dir does not exist, name duplication
184 does not occur.
185 
186 If part of the tree is not copied (by specifying a storage system entry
187 key), problems with link translation may occur.  If the link target in
188 the source_dir tree was in the part of the tree not copied, there may
189 be no corresponding entry in the target_dir tree.  Hence, translation
190 of the link causes the link to become null.
191 
192 
193 If copying a non-empty mailbox requires that the max_length
194 characteristic of the source be applied to the target, then the target
195 max_length value will take on the default value that was given it when
196 created.