STD.File.PromoteSuperFileList( supernames [ , addhead ] [ , deltail ] [ , createjustone ] [ , reverse ] )
oldlist := STD.File.fPromoteSuperFileList( supernames [ , addhead ] [ , deltail ] [ , createjustone ] [ , reverse ] );
| supernames | A set of null-terminated strings containing the logical names of the superfiles to act on. Any that don't exist will be created. The contents of each superfile will be moved to the next in the list (NB -- each superfile must contain different sub-files). |
| addhead | Optional. A null-terminated string containing a comma-delimited list of logical file names to add to the first superfile after the promotion process is complete. |
| deltail | Optional. A boolean value specifying whether to physically delete the contents moved out of the last superfile. If omitted, the default is FALSE. |
| createjustone | Optional. A boolean value specifying whether to only create a single superfile (truncate the list at the first non-existent superfile). If omitted, the default is FALSE. |
| reverse | Optional. A boolean value specifying whether to reverse the order of processing the supernames list, effectively "demoting" instead of "promoting" the sub-files. If omitted, the default is FALSE. |
| oldlist | The name of the attribute that receives the returned string containing the list of the previous subfile contents of the emptied superfile. |
| Return: | PromoteSuperFileList returns Null; fPromoteSuperFileList returns a string. |
The PromoteSuperFileList function moves the subfiles from the first entry in the list of supernames to the next in the list, subsequently repeating the process through the list of supernames.
This function does not use superfile transactions, it is an atomic operation.
Example:
STD.File.PromoteSuperFileList(['Super1','Super2','Super3'],
'NewSub1');
//Moves what was in Super1 to Super2,
// what was in Super2 to Super3, replacing what was in Super3,
// and putting NewSub1 in Super1