Copies subfiles from backing-store files into a single file.
Options
PRINT = string token |
What to print (catalogue); default * |
|---|---|
OUTCHANNEL = scalar |
Channel number of the backing-store file where the subfiles are to be stored; default 0, i.e. the workfile |
METHOD = string token |
How to append subfiles to the OUT file (add, overwrite, replace); default add, i.e. clashes in subfile identifiers cause a fault (note: replace overwrites the complete file) |
PASSWORD = text |
Password to be checked against that stored with the file; default * |
Parameters
SUBFILE = identifiers |
Identifiers of the subfiles |
|---|---|
INCHANNEL = scalars |
Channel number of the backing-store file containing each subfile |
NEWSUBFILE = identifiers |
Identifier to be used for each subfile in the new file |
Description
The MERGE directive is used to copy subfiles into another backing-store file. You can either add the subfiles to an existing backing-store file, or form a new backing-store file.
The OUTCHANNEL option specifies the backing-store channel of the file to which the subfiles are to be copied; by default this is the workfile (channel 0).
The SUBFILE parameter specifies the list of subfiles that are to be copied, and the INCHANNEL parameter indicates the channel of the backing-store file where each one is currently stored. If you do not specify the INCHANNEL parameter, Genstat assumes that the subfiles are coming from the workfile. You are not allowed to include the OUTCHANNEL among the channels in the INCHANNEL list. Also, you cannot store two subfiles with the same names, and should use the NEWSUBFILE parameter to rename any that clash. For example
MERGE [OUTCHANNEL=3] JanData,JulyData,JanData;\
INCHANNEL=1,1,2; NEWSUBFILE=Jan92dat,Jul92dat,Jan93dat
To rename only some of the subfiles, you can either respecify the existing identifier, or insert * at the appropriate point in the NEWSUBFILE list.
If you specify a missing identifier * in the SUBFILE list, Genstat will include all the subfiles from the relevant INCHANNEL. If you want to rename any of these subfiles, you can also mention it explicitly. For example, this statement will take all the subfiles from channel 1 and rename subfile Sub as Subf.
MERGE *,Sub; INCHANNEL=1; NEWSUBFILE=*,Subf
You can set option PRINT=catalogue to produce a catalogue of the subfiles in the new backing-store file.
If a subfile of the specified name already exists on the backing-store file, the storing operation will usually fail. However, you can set option METHOD=overwrite to overwrite the old subfile, that is, to replace the old subfile with a new subfile. Alternatively, you can put METHOD=replace to form a new backing-store file containing only the new subfiles.
Subfiles are merged in a fixed order. Genstat first takes the subfiles from the backing-store file with the lowest channel number, in the order in which they occur there, then it takes the subfiles the next lowest channel number, and so on. If OUTCHANNEL=0 (that is, the new file is the workfile), the original subfiles that are to be retained from that file will be followed by the new subfiles; otherwise, if OUTCHANNEL is non-zero, the original subfiles are placed after the new subfiles. If you want to put the subfiles into a particular order, you should merge them into the workfile in that order, and then merge the workfile into a new userfile.
To keep the new file secure, you can use the PASSWORD option to incorporate a password. Once you have done this, you must include the same password in any future use of MERGE or STORE with this same userfile; spaces, case, and newlines are significant in the password. You cannot change the password in a userfile once you have set it, but you can use the MERGE directive to create a new userfile with no password or with a new password. If you set the password to be a text whose values have been have restricted, the restriction is ignored.
Options: PRINT, OUTCHANNEL, METHOD, PASSWORD.
Parameters: SUBFILE, INCHANNEL, NEWSUBFILE.
See also
Directives: STORE, RETRIEVE, CATALOGUE, OPEN.
Commands for: Input and output.
Example
" Example MERG-1: Merge data from separate backing-store files Store the plan and data (sugar %) from a sugar experiment at Kings Lynn in a subfile called KLYNN" VARIATE PLOT; VALUES=!(1...30); DECIMALS=0 UNIT PLOT FACTOR [LEVELS=!(0,1,2,3,4)] K2O FACTOR [LEVELS=!(0,1)] NACL OPEN '%gendir%/examples/MERG-1.DAT'; CHANNEL=2; FILETYPE=input READ [CHANNEL=2] K2O,NACL READ [CHANNEL=2] S% " Open three new backing-store files." OPEN 'MERG-1.BAC','MERG-1.BC1','MERG-1.BC2';\ CHANNEL=1,2,3; FILETYPE=backingstore " Store the plan and data from the Kings Lynn site in subfile KLYNN in the file MERG-1.BC1." STORE [CHANNEL=2; PRINT=catalogue; SUBFILE=KLYNN] K2O,NACL,S% " Delete all structure read in" DELETE [REDEFINE=yes] K2O,NACL,S% " Repeat for the IPSWICH site" FACTOR [LEVELS=!(0,1,2,3,4)] K2O FACTOR [LEVELS=!(0,1)] NACL READ [CHANNEL=2] K2O,NACL READ [CHANNEL=2] S% " Store the plan and data from Ipswich site in subfile IPSWICH in the file MERG-1.BC2" STORE [CHANNEL=3; PRINT=catalogue; SUBFILE=IPSWICH] K2O,NACL,S% " Merge the files MERG-1.BC1 and MERG-1.BC2 into MERG-1.BAC" MERGE [OUTCHANNEL=1] SUBFILE=KLYNN,IPSWICH; INCHANNEL=2,3 " List the subfiles and structures in file MERG-1.BAC" CATALOGUE [CHANNEL=1; LIST=ALL] " Close the files, and delete the backing-store files." CLOSE CHANNEL=1,2,3; FILETYPE=backingstore; DELETE=yes CLOSE CHANNEL=2; FILETYPE=input