4.2.11 Record summation option (-summary)

To use the record summation option, specify the summation field.
When the values of the specified key fields are equal, add the summation fields to make 1 record. In the case of text files, only the numbers described in ASCII code and Unicode are to be processed. The record summation option (field operand) has an exclusive relationship with the suppress operand.

Format

field=summary-definition

Format of summary-definition
```
pos.len typ [ opt ]
```

pos

This specifies the position of the summation field.
To specify the binary files and text file fixed fields, specify the byte position where the head of the record was assumed to be 0. For the specification of the text file floating field, text file CSV format, and text file TSV format, specify the field number counted from 0.

len

This specifies the length of the summation field in the number of bytes.
For fields that are longer than the specified field, process the text file floating field, the text file CSV format, and the text file TSV format with the specified field length. When a field that is shorter than the specified field length appears, it enhances to the specified field length.

Note

In the text file CSV format and text file TSV format specification, the length of the summation field does not contain the double quotation marks (") that enclose the field.

Example: Summation field and length in text file CSV format.

Summation field    Characters effective as    Length of summation field
                   summation field
123                123                        3bytes
"123"              123                        3bytes

typ

This specifies the data format of the summation field.
For more information, refer to the Data formats that can be specified in the summation field.

opt

This specifies the output format options of the summation field for a text file.
If these are specified for a binary file, an error occurs. The output format options that can be specified are shown below.

opt	Meaning
i	Appends a sign to the value in the summation field. This option and the u option are mutually exclusive.
u	Appends a minus sign (-) to the value in the summation field if that value is negative. This option and the i option are mutually exclusive.
z	If the length of the value in the summation field is less than the field length, the area to the left of the value is padded with zeroes (0). For example, if the value in the summation field is "1234", and the summation field length is six bytes, the value is recorded as "001234". This option, the b, and d options are mutually exclusive.
b	If the length of the value in the summation field is less than the field length, the area to the left of the value is padded with spaces. For example, if the value in the summation field is "1234", and the summation field length is six bytes, the value is recorded as " 1234". This option, the z, and d options are mutually exclusive.
d	Deletes any spaces, tabs, or zeroes that appear at the head of the summation field. If there are any spaces, tabs, or zeroes at the head of the summation field, the field is evaluated from the left and any spaces, tabs, or zeroes that appear before the first number (other than zero) are deleted. For example, if the value in the summation field is "00123", it is changed to "123". Note that, if the value in the summation field is equivalent to zero (such as "0", "0000" or "+000"), the last "0" is not deleted. This option can be specified for the text file floating field, text file CSV format, and text file TSV format. This option, the z, and b options are mutually exclusive.

Note

opt d can be specified for the text file floating field, text file CSV format, and text file TSV format. If it is specified for a text file fixed field, an error occurs.
When summating with opt i specified, if the summated value becomes zero, a plus sign (+) is appended.
When opt b is specified and a plus or minus sign exists, the sign is positioned immediately before the number.
When neither opt i nor u is specified, processing is as follows:
- If the summation result is a negative value, a minus sign (-) is included in the summation result.
- If the summation result of unsigned data and signed data is a positive value, no sign is included in the summation result.
- If two unsigned data items are summated, no sign is included in the summation result.
- If signed and unsigned data are summated and the result is zero, no sign is included.
- If two signed data items are summated, a sign is included in the summation result. If the summation result is zero, a plus sign (+) is included.
When a sign is to be included in the value in the summation field, if the value in the summation field is already as long as the specified summation field length, the sign cannot be included and this causes an overflow to occur.
When neither z, b nor d are specified, processing is as follows:
- When the summation field is summated under the conditions listed below, if the length of the result in the summation field is less than the field length, the area to the left of the value is padded with zeroes (0).
  - When both summated data items are padded to the left with zeroes
  - When one summated data item is padded to the left with zeroes and the other is padded to the left with spaces
  - When one summated data item is padded to the left with zeroes and the other is padded to the left with tabs
- When the summation field is summated under the conditions listed below, if the length of the result in the summation field is less than the field length, the area to the left of the value is padded with spaces.
  - When both summated data items are padded to the left with spaces
  - When both summated data items are padded to the left with tabs
  - When one summated data item is padded to the left with spaces and the other is padded to the left with tabs
Summation fields of records that are not targeted for summation (that is, records with identical key field values for which no other record exists) are processed as follows:
- If opt is specified, results are output in the format specified by opt.
- If opt is not specified, results are output in the input format.

Example

To specify the field of the packed decimal number in 8 bytes from the 7th byte of the input record for the summation field, specify as follows:
```
-summary field=6.8pdl
```
To specify the field of ASCII code in 8 bytes in length from the 4th byte of the input record for the summation field in the text file. Appends a sign to the value in the summation field. If the length of the value in the summation field is less than the field length, the area to the left of the value is padded with spaces.
```
-summary field=3.8ascib
```

Note

Of the records that are objects of the summation process, it is not possible to predict which record is output with the summation results. With the bsortex command, it is possible to specify the record that is output with the summation result using the first operand or last operand.
Specify so that the summation field does not overlap a key field or another summation field.
Note also that the summation field must be completely included in the record.
When using the record summation feature, the key field specification cannot be omitted.

If an overflow occurs during addition of a summation field, subsequent behavior is determined by the specification of the environment variable BSORT_SUMOVERCONT.

Numbers with decimal points cannot be summated.
For text files, only single-byte numbers in ASCII code, Unicode UCS-2 format, Unicode UTF-32 format, or Unicode UTF-8 format are processed.
With a text file floating field specification, if the summation field contains a field separation character and this causes the summation field position to change, correct processing cannot be guaranteed.

With a text file floating field specification, summation results are processed to the specified field length. When a field that is longer than the specified field length appears, the part that exceeds the specified field length is output without changing the content. If the field is shorter than the specified field length, it is extended to the specified field length, and then processed.

Example: Specify "1.5asc" for the summation field. Specify "0.3asca" for the key field. The field separation character string is a comma (,).

Input record                  Output record
001,12345ABC,OPQ (Note1)      001,12456ABC,OPQ (Note2)
001,111,RST                   002,00127,UVW (Note3)
002,15,UVW (Note1)
002,00112DEF,XYZ

NOTE
1. Assume that the record shown here is the one output by the record summation option.
2. Part ("ABC") that exceeds the specified field length is output without changing the content.
3. When the field is shorter than the specified field length, it is extended to the specified field length.

In the text file CSV format and text file TSV format, summation results are processed to the specified field length. When a field is longer than the specified field length, the part that exceeds the specified field length is not output. If the field is shorter than the specified field length, it is extended to the specified field length, and then processed.

Example: Specify "1.5asc" for the summation field of the text file CSV format. Specify "0.3asca" for the key field.

Input record                  Output record
001,12345ABC,OPQ (Note1)      001,12468,OPQ (Note2)
001,123,RST                   002,00027,UVW (Note3)
002,15,UVW (Note1)
002,00012DEF,XYZ

NOTE
1. Assume that the record shown here is the one output by the record summation option.
2. Part ("ABC") that exceeds the specified field length is not output.
3. When the field is shorter than the specified field length, it is extended to the specified field length.

In the text file CSV format and the text file TSV format, whether the summation field is enclosed with double quotation marks (") or it doesn't enclose it is decided depending on the following conditions. When the field on the input record of the target for the output is enclosed with double quotation marks ("), the field after the record is summation is enclosed with double quotation marks ("). When the field on the input record of the target for the output is not enclosed with double quotation marks ("), the field after the record is summation is not enclosed with double quotation marks (").
```
Example: Specify "1.5asc" for the summation field of the text file CSV format. Specify "0.3asca" for the key field.
```
```
Input record                  Output record
001,"12345",OPQ (Note)        001,"12468",OPQ
001,"123",RST                 002,"00027",UVW
002,"15",UVW (Note)           003,11900,GHI
002,00012,XYZ                 004,98769,MNO
003,11111,GHI (Note)
003,"00789",JKL
004,98765,MNO (Note)
004,4,PQR

NOTE
Assume that the record shown here is the one output by the record summation option. 
```
In the text file floating field specification, when a field that is shorter than the specified field length appears, it enhances to the specified field length. As a result, when the record length exceeds the specified maximum record length, it processes as an overflow.

4.2.11 Record summation option (-summary)

4.2.11.1 field operand

4.2.11.2 suppress operand

4.2.11.3 first operand

4.2.11.4 last operand