STD.File.CreateSuperFile( superfile [ , sequentialparts ] [ , allowExist ] )
| superfile | A null-terminated string containing the logical name of the superfile. |
| sequentialparts | Optional. A boolean value indicating whether the sub-files must be sequentially ordered. If omitted, the default is FALSE. |
| allowExist | Optional. A boolean value indicating whether to post an error if the superfile already exists. If TRUE, no error is posted. If omitted, the default is FALSE. |
| Return: | Null. |
The CreateSuperFile function creates an empty superfile. This function is not included in a superfile transaction.
The sequentialparts parameter set to TRUE governs the unusual case where the logical numbering of sub-files must be sequential (for example, where all sub-files are already globally sorted). With sequentialparts FALSE (the default) the subfile parts are interleaved so the parts are found locally.
For example, if on a 4-way cluster there are 3 files (A, B, and C) then the parts are as follows:
A._1_of_4, B._1_of_4, and C_1_of_4 are on node 1
A._2_of_4, B._2_of_4, and C_2_of_4 are on node 2
A._3_of_4, B._3_of_4, and C_3_of_4 are on node 3
A._4_of_4, B._4_of_4, and C_4_of_4 are on node 4
Reading the superfile created with sequentialparts FALSE on Thor will read the parts in the order:
[A1,B1,C1,] [A2,B2,C2,] [A3,B3,C3,] [A4,B4,C4]
so the reads will all be local (i.e., A1,B1,C1 on node 1 etc). Setting sequentialparts to TRUE will read the parts in subfile order, like this:
[A1,A2,A3,] [A4,B1,B2] [,B3,B4,C1,] [C2,C3,C4]
so that the global order of A,B,C,D is maintained. However, the parts cannot all be read locally (e.g., A2 and A3 will be read on part 1). Because of this it is much less efficient to set sequentialparts true, and as it is unusual anyway to have files that are partitioned in order, it becomes a very unusual option to set.
Example:
STD.File.CreateSuperFile('~CLASS::RT::IN::SF1',,1);
//This is the same but uses named parameter
STD.File.CreateSuperFile('~CLASS::RT::IN::SF1',allowExist := 1);