CHANGELFILE

The CHANGELFILE entry point changes the names of files without opening them. It corresponds with the ALGOL CHANGEFILE statement, but it does not truncate file names at 17 characters. This allows CHANGELFILE to be used on files that contain long file name nodes.

ALGOL Interface

LIBRARY GENERALSUPPORT(LIBACCESS=BYFUNCTION);
BOOLEAN PROCEDURE CHANGELFILE(OLDTITLE, NEWTITLE);
  VALUE OLDTITLE, NEWTITLE;
  POINTER OLDTITLE, NEWTITLE;
  LIBRARY GENERALSUPPORT;

Syntax

── CHANGELFILE ── ( ──<directory element>─ , ─ <directory element>─── ) ──┤

<directory element>

──┬─<pointer expression>─┬────────────────────────────────────────────────┤
  └─<array row>──────────┘

Explanation

The CHANGELFILE function returns a value of TRUE if an error occurs. Error numbers, stored in field [39:20] of the result, correspond to the causes of failure as follows.

Value

Meaning

10

The first directory element is in error.

20

The second directory element is in error.

30

File names have not been changed.

File names and directory names must be specified in EBCDIC and must be followed by a period. All errors in names are detected at run time.

If a family substitution specification is in effect, the CHANGELFILE function affects only the substitute family, not the alternate family.

If a directory name is specified as the source, the names of the files in that directory are changed according to the following rules:

  • If the specified target directory is a new directory, then the names of all the files in the source directory are changed.

  • If the specified target directory is not a new directory, then only files that do not have corresponding names in the target directory are changed. For example, the first column in the following table shows file names that exist before the statement CHANGELFILE(POINTER("A."),POINTER("B.")); is executed, and the second column shows the file names resulting from execution of the statement.

Existing Files

Resulting Files

A/B/C

B/B/C

A/B/D

A/B/D

B/B/D

B/B/D

B/C/D

B/C/D
Note: Because file B/B/D already exists, the file named A/B/D is not changed.

  • A directory element of the form <file name>/= affects only files in that directory. It does not affect a file named <file name>.

  • If the source directory element is in the permanent directory namespace, (for example, within the *DIR directory), and is not of the form <file name>/= , and the directory is empty, only the file or directory is changed.

Conflicting CHANGE Requests

Two simultaneous change requests that affect the same set of files can produce unpredictable results because directory change requests are processed in groups of files. For example, two simultaneous CHANGELFILE (POINTER("A."), POINTER("B.")) and CHANGELFILE (POINTER("B."), POINTER("A.")) calls, where both directories A/= and B/= exist with nonconflicting file names, can result in all of the files being held in directory A/=, all of the files being held in directory B/=, or all of the files being split between the two directories.

<directory element>

A directory element is a file name, a directory name, or both a file name and a directory name. A directory name references a group of files. For example, the following files are all in the directory names JAMES. The first six files are in the directory named (JAMES)OBJECT, and the first five files are in the directory named (JAMES)OBJECT/TEST. Note that (JAMES) OBJECT/TEST/PRIMES is both a file name and a directory name. 

(JAMES)OBJECT/TEST/COM
(JAMES)OBJECT/TEST/SORT
(JAMES)OBJECT/TEST/PRIMES
(JAMES)OBJECT/TEST/PRIMES/1
(JAMES)OBJECT/TEST/PRIMES/2
(JAMES)OBJECT/LIBRARY1
(JAMES)MEMO

In the CHANGELFILE function, the second directory element, the target, designates the name to which the first directory element, the source, is to be changed. If the change applies to files on pack and a family substitution specification is not in effect (either by default through the USERDATA file or by specification in either CANDE or WFL), the target must include ON <family name>, and the source must not include a family name. If a family substitution specification is in effect, ON <family name> is not required. If ON <family name>does not appear, the family substitution specification is used to determine the family on which the files reside.

Example

In the following example of a CHANGELFILE, the program changes A/B to C/D and then removes C/D. 

BEGIN
   ARRAY OLD, NEW[0:44];
   BOOLEAN B;
   LIBRARY GENERALSUPPORT(LIBACCESS=BYFUNCTION);
   BOOLEAN PROCEDURE CHANGELFILE(OLDTITLE, NEWTITLE);
    VALUE   OLDTITLE, NEWTITLE;
    POINTER OLDTITLE, NEWTITLE;
    LIBRARY GENERALSUPPORT;
   REPLACE POINTER(OLD) BY 8"A/B.";
   REPLACE POINTER(NEW) BY 8"C/D.";
   IF B := CHANGELFILE(OLD,NEW) THEN
      DISPLAY("CHANGELFILE ERROR");
END.
Prev  Up  Next
GENERALSUPPORT Entry Points  Home  REMOVELFILE