<change statement>
── CHANGE ─┬─<change list>────────────────────────────────┬────────────►
│ ┌◄───────── , ────────┐ │
└─┴─<change from group>─┴─┬────────────────────│
└─ , ──<change list>─┘
►─┬────────────────────────────────────────────────────────────────────────────┬─┤
└─ [ ──<b1>─┬──────────────────────────────────────────────────────────┬─ ] ─┘
└─ , ──<i>─┬───────────────────────────────────────────────┤
└─ , ──<b2>─┬───────────────────────────────────┤
└─ , ──<b3>─┬───────────────────────┤
└─ , ──<b4>─┬───────────┤
└─ , ──<b5>─┘<change list>
┌◄───────────────────────────── , ────────────────────────────┐
──┴─┬─ <long file title> ── TO ── <long file name> ───────────┬─┴──────┤
└─ <long directory title> ── TO ── <long directory name> ─┘<change from group>
┌◄──────────────────────────── , ────────────────────────────┐
──┴─┬─ <long file name> ── TO ── <long file name> ───────────┬─┴───────►
└─ <long directory name> ── TO ── <long directory name> ─┘
►─ FROM ── <family name> ──────────────────────────────────────────────┤Explanation
The CHANGE statement changes the names of files on disk.
Conflicting File Name
If you specify a file name and a file already exists with that file name, the existing file with the same name is removed before the file name specified is changed to the new file name.
Conflicting Directory Change Requests
Because directory change requests are processed in groups of files, two simultaneous change requests that affect the same set of files produce unpredictable results. For example, simultaneous CHANGE A/= TO B/= and CHANGE B/= TO A/= statements, where both directories A/= and B/= exist with nonconflicting file names, can result in all files in directory A/=, all files in directory B/=, or with the files shared between the two directories.
Directory Changes
If you specify a directory, the names of the files in that directory are changed. If the new directory name already exists, the files are added to that directory, and any files that already belonged to the new directory are not changed. The directories *= and = cannot be used in the CHANGE statement.
LOCKEDFILE Attribute
If you use the CHANGE statement to change the name of a file whose LOCKEDFILE file attribute is set to TRUE, the file name is not changed. The system displays the following message to indicate that the file name was not changed:
<file name> NOT CHANGED (LOCKEDFILE).
See ALTER Statement in this section for more information about changing the LOCKEDFILE file attribute. For additional information about the LOCKEDFILE file attribute, refer to the File Attributes Programming Reference Manual.
Change From Group
When you use a “change from” group, the FROM clause applies to all of the file names and directory names in that “change from” group.
Active Family Specification
Family substitution is used if the job or task has an active family specification. Only the primary family name is used. For more information on active family specification, refer to FAMILY Assignment and Interrogating Complex Task Attributes.
DATAPATH Attribute Specification
Path substitution is used if the job has an active DATAPATH attribute specification. Only the first path element is used. For more information on active DATAPATH attribute specification, refer to DATAPATH Assignment and Interrogating Complex Task Attributes.
Change Privileges
You can use the CHANGE statement to change the name of a file or directory if any one of the following conditions is true:
-
You are a privileged user.
-
You are the owner of the file or directory.
-
You have write access to the file or directory.
Change Results
The CHANGE statement can be followed by an optional results structure: [b1, i, b2, b3, b4, b5]. Parameters are optional. For example, [b1, i] is syntactically correct. However, if a parameter is specified, all preceding parameters must also be specified. The parameters return the following information:
|
Variable |
Type |
Description |
|---|---|---|
|
b1 |
Boolean |
TRUE if a failure occurred. FALSE if all files and directories were changed. |
|
i |
Integer |
Total number of changed files |
|
b2 |
Boolean |
TRUE if at least one file or directory was not changed because it was not present. |
|
b3 |
Boolean |
TRUE if at least one file was not changed because the file was a locked file. |
|
b4 |
Boolean |
TRUE if at least one file was not changed because of a security error. |
|
b5 |
Boolean |
TRUE if at least one file was not changed because the destination file already existed. |
If you run a job that uses this syntax on a 12.0 or earlier MCP system, it is aborted.
Examples
This CHANGE statement changes the name of file X on DISK to Y:
CHANGE X TO Y;
This statement changes the name of file A/B on USERS to C/D:
CHANGE A/B ON USERS TO C/D;
This statement changes the names of all the files under the directory A/= on PACK to B/= on PACK:
S1:="A/="; S2:="B/="; CHANGE #S1 ON PACK TO #S2;
This statement changes the name of file X on MYPACK to Y, changes the name of file X/X on MYPACK to Y/Y, changes the name of file XX on PACK to YY, and changes the name of file Z on DISK to ZZ:
CHANGE X TO Y, X/X TO Y/Y FROM MYPACK,
XX TO YY FROM PACK,
Z TO ZZ;This job demonstrates the use of the optional results:
BEGIN JOB DEMONSTRATE/CHANGE;
BOOLEAN BFAILED, BMISSING, BLOCKED, BSEC, BDUP;
INTEGER COUNT;
CHANGE CHANGETEST1/= TO CHANGETEST3/=,
CHANGETEST5/= TO CHANGETEST2/=,
CHANGETEST6 TO CHANGETEST7
[BFAILED, COUNT, BMISSING, BLOCKED, BSEC, BDUP];
DISPLAY "Change test: " & STRING (COUNT, *) & " files changed";
IF NOT BFAILED THEN
DISPLAY "All files changed";
IF BMISSING THEN
DISPLAY "Missing files";
IF BLOCKED THEN
DISPLAY "Locked files seen";
IF BSEC THEN
DISPLAY "Security error seen";
IF BDUP THEN
DISPLAY "Duplicate files seen";
END JOB