IFCTO (HLI function)
The conventions used on this page are described in Function call notation conventions.
Summary
- Description
- The IFCTO call (COUNT OCCURRENCES) counts the number of occurrences of the specified field, or fields, in the current record and returns a count value for each field in an output parameter.
- Thread type
- single cursor IFSTRT thread
- IFCALL function number
- 65
Syntax
IFCTO(RETCODE,BUFFER,FIELD_LIST,CTO_NAME,%VARBUF,%VARSPEC)
- Compile-only form
IFCALL function number: 66
IFCTOC(RETCODE,FIELD_LIST,CTO_NAME)
- Execute-only form
IFCALL function number: 67
IFCTOE(RETCODE,BUFFER,CTO_NAME,%VARBUF,%VARSPEC)
Specify the parameters in the syntax order shown above.
| Parameter | Description |
|---|---|
| RETCODE | [O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value. |
| BUFFER | [O,c,r] The buffer location is a required output parameter that specifies the address of the user's data area. Specify a character string. The buffer contains the occurrence counter, or counters, returned by IFCTO for each field that is defined by the FIELD_LIST parameter, described below. For each field specified, a four-byte value is returned.
Multiple count values are positioned in order corresponding to the location of the fields in the current record. If a specified field does not occur in the record, its counter is set to zero. |
| FIELD_LIST | [I,c,r] The field specification is a required input parameter that defines the field, or fields, that are to be counted in the current record. Specify the name of a field as a character string. You must list at least one field to be counted in the current record. You can list additional fields by separating field names with a comma. |
| CTO_NAME | [I,s,o/r] The name of the IFCTO compilation is a required input parameter with IFCTOC and optional with IFCTO or IFCTOE. If specified, Model 204 saves the compilation using this name. Specify the name as unique and as a short character string (maximum 32 characters).
Any characters except the following are valid in the name: blank, comma, parenthesis, equal sign, or semicolon. The first character in the name must be alphanumeric. A null value is equivalent to omitting the name parameter. |
| %VARBUF | [I,c,o] The variable buffer is an optional input parameter that addresses a data area which accommodates up to 255 bytes of data per value. The buffer contains values that are defined by the %VARSPEC parameter, below, to be assigned to %variables. Specify a character string. For information about %variables, see Declaring %variables and %variable arrays. |
| %VARSPEC | [I,c,o] The variable specification describes the format of the data that is contained in the %variable parameter, and it lists the %variables to be assigned. %VARSPEC specifies the contents of the variable buffer, described above. Specify a character string that follows a LIST, DATA, or EDIT syntax.
%VARSPEC is a required input parameter if %VARBUF is specified. |
Usage notes
Use the IFCTO call to count occurrences of fields in the current record. Issue the IFCTO call after a current record is selected by IFGET, IFPOINT, or IFBREC. The record is enqueued with share status.
IFCTO is available for use only on a single cursor IFSTRT thread. IFCTO operates similarly to the IFOCC call that is used with multiple cursor IFSTRT.
The IFCTO call is the equivalent of the SOUL COUNT OCCURRENCES OF statement in the host language environment.
Coding example (PL/1)
DCL ERROR FIXED BIN (31), BUFFER CHAR (8) FIELDS CHAR (20) VARYING INITIAL ('CAR,CHILD NAME'); . . . CALL IFCTO (ERROR,BUFFER,FIELDS)
Note: After the IFCTO call shown above is issued to count the number of field occurrences in a record that contains two cars and five children, BUFFER contains the following hexadecimal value:
0000000200000005