MERGE

Combine two or more files

MERGE(INPUT=(filename_1, filename_2[, ...])[, RECORD=record[/rec_switch]]
&    [, KEY=(key_field[/key_switch, ...])][, OUTPUT=out_file][, SKIP=(skip_rec[, ...])]
&    [, END=(end_var[, ...])][, OPTIONS=option_string])

Arguments

INPUT=(filename_1, filename_2[, …])

Specifies at least two and up to seven input files to merge. The first file is the primary file. (a)

RECORD=record

(optional) Specifies the record that defines the file record format. If RECORD is not specified, the RECSIZE qualifier must be included in the OPTIONS qualifier string. (a)

rec_switch

(optional) One of the following switches that identifies the record as either fixed-length or variable-length. Each switch must be preceded by its own slash (/). (a)

f = Fixed-length (default)

v = Variable-length

KEY=key_field

(optional) Specifies up to 15 fields, separated by commas, within record to use as a key. If KEY is not specified, the KEY qualifier must be specified in the OPTIONS string. The order in which the keys are specified defines the order of comparison in the MERGE. To use this compile-time KEY argument, you must also specify the compile-time RECORD argument. (a)

key_switch

(optional) One or more of the following key switches that indicates the order of the sorted records. Each switch must be preceded by its own slash (/). (a)

Sort order

f = Forward (ascending) sorted order (default)

r = Reverse (descending) sorted order

Sort type

a = Alpha key (no case distinction)

c = Character key (case-sensitive ordering) (default)

d = Decimal key (numeric ordering)

You can specify a maximum of one sort order switch and one sort type switch (for example, /f/c).

OUTPUT=out_file

(optional) Specifies the name of the output file. If OUTPUT is not specified, the MERGE is assumed to be an in-place reverse merge into the first (primary) input file listed (only two files can be used in this case). If OUTPUT is specified, an n-way merge is performed, where n is the number of input files specified. (a)

SKIP=(skip_rec[, …])

(optional) Specifies the number of records to skip at the beginning of an input file. Each number in the list, in the order specified and separated by commas, corresponds to an input file. If a number is not specified for a particular file, the previous value in the list is carried over. If skip_rec is not specified at all, the MERGE begins with the file’s first record. (n) (Windows, UNIX only)

END=(end_var[, …])

(optional) Specifies a list of alpha or numeric variables or literals, separated by commas, to use as either logical end-of-file characters or maximum record counts for the input file. Each element in the list, in the order specified, corresponds to an input file. If an element is not specified for a particular file, the previous element in the list is carried over. If END is not specified, the files are merged to the physical end of file. (a or n)

OPTIONS=option_string

(optional) Specifies one or more MERGE options to be parsed at runtime. See The OPTIONS string in the Discussion for the syntax of option_string. (a)

Discussion

The MERGE statement combines two or more ordered files to create one ordered output file.

The merged output file always supersedes any existing file. If the output file already exists, any existing contents are lost. All files used by the MERGE are opened and closed internally.

The file structures and record definitions for each input file must be identical, and the files must be sorted in the same order.

If the files are not sorted, no error or warning occurs; the output file MERGEs unsorted. A file containing variable-length records cannot be merged in place.

If the logical end of file is specified but not found, no error or warning occurs; the file is processed until the physical end of file is reached.

Key_field should not reference a pseudo array element (for example, myarr(1)). Use a named overlay of the array element instead.

By default, an in-place MERGE treats the logical end-of-file character or record as the end of usable data. Any records following the logical end of file are overwritten during the in-place MERGE.

If you want to have any records that follow the logical end of file moved to the end of the extended primary file, set system option #18.

By default, an in-place MERGE places duplicate records from the secondary file before their matching records from the primary file. Set system option #23 to place duplicate records from the secondary file after their matching record in the primary file.

The OPTIONS string

Option_string has a maximum of 256 characters and the following format:

[RECSIZE=size[/rec_swch]][, KEY=(key_spec)][, OUTPUT=out_file]
&        [, SKIP=(skip_rec[, ...])][, END=(end_var[, ...])]

RECSIZE=size

(optional) Specifies the size of the records in the file. This qualifier must be specified if the RECORD compile-time qualifier is not specified. For files containing variable-length records, use the maximum record length. (n)

rec_swch

(optional) One of the following switches. Each switch must be preceded by its own slash (/). (a)

f = Size is the size of a fixed-length record. (default)

v = Size is the maximum size of a variable-length record.

e = Size is the exact size of a fixed-length record, including record terminators.

KEY=(key_spec)

(optional) Must be used if the KEY compile-time qualifier is not specified; specifies up to 15 MERGE keys in the format pos:len[/swch, …]: (a)

pos

The position of the key field within the record (n)

len

The length of the given key (n)

swch

(optional) Any one of the switches listed above under key_switch. Each switch must be preceded by its own slash (/). (a)

OUTPUT=out_file

(optional) Specifies an output filename. This qualifier is functionally similar to the OUTPUT compile-time qualifier, except that only literal values are accepted.

SKIP=(skip_rec[, ...])

(optional) Specifies a list of the number of records to skip at the beginning of each input file. This qualifier is functionally similar to the SKIP compile-time qualifier, except that only literal values are accepted. (Windows, UNIX only)

END=(end_var[, ...])

(optional) Specifies a list of alpha or numeric literals to use as either logical end-of-file characters or maximum record counts for the input file. This qualifier is functionally similar to the END compile-time qualifier, except that only literal values are accepted.

The options specified by the OPTIONS qualifier override their corresponding MERGE qualifiers. OPTIONS enables you to build MERGE commands during program execution. This causes some minor extra runtime overhead, so we recommend that you use the corresponding compile-time qualifiers wherever possible.

The /e switch is allowed within the OPTIONS string, but not within the RECORD option. Also, if both record options are used in the MERGE statement, the runtime specification is used. The
/e switch is designed for files with nonstandard record terminators; however, it may restrict portability between some operating systems if record terminators vary in length. The /f or /v switch should be used with standard files.

You must specify at least one key, whether it be in the KEY compile-time qualifier or within the OPTIONS string.