Find Field Numbers in List (QGYFNDF) API
Required Parameter Group:
| 1 | Request handle | Input | Char(4) |
| 2 | Receiver variable | Output | Char(*) |
| 3 | Length of receiver variable | Input | Binary(4) |
| 4 | Format | Input | Char(8) |
| 5 | Field specification | Input | Char(*) |
| 6 | Total number returned | Output | Binary(4) |
| 7 | Record number | I/O | Binary(4) |
| 8 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Find Field Numbers in List (QGYFNDF) API returns the number of the entry in a list of information and the value of that field whenever the value of that field changes. Two types of find operations are supported.
- Generic find operations: The caller specifies which field in the record is used to cause a break.
- Formatted find operations: The format selected determines which field or fields cause a break.
Authorities and Locks
None.
Required Parameter Group
- Request handle
- INPUT; CHAR(4)
The handle of the request. When a list API is called, a handle is returned upon successful completion. One of these handles is required as input to this API.
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The amount of data the application program is prepared to receive. If the length specified is larger than the amount of data available, the receiver is not changed beyond the amount of data available.
The receiver variable must be large enough to hold one array entry. For format FNDF0100 the minimum receiver length must be:
4 + field length rounded up to a multiple of 4
For format FNDF0200 the minimum receiver length must be:40
- Format name
- INPUT; CHAR(8)
The content and format of the information returned. The possible format names are:
FNDF0100 Generic find operation is performed. The calling program specifies the field offset and length in the field specification parameter.
Each time the field changes in the list, a record entry is added to the receiver variable.
FNDF0200 Spooled file find operation by printer is performed. This format can only be used against a list of spooled files with format OSPL0200 that contains the following fields:
- Device name (field key 208)
- Output queue library (field key 207)
- Output queue name (field key 206)
Each time the device name field changes in the list, a record is added to the receiver variable. In addition, when the printer assigned value is 2, then each time the output queue changes in the list a record is added to the receiver variable.
- Field specification
- INPUT; CHAR(*)
The fields to search for a break. For the FNDF0100 format this parameter must be an array of field offsets and field lengths. The fields specified are considered one logical field for comparison when searching for changes in the fields. The values for the fields will be returned in the receiver variable concatenated in the same order they are specified in this parameter. For the FNDF0100 format, this parameter must have the following layout:
Offset Type Field Dec Hex 0 0 BINARY(4) Number of fields to search on. Valid values are 1 through 3. Offsets vary. These fields repeat, in the order listed, for each field to search on. BINARY(4) Field offset BINARY(4) Field length
For the FNDF0200 format, this parameter must have the following layout:
Offset Type Field Dec Hex 0 0 BINARY(4) Number of fields to search on. This must be set to zero (0).
- Total number returned
- OUTPUT; BINARY(4)
The total number of array entries returned in the receiver variable. This is not necessarily the total number of entries available. If the receiver variable is not large enough to hold all available entries, the record number parameter is set to the record number where the next break occurs.
- Record number
- I/O; BINARY(4)
On input, the record to begin searching for field breaks. This should be set to 1 for the initial call for a list so that searching begins with the first record. This program always assumes a field break to have occurred at the record specified by this parameter. Thus, the record specified is always returned in the receiver variable.
On output, this parameter indicates whether the information in the receiver variable is partial or complete. If the receiver variable is complete, this parameter will be set to zero. If the receiver variable contains partial information, this parameter will be set to the record number where the next field break occurs. This value can be specified as input on a subsequent call to this program to continue the search for field breaks.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of Receiver Variable
Format FNDF0100
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Record size |
| Offsets vary. These fields repeat, in the order listed, for each entry returned. | BINARY(4) | Record number | |
| CHAR(*) | Field value | ||
| CHAR(*) | Padding for boundary alignment | ||
Format FNDF0200
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Record size |
| Offsets vary. These fields repeat, in the order listed, for each entry returned. | BINARY(4) | Record number | |
| CHAR(10) | Output queue name | ||
| CHAR(10) | Output queue library | ||
| CHAR(1) | Printer assigned value | ||
| CHAR(10) | Device name | ||
| CHAR(*) | Padding for boundary alignment | ||
Field Descriptions
Device name. The name of the printer device where the spooled file is printed.
Field value. The value of the field where the break occurs.
This is a concatenation of the fields specified to search on. The fields are concatenated in the order they were specified in the field specification parameter. The length of this field is the sum of all field lengths specified in the field specification parameter.
Output queue library. The name of the library containing the output queue that the spooled file is assigned.
Output queue name. The name of the output queue that the spooled file is assigned.
Padding for boundary alignment. A reserved field.
Printer assigned value. The value specifying whether this spooled file is assigned to a printer. Valid values are 1 through 3.
| Printer Value | Description |
|---|---|
| 1 | Spooled file is assigned to a specific printer. The device name field contains the name of the printer. |
| 2 | Spooled file is assigned to multiple printers. The device name field is set to blanks. |
| 3 | Spooled file is not assigned to a printer. The device name field is set to blanks. |
Record number. The record number in the list where the break occurs.
Record size. The size of the record in the array shown.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| GUI0001 E | Invalid handle specified. |
| GUI0002 E | &2 is not valid for length of receiver variable. |
| GUI0101 E | List information is not valid. Reason code &1. |
| GUI0102 E | Offset of field, &1, is not valid. |
| GUI0103 E | Invalid handle specified. Length of field, &2, is not valid. Reason code &1. |
| GUI0104 E | Record number, &1, is not valid. |
| GUI0106 E | List does not contain required fields. |
| GUI0107 E | Number of fields, &2, is not valid. Reason code &1. |
API introduced: V3R6