STD.File.AddSuperFile( superfile, subfile [ , atpos ] [ , addcontents ] [ ,strict ])
| superfile | A null-terminated string containing the logical name of the superfile. |
| subfile | A null-terminated string containing the logical name of the sub-file. This may be another superfile. |
| atpos | An integer specifying the position of the subfile in the superfile. If omitted, the default is zero (0), which places the subfile at the end of the superfile. |
| addcontents | A boolean flag that, if set to TRUE, specifies the subfile is also a superfile and the contents of that superfile are added to the superfile rather than its reference. If omitted, the default is to add by reference (addcontents := FALSE). |
| strict | A boolean flag specifying, in the case of a subfile that is itself a superfile, whether to check for the existence of the superfile and raise an error if it does not. Also, if addcontents is set to TRUE, it will ensure the subfile that is itself a superfile is not empty. If omitted, the default is false. |
| Return: | Null. |
The AddSuperFile function adds the subfile to the list of files comprising the superfile. All subfiles in the superfile must have exactly the same structure type and format.
This function may be included in a superfile transaction, but is not required to be.
Example:
IMPORT STD;
SEQUENTIAL(
STD.File.StartSuperFileTransaction(),
STD.File.AddSuperFile('MySuperFile1','MySubFile1'),
STD.File.AddSuperFile('MySuperFile1','MySubFile2'),
STD.File.AddSuperFile('MySuperFile2','MySuperFile1'),
STD.File.AddSuperFile('MySuperFile3','MySuperFile1',addcontents := true),
STD.File.FinishSuperFileTransaction()
);
// MySuperFile1 contains { MySubFile1, MySubFile2 }
// MySuperFile2 contains { MySuperFile1 }
// MySuperFile3 contains { MySubFile1, MySubFile2 }