ICOUNT
Counts file items whose index keys meet specified conditions.
Command Class
TCL-I command.
Syntax
ICOUNT file-specifier WITH index-name {{operator} literalValue{ AND operator literalValue}}
Syntax Elements
file-specifier Specifies a file as defined in Conventions, except that file modifiers cannot be used because indexes are only definable on data sections.
index-name The name of an index associated with the file.
operator One of the following relational operators:
EQ, =is equal to
GT, >is greater than
GE, >=is greater then of equal to
LT, <is less than
LE, <=is less than or equal to
If the operator and literal value are omitted, a count of all indexed item-ids is displayed. If a literal value is specified, but no operator, the EQ operator is used.
literalValue One or more literal strings enclosed in either single or double quotes. Include one string for each BY clause in the index definition.
If the operator is EQ or =, a trailing ] character is interpreted as a wildcard (see Wildcard Searching).
AND Specifies that ICOUNT should count keys that fall between specified values; that is, keys that are greater than, or greater than or equal to the lower key value, and less than, or less than or equal to the higher key value. The keys meeting this condition represent a contiguous group of keys within the index.
Note that you cannot use the EQ or = operator with AND.
Operation
ICOUNT is similar to the English COUNT command in that it counts items meeting specified conditions. The difference is that ICOUNT uses a file index to count items whose keys meet a specified condition.
ICOUNT cannot work from an active select list. If a select list is active
when ICOUNT is invoked, the message Abandoning previous select list [ICOUNT] is displayed and the list is
discarded before returning the count information.
On completion, ICOUNT generates the following message:
itemCount item(s) from keyCount unique index key(s) counted.
where itemCount is the number of items meeting the selection criteria and keyCount is the number of unique keys.
The following example counts all items in the file CUST.FILE that are indexed on XREGION:
ICOUNT CUST.FILE WITH XREGION
Using Selection Criteria
To count a subset of the indexed items, specify selection criteria; that is, an operator and a literal string value to match. Valid operators are EQ, LT, <, GT, >, GE, >=, LE and <=, and their symbol equivalents (see Syntax).
The following example counts all items in a file indexed on XREGION whose keys are greater than A1.
ICOUNT CUST.FILE WITH XREGION GT "A1"
More complex matching can be performed by combining selection criteria with the AND connective. Under these circumstances, you must use GE, >=, GT or > to specify the lower limit and LE, <=, LT or < the upper limit of the required range of keys (see Syntax); the EQ operator is not valid. For example, to count the portion of CUST.FILE with key values greater than or equal to A1 and less than B1, use the following command:
ICOUNT CUST.FILE WITH XREGION GE "A1" AND LT "B1"
Note
Using the AND connective with ICOUNT counts keys that fall between specified values; that is, keys that are greater than or greater than or equal to the lower key value and less than or less than or equal to the higher key value. The keys meeting this condition represent a contiguous group of keys within the index. Any other form for multiple selection criteria is invalid and produces an error message.
Wildcard Searching
When using the EQ or = operator, the literal value can end with the ] wildcard character. The following example counts all the key values that begin with A.
ICOUNT CUST.FILE WITH XREGION EQ "A]"
Output Conversions
For indexes that were created from dictionary definitions that include output conversions, ICOUNT applies those output conversions as input conversions to the literal data specified as appropriate. For backwards compatibility, this behaviour can be inhibited with the EXTERNAL.KEY environment option.
Case Sensitivity
If keyword case-insensitivity is selected, the WITH, EQ, GT, GE, LT, LE and AND keywords can be in upper or lower case. Otherwise, they must be in upper case.
The case of the literalValue parameter is subject to the case-sensitivity settings that were current when the index was created (see CREATE-INDEX, Item Lists and Selection Criteria). If in doubt, ensure that the case of this parameter matches that of the index key values.