IFGET (HLI function)
Summary
- Description
- The IFGET call (GET) processes the next logical record and returns specified data to the user.
- Thread type
- single cursor IFSTRT
- IFCALL function number
- 15
Syntax
IFGET(RETCODE,BUFFER,EDIT_SPEC,GET_NAME,%VARBUF,%VARSPEC,ORD_SPEC)
- Compile-only form
- IFCALL function number: 48
IFGETC(RETCODE,EDIT_SPEC,GET_NAME,ORD_SPEC)
- Execute-only form
- IFCALL function number: 49
IFGETE(RETCODE,BUFFER,GET_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. The buffer contains the data returned by IFGET for the fields that are defined by the EDIT_SPEC parameter, described below. Specify a character string.
Note: The data is placed in the data area from left to right. If parameters are being passed without dope vectors (IFSTRT language indicator = 2), the data is placed in the area as specified. No length checking is attempted because the Host Language Interface does not know the length of the data area. |
| EDIT_SPEC |
[I,c,r] The edit specification is a required input parameter that defines the fields to be returned from the specified record. The specification describes the format of the data that is returned at the buffer location (see BUFFER above). Specify a character string using one of the following LIST, DATA, or EDIT format options: LIST (fieldname list); DATA (fieldname list); DATA; EDIT EDIT (fieldname list2) (edit format2); where: fieldname list is required and specifies a field name or names. Specify elements in the field name list using one of the following options:
where:
edit format is required in the EDIT specification. edit format specifies a code or codes indicating the format of the data to be returned for the named field in the field name list-edit format pair. See HLI: Field formatting options for HLI calls for a description of LIST, DATA, and EDIT formatting. |
| GET_NAME | [I,s,r/o] The name of the IFGET compilation is an input parameter that is only required if using the Compiled IFAM facility (IFGETC and IFGETE). Model 204 saves the compilation using this name. Specify the name as unique and as a short character string. Any characters except the following are valid in the name: blank, comma, parenthesis, equal sign, or semicolon. 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 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. |
| ORD_SPEC | [I,c,o] The order specification is an optional input parameter that provides ordered index functionality. This parameter works with multicursor IFAM only. The order specification specifies the ORDERED index field that is used to order the return of the records. Specify the order using an IN ORDER clause with the following format:
IN [ASCENDING | DESCENDING] ORDER [BY [EACH] fieldname] [FROM value1] [TO value2] [[NOT] LIKE pattern] where: ASCENDING and DESCENDING are keywords that indicate the order in which the record set will be processed. ASCENDING order is the default. fieldname specifies the name of the field to be used for ordering the records. The FROM and TO clauses specify the range of values for fieldname, where value1 specifies the beginning value, and value2 specifies the ending value. You can specify the range using both FROM and TO, or using only FROM (for all values greater than or equal to), or only TO (for all values less than or equal to). Specifying a range limits the selection of records to be processed. If a range is specified, records that do contain the field are not processed. pattern specifies a field value in the form of a character string that is used to match against the record. Enclose the pattern string inside single quotation marks. See Record loops for a description of the valid pattern characters and examples of their use. Specifying a pattern limits the selection of records to be processed. Only records that meet the pattern matching criteria are processed. Note: Order specification works with multicursor programs only. Change your program to a multicursor program, if necessary. For more information about the order specification, see Record loops. |
Usage notes
Use IFGET to retrieve the next record from the current set. Only fields that you specify are returned to the application program.
The call to IFGET specifies a data area into which the Host Language Interface places the retrieved data. IFGET also specifies the needed fields and the manner in which they are to be formatted in the data area.
Records from a sorted file are returned from the current set in sort key sequence. As each record is retrieved from the current set, its physical record number is stored in the parameter CURREC and it becomes the current record.
Note: Execution of an IFEPRM call on a sorted set returns the record number of the database record. The record is then removed from the current set and the record set count is decreased by one.
Call IFCOUNT and IFLIST before the first IFGET from the current set. Otherwise, IFCOUNT and IFLIST do not reflect the entire set of records selected with IFFIND.
Completion return code (RETCODE)
Note the following special conditions about three of the possible completion codes for IFGET:
| Code | Condition |
|---|---|
| 1 | Conversion of a nonnumeric value was attempted for a B, P, Z, or F edit format, or the integer portion of a numeric value was too large for the output area. The value returned in the data area is binary (HIGH-VALUES in COBOL). Processing of the field name list continues, with the result that more than one value may be in error. |
| 2 | Indicates the end of the found set. |
| 4 | If a nonexistent field name is encountered, the IFGET specification is executed and saved if appropriate, with the nonexistent field being ignored. Any other type of error prevents the specification from being executed or saved. |
Coding examples
Assembler
Suppose that a particular record contains the following pairs:
SCHOOL=HARVARD,SCHOOL=YALE,SCHOOL=MICHIGAN STATE
The application program might include the following:
CALL IFGET,(ERR,WORKAREA, EDIT LIST),VL . . . WORKAREA DS CL120 EDITLIST (DC) CL20 'EDIT(SCHOOL(*)) (M);'
After the IFGET function completed, WORKAREA would contain the following:
X'0307C8C1D9E5C1D9C404E8C1D3C50AD6C8C9D640E2E3C1E3C5'
COBOL
01 RETCODE PIC 9(5) COMP SYNC. 01 WORK-REC. 05 WORK-SSN PIC 9(9). 05 WORK-NAME PIC X(30). 05 WORK-BDATE PIC 9(6). 05 WORK-SCDATE PIC 9(6). 05 FILLER PIC X(2). 05 WORK-GRADE PIC 9(2). 05 WORK-STEP PIC 9(2). . . 01 EDITLIST-1 PIC X(68) VALUE 'EDIT(SSN,NAME,BDATE,SCDATE,GRADE,STEP)(A(9), - A(30),2A(6),'X(2),2J(2));'. . . CALL 'IFGET' USING RETCODE, WORK-REC, EDITLIST-1. . .