|
The TBSORT service places the rows of an open table in a user-specified
order and stores this specified order in a sort information record.
The sort can be done on more than one field and in either an ascending
or descending order. TBSORT can be issued for an empty table. When
a TBSORT is completed, the CRP is set to zero (top).
The sort can also be done by date without having to change the
date variable to a 4-digit year. The ISPF configuration table field
YEAR_2000_SLIDING_RULE is used to determine a century value to be
appended to the existing 2-digit year values within the ISPF table.
The variable is only modified internally for comparison purposes and
no actual change is made to data stored in the ISPF table.
The sort information record is maintained with the table. This
record contains the order of the "last-sort" and provides for
rows to be added to the table in the proper sequence after a sort
has been completed. This is done through the ORDER keyword on the
TBADD, TBMOD, and TBPUT services. The sort information record is saved
on external storage when a TBSAVE or TBCLOSE operation successfully
completes. It is retrieved during TBOPEN processing.
Notes on Performance: - The performance of TBSORT is not greatly affected by the starting
order of the table. However, a sort by year can affect performance
because an internal conversion to a 4-digit year must be done for
each comparison.
- A numeric sort affects performance because a conversion of two
numbers must be done for each comparison.
Command invocation format
>>-ISPEXEC--TBSORT--table-name--FIELDS(sort-list)--------------><
Parameters
- table-name
- Specifies the name of the table to be sorted.
- sort-list
- Specifies sort fields. The syntax is as follows:
(field-name1, B|C|N|Yn, A|D,field-name2, B|C|N|Yn, A|D, …)
Each
sort field-name must be either a KEY or NAME field. The first (left
most) field-name is the primary key (most significant) and the rows
are then collated based on the values of the field-names.
The
field-name is followed by a sort field type designator. The sort field
type designator can have a value of 'C' for a character sort, a value
of 'N' for a numeric sort, a value of 'B' for a binary sort, or a
value of 'Yn' for a year sort. For English,
where sorting is in EBCDIC sequence, specifying either C or B as the
sort field type designator causes the same sort order. For other languages,
where the character format can be other than EBCDIC, only B is to
be specified for a binary sort.
The 'Y n'
sort is treated as a character sort where the variable being sorted
is a date variable, with n being the offset
of the beginning of a 2-byte year in the variable. To sort a table
into a valid ascending or descending date sequence, the date field
must have a format with the most significant part (the year) at the
start, the least significant part at the end, and a sort field type
designator of Y1. Some examples of valid formats are: YY/MM/DD
YYDDD
YY-MM
Internally, TBSORT expands the year to a 4-byte
year using the ISPF configuration table field YEAR_2000_SLIDING_RULE
to calculate the century value.
The collating sequence for
character sorts during DBCS and English sessions is in EBCDIC order.
This means, for example, that all lowercase letters precede uppercase
letters when sorting in an ascending sequence. For other languages,
a character sort is done such that both uppercase and lowercase, as
well as accented and non-accented versions of a letter, are sorted
in the proper order.
The
sort field type designator is followed by a sort sequence direction
value. The sort sequence direction value can be either 'A' (ascending)
or 'D' (descending). The field type designator and the sort sequence
direction can be omitted for the last named field only. They default
to 'C' (character) and 'A' (ascending), respectively.
In some
languages, the comma is used in place of a decimal point. To accommodate
different usages, three numeric representations are supported: period,
comma, and French representations.
Table 1. Decimal Point RepresentationsConvention |
Example |
Example |
Where Used |
---|
Period |
1,234.56 |
0.789 |
Japan, Mexico, UK, USA |
Comma |
1.234,56 |
0,789 |
Most other countries |
French |
1234,56 |
0,789 |
France, South Africa |
The TBSORT service accommodates these three numeric representations.
The convention used is determined by the language of the session,
specified by the value of ZLANG in the system profile table. The current
English version accepts only the period, treating it as the delimiter
of the whole and decimal portion of a number. Sorting is based on
the specified language convention.
These restrictions apply
to fields for a "numeric" type sort:
- The field must be a decimal number and optionally can contain
a plus (+) or minus (-) sign. The decimal number can be either a whole
number (for example, 234) or a mixed number (for example, 234.56),
composed of a whole number followed by a decimal point. A decimal
point is not required after a whole number, but is required in a mixed
number. (Under the period convention, the decimal point is represented
by a period (.); under the comma or French conventions, the decimal
point is represented by a comma (,).) No other characters are allowed
except leading blanks.
- No numeric string can exceed 16 characters. This length value
includes any plus or minus sign, any blanks, or a decimal point.
- The largest value that can be sorted is plus or minus 2 147 483 647.
- The string can have leading blanks following the sign character.
- buf-len
- Specifies a fullword fixed binary integer containing the length
of "buffer".
- buffer
- Specifies a buffer containing the name of the service and its
parameters in the same form as they would appear in an ISPEXEC call
for a command procedure.
Return codes
These return codes are possible:
- 0
- Normal completion.
- 12
- Table is not open.
- 16
- Numeric convert error.
- 20
- Severe error.
Example 1
Perform a sort on the LASTNAME field for table TELBOOK. Use the
defaults of "A" (ascending) and "C" (character). ISPEXEC TBSORT TELBOOK FIELDS(LASTNAME)
Set
the program variable BUFFER to contain: TBSORT TELBOOK FIELDS(LASTNAME)
Set
program variable BUFLEN to the length of the variable BUFFER. Issue
the command: CALL ISPEXEC (BUFLEN, BUFFER);
CALL ISPLINK ('TBSORT ','TELBOOK ','LASTNAME');
Example 2
Perform a sort on table MODSIZES. Sort on NAME, a character field,
in ascending sequence. Then sort on SIZE, a numeric field, in descending
sequence. ISPEXEC TBSORT MODSIZES FIELDS(NAME,C,A,SIZE,N,D)
Set
the program variable BUFFER to contain: TBSORT MODSIZES FIELDS(NAME,C,A,SIZE,N,D)
Set
program variable BUFLEN to the length of the variable BUFFER. Issue
the command: CALL ISPEXEC (BUFLEN, BUFFER);
or alternately CALL ISPLINK ('TBSORT ','MODSIZES','(NAME,C,A,SIZE,N,D)');
|