IFOCC (HLI function)

From m204wiki
Revision as of 22:14, 11 July 2016 by ELowell (talk | contribs)
Jump to navigation Jump to search

The conventions used on this page are described in Function call notation conventions.

Summary

Description
The IFOCC 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. IFOCC specifies the cursor for the current record.
Thread type
multiple cursor IFSTRT
IFCALL function number
122

Syntax

IFOCC(RETCODE,BUFFER,CURSOR_NAME,FIELD_LIST,OCC_NAME,%VARBUF,%VARSPEC)

Compile-only form
IFCALL function number: 123

IFOCCC(RETCODE,CURSOR_NAME,FIELD_LIST,OCC_NAME)

Execute-only form
IFCALL function number: 124

IFOCCE(RETCODE,BUFFER,OCC_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 IFOCC for each field that is defined by the FIELD_LIST parameter described in this table. 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 field list. If a specified field does not occur in the record, its counter is set to zero.

CURSOR_NAME [I,c,r] Is a required input parameter that specifies the name of the cursor pointing to the current record for which the field count(s) is (are) performed. This is a character string, the name previously assigned to the cursor in a corresponding IFOCUR call.
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.
OCC_NAME [I,s,o] The name of the IFOCC compilation is an optional input parameter. If OCC_NAME is specified, Model 204 saves the compilation using the name.

Specify the name as unique and as a short character string (maximum 32 characters). The first character in the name must be alphanumeric, and the name must begin with a letter (A-Z or a-z) which may be followed by a letter, a digit (0-9), a period (.), or underscore (_). A null value is equivalent to omitting the name parameter and is not valid.

%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 Using variables and values in computation.
%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 IFOCC call to count occurrences of fields in a record.

IFOCC requires a cursor to specify the current record, but otherwise it operates similarly to the single cursor IFCTO call.

The IFOCC call is the equivalent of the COUNT OCCURRENCES statement in SOUL in the host language multiple cursor environment. For information about the COUNT OCCURRENCES statement, see Operations on multiply occurring fields.

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 BUFFER PIC X(8). 05 CURSOR-NAME PIC X(5) VALUE "CUR1;". 05 FIELD-LIST PIC X(12) VALUE "COLOR, MAKE;". . . . PROCEDURE DIVISION. . . . CALL "IFOCC" USING RETCODE, BUFFER, CURSOR-NAME, FIELD-LIST.