| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Qualified file name | Input | Char(20) |
| 4 | Record format name | Input | Char(10) |
| 5 | Override processing | Input | Char(1) |
| 6 | Error code | I/O | Char(*) |
The List Fields (QUSLFLD) API generates a list of fields within a specified file record format name. The list of fields is placed in a specified user space. The generated list replaces any existing information in the user space. You can use the QUSLFLD API only with database file types, such as *PF, *LF, and *DDMF, and device file types, such as *ICFF and *PRTF.
You can use the QUSLFLD API to:
The name of the user space that is to receive the created list, and the library in which it is located. The first 10 characters contain the user space name, and the second 10 characters contain the library name. You can use these special values for the library name:
| *CURLIB | The job's current library |
| *LIBL | The library list |
The format of the information returned. You must use the following format name:
| FLDL0100 | Field information |
| FLDL0200 | Field and default value information |
| FLDL0300 | Field, alternative field name, and default value information |
For more information, see Format of the Generated List.
The file whose member names are to be placed in the list, and the library in which it is located. The first 10 characters contain the file name, and the second 10 characters contain the library name. You can use these special values for the library name:
| *CURLIB | The job's current library |
| *LIBL | The library list |
The record format name whose fields are to be returned.
Whether overrides are to be processed. The possible values are:
| 0 | No override processing |
| 1 | Override processing |
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
The field list consists of:
For details about the user area and generic header, see User space format for list APIs. For details about the remaining items, see the following sections. For descriptions of each field in the list returned, see Field Descriptions.
When you retrieve list entry information from a user space for format FLDL0100, you must use the entry size returned in the generic header as a displacement to the next list entry. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid.
When you retrieve list entry information from a user space for format FLDL0200 or FLDL0300, you must use the length provided at the beginning of format FLDL0200 or FLDL0300 as a displacement to the next list entry. If you do not use the length provided in FLDL0200 or FLDL0300, the result may not be valid.
For examples of how to process lists, see the API examples.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name |
| 10 | A | CHAR(10) | User space library name |
| 20 | 14 | CHAR(8) | Format name |
| 28 | 1C | CHAR(10) | File name specified |
| 38 | 26 | CHAR(10) | File library name specified |
| 48 | 30 | CHAR(10) | Record format name specified |
| 58 | 3A | CHAR(1) | Override processing |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | File name used |
| 10 | A | CHAR(10) | File library name used |
| 20 | 14 | CHAR(10) | File type |
| 30 | 1E | CHAR(10) | Record format name used |
| 40 | 28 | BINARY(4) | Record length |
| 44 | 2C | CHAR(13) | Record format ID |
| 57 | 39 | CHAR(50) | Record text description |
| 107 | 6B | CHAR(1) | Reserved |
| 108 | 6C | BINARY(4) | Record text description CCSID |
| 112 | 70 | CHAR(1) | Variable length fields in format indicator |
| 113 | 71 | CHAR(1) | Graphic fields indicator |
| 114 | 72 | CHAR(1) | Date and time fields indicator |
| 115 | 73 | CHAR(1) | Null-capable fields indicator |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Field name |
| 10 | A | CHAR(1) | Data type |
| 11 | B | CHAR(1) | Use |
| 12 | C | BINARY(4) | Output buffer position |
| 16 | 10 | BINARY(4) | Input buffer position |
| 20 | 14 | BINARY(4) | Field length in bytes |
| 24 | 18 | BINARY(4) | Digits |
| 28 | 1C | BINARY(4) | Decimal position |
| 32 | 20 | CHAR(50) | Field text description |
| 82 | 52 | CHAR(2) | Edit code |
| 84 | 54 | BINARY(4) | Edit word length |
| 88 | 58 | CHAR(64) | Edit word |
| 152 | 98 | CHAR(20) | Column heading 1 |
| 172 | AC | CHAR(20) | Column heading 2 |
| 192 | C0 | CHAR(20) | Column heading 3 |
| 212 | D4 | CHAR(10) | Internal field name |
| 222 | DE | CHAR(30) | Alternative field name |
| 252 | FC | BINARY(4) | Length of alternative field name |
| 256 | 100 | BINARY(4) | Number of DBCS characters |
| 260 | 104 | CHAR(1) | Null values allowed |
| 261 | 105 | CHAR(1) | Host variable indicator |
| 262 | 106 | CHAR(4) | Date and time format |
| 266 | 10A | CHAR(1) | Date and time separator |
| 267 | 10B | CHAR(1) | Variable length field indicator (overlay for MI mapping) |
| 268 | 10C | BINARY(4) | Field text description CCSID |
| 272 | 110 | BINARY(4) | Field data CCSID |
| 276 | 114 | BINARY(4) | Field column headings CCSID |
| 280 | 118 | BINARY(4) | Field edit words CCSID |
| 284 | 11C | BINARY(4) | UCS-2 displayed field length |
| 288 | 120 | BINARY(4) | Field data encoding scheme |
| 292 | 124 | BINARY(4) | Maximum large object field length |
| 296 | 128 | BINARY(4) | Pad length for large object |
| 300 | 12C | BINARY(4) | Length of user-defined type name |
| 304 | 130 | CHAR(128) | User-defined type name |
| 432 | 1B0 | CHAR(10) | User-defined type library name |
| 442 | 1BA | CHAR(1) | Datalink link control |
| 443 | 1BB | CHAR(1) | Datalink integrity |
| 444 | 1BC | CHAR(1) | Datalink read permission |
| 445 | 1BD | CHAR(1) | Datalink write permission |
| 446 | 1BE | CHAR(1) | Datalink recovery |
| 447 | 1BF | CHAR(1) | Datalink unlink control |
| 448 | 1C0 | BINARY(4) | Display or print row number |
| 452 | 1C4 | BINARY(4) | Display or print column number |
| 456 | 1C8 | CHAR(1) | ROWID column |
| 457 | 1C9 | CHAR(1) | Identity column |
| 458 | 1CA | CHAR(1) | GENERATED BY |
| 459 | 1CB | CHAR(1) | Identity column - CYCLE |
| 460 | 1CC | DECIMAL(31,0) | Identity column - Original START WITH |
| 476 | 1DC | DECIMAL(31,0) | Identity column - Current START WITH |
| 492 | 1EC | BINARY(4) | Identity column - INCREMENT BY |
| 496 | 1F0 | DECIMAL(31,0) | Identity column - MINVALUE |
| 512 | 200 | DECIMAL(31,0) | Identity column - MAXVALUE |
| 528 | 210 | BINARY(4) | Identity column - CACHE |
| 532 | 214 | CHAR(1) | Identity column - ORDER |
| 533 | 215 | CHAR(11) | Reserved |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of FLDL0200 format |
| 4 | 4 | BINARY(4) | Displacement to default value |
| 8 | 8 | BINARY(4) | Length of default value |
| 12 | C | All fields defined by FLDL0100 format | |
| * | * | CHAR(*) | Default value |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of FLDL0300 format |
| 4 | 4 | BINARY(4) | Displacement to all fields defined by FLDL0100 format |
| 8 | 8 | BINARY(4) | Displacement to alternative field name |
| 12 | C | BINARY(4) | Displacement to default value |
| 16 | 10 | BINARY(4) | Length of default value |
| * | * | All fields defined by FLDL0100 format | |
| * | * | CHAR(*) | Alternative field name (long) |
| * | * | CHAR(*) | Default value |
Alternative field name. The alternative name of the field the entry describes. This is the DDS keyword ALIAS or a long column name in SQL. If the length of the alternative name is greater than 30, the Alternative field name will contain blanks. If the FLDL0300 format is used, the Alternative field name (long) will always contain the alternative name.
Alternative field name (long). The alternative name of the field the entry describes. This is the DDS keyword ALIAS or a long column name in SQL.
Column heading 1. The description of the first column heading for this field. It contains blanks if the heading is not defined.
Column heading 2. The description of the second column heading for this field. It contains blanks if the heading is not defined.
Column heading 3. The description of the third column heading for this field. It contains blanks if the heading is not defined.
Data type. The type of field:
| A | Alphanumeric (character) |
| B | Binary |
| D | Digits only |
| E | Either DBCS or alphanumeric |
| F | Floating point |
| G | Graphic data type |
| H | Hexadecimal |
| I | Inhibit entry |
| J | Double-byte character set (DBCS) data only |
| L | Date |
| M | Numeric only |
| N | Numeric shift |
| O | (Open) Both DBCS and alphanumeric |
| P | Packed decimal |
| S | Zoned decimal |
| T | Time |
| W | Katakana |
| X | Alphabetic only (character) |
| Y | Numeric only |
| Z | Timestamp |
| 1 | Binary large object (BLOB) |
| 2 | Character large object (CLOB) |
| 3 | Graphic data large object (DBCLOB) |
| 4 | Datalink |
| 5 | Binary character |
Datalink integrity. How the control of the file is handled. This value applies to datalink fields. A datalink is a field data type that is used to point to another object that contains the data for that field. If the datalink link control field is 0 (no link control), this field is not applicable. The possible values are:
| 0 | All linked files are under control of the database. |
| 1 | All linked files are under selective database control if the server has the Datalink File Manager installed. |
Datalink link control. Whether the file should be linked by the Datalink File Manager. The Datalink File Manager is a function that tracks which files are linked to a specific database file. This value applies to datalink fields. The possible values are:
| 0 | No link control. |
| 1 | File link control. |
Datalink read permission. The check that is done to read the file. This value applies to datalink fields. If the datalink link control field is 0 (no link control), this field is not applicable. The possible values are:
| 0 | The database controls whether a user has read authority. |
| 1 | The file system controls whether a user has read authority. |
Datalink recovery. Whether file recovery is done. This value applies to datalink fields. If the datalink link control field is 0 (no link control), this field is not applicable. The possible values are:
| 0 | Recovery is not done. |
| 1 | Recovery is done. |
Datalink unlink control. The action that is done to a file during an unlink operation. This value applies to datalink fields. If the datalink link control field is 0 (no link control) or the datalink write permission field is 1 (File system control), this field is not applicable. The possible values are:
| 0 | Restore the file owner and file authorities that existed prior to the file link when an unlink operation occurs. |
| 1 | Delete the file when an unlink operation occurs. |
Datalink write permission. The check that is done to write to the file. This value applies to datalink fields. If the datalink link control field is 0 (no link control), this field is not applicable. The possible values are:
| 0 | The file is blocked from accepting writing. |
| 1 | The file system controls whether a user has write authority. |
Date and time fields indicator. Whether this format contains date and time fields. The possible values are:
| 0 | The format does not contain date and time fields. |
| 1 | The format contains date and time fields. |
Date and time format. This value applies to date, time, and timestamp fields. It also may apply to packed decimal, zoned decimal, and character fields in a logical file. The possible values are:
| *USA | IBM USA standard (mm/dd/yyyy, hh:mm a.m., hh:mm p.m.) |
| *ISO | International Standards Organization (yyyy-mm-dd, hh.mm.ss) |
| *EUR | IBM European Standard (dd.mm.yyyy, hh.mm.ss) |
| *JIS | Japanese Industrial Standard Christian Era (yyyy-mm-dd, hh:mm:ss) |
| *SAA | SAA timestamp |
| *MDY | Month/day/year (mm/DD/yy) |
| *DMY | Day/month/year (DD/mm/yy) |
| *YMD | Year/month/day (yy/mm/DD) |
| *JUL | Julian (yy/ddd) |
| *HMS | Hour/minute/second (hh:mm:Ss) |
| MDYY | Month/day/year (mm/DD/yyyy) |
| DMYY | Day/month/year (DD/mm/yyyy) |
| YYMD | Year/month/day (yyyy/mm/DD) |
| JUL4 | Long Julian (yyyy/ddd) |
| CMDY | Century/month/day/year (c/mm/DD/yy) |
| CDMY | Century/day/month/year (c/DD/mm/yy) |
| CYMD | Century/year/month/day (c/yy/mm/DD) |
| *MY | Month/year (mm/yy) |
| *YM | Year/month (yy/mm) |
| *MYY | Month/year (mm/yyyy) |
| *YYM | Year/month (yyyy/mm) |
Date and time separator. This value applies only to date or time fields. The possible values are:
| / | Slash separator |
| - | Dash separator |
| . | Period separator |
| , | Comma Separator |
| : | Colon separator |
| (blank) | Blank separator |
Note: If the date and time separator field returns a blank, the separator may have been determined by the default for the specified value of the date and time format field.
Decimal position. The number of decimal positions. This entry is zero if the field is not numeric.
Default value. The default value for this field. The
default value is defined by the DFT or DFTVAL keyword used in DDS, or by the
WITH DEFAULT clause of the CREATE TABLE SQL statement. Some examples of
returned data are:
| SQL clause WITH DEFAULT value, where value is: | DDS keyword DFT(value), where value is: | Returned by API: |
|---|---|---|
| 'ABC' | 'ABC' | 'ABC' |
| +999 | +999 | +999 |
| 999 | +999 | |
| 999 | 999 | |
| -999 | -999 | -999 |
| USER Note: This value means to use the User ID as the value. |
USER | |
| COCODE ( 'ABC' ) | COCODE ( 'ABC' ) |
Digits. The number of digits. This entry is zero if the field is not numeric.
Displacement to all fields defined by FLDL0100 format. This field contains the offset from the beginning of this entry to the beginning of the data mapped by the FLDL0100 format.
Displacement to alternative field name. This field contains the offset from the beginning of this entry to the beginning of the alternative field name. This field is zero if there is no alternative field name.
Displacement to default value. This field contains the offset from the beginning of this entry to the beginning of the default data. This field is zero if there is no default data for the field.
Display or print column number. This field contains the column number specified in the DDS source or as calculated at compile-time by the DDS compiler. If this value was not calculated at compile-time, it will be set to -1.
Display or print row number. This field contains the row number specified in the DDS source. This value will be relative to the start of the format. If spacing keywords (such as SPACEA, SKIPA, and SLNO) were specified for the file, record or field, this value will be set to -1.
Edit code. The field edit code.
Edit word. The field edit word.
Edit word length. The length of the edit word used.
Field column headings CCSID.
| 0 | There are no field column headings. |
| 1-65,535 | The CCSID for the field column headings. |
Field data CCSID.
| 0 | There is no field data. |
| 1-65,535 | The CCSID for the field data. |
Field data encoding scheme. The encoding scheme associated with the field data CCSID.
Field edit words CCSID
| 0 | There are no field edit words. |
| 1-65,535 | The CCSID for the field edit words. |
Field length in bytes. The number of bytes the field occupies.
Field name. The name of the field the entry describes.
Field text description. The description of the field.
Field text description CCSID.
| 0 | There is no field text description. |
| 1-65,535 | The CCSID for the field text description. |
Record text description CCSID.
| 0 | There is no record text description. |
| 1-65,535 | The CCSID for the record text description. |
File library name specified. The library specified in the call to the API.
File library name used. The name of the library that contained the file.
File name specified. The file specified in the call to the API.
File name used. The name of the file where the member list was found.
File type. The type of file found.
| BSCF | Binary synchronous communications (BSC) file |
| CMNF | Communications file |
| DDMF | Distributed data management file |
| DKTF | Diskette file |
| DSPF | Display file |
| ICFF | Intersystem communications function file |
| LF | Logical file |
| MXDF | Mixed file |
| PF | Physical file |
| PRTF | Printer file |
| SAVF | Save file |
| TAPF | Tape file |
Format name. The content and format of the information returned for each field. The possible values are:
| FLDL0100 | Field information |
| FLDL0200 | Field and default value information |
| FLDL0300 | Field, alternative field name, and default value information |
GENERATED BY. This value defines when DB2 will generate a value for the column when a row is inserted or updated in a table. If the identity column field is 0 and the ROWID column field is 0, this field is not applicable. The possible values are:
| 1 | BY DEFAULT - Indicates that DB2 will generate a value for the column when a row is inserted or updated in a table unless a value is specified. |
| 2 | ALWAYS - Indicates that DB2 will always generate a value for the column when a row is inserted or updated in a table. |
Graphic fields indicator. Whether this format contains graphic fields. The possible values are:
| 0 | The format does not contain graphic fields. |
| 1 | The format does contain graphic fields. |
Host variable indicator. Whether a query has been defined with a host variable or a parameter marker in place of a comparison operand (for example, FIELDA > :hostvar) or an arithmetic operand (for example, FIELDA * 10). Possible values follow:
| 0 | The query definition does not contain a host variable or a parameter marker. |
| 1 | The query definition does contain a host variable or a parameter marker. |
Identity column. This value specifies whether or not this column was created as an identity column. The possible values are:
| 0 | This is not an identity column. |
| 1 | This is an identity column. |
Identity column - CACHE. This value is the number of cached values. If the Identity column field is 0 (no value specified), this field is not applicable.
Identity column - CYCLE. This value specifies whether this identity column should continue to generate values after generating either its maximum or minimum value. If the identity column field is 0, this field is not applicable. The possible values are:
| 0 | This identity column should not continue to generate values after generating either its minimum or maximum value. |
| 1 | This identity column should continue to generate values after generating either its minimum or maximum value. |
Identity column - INCREMENT BY. This value specifies the interval between consecutive values of the identity column. This value applies to identity column fields. If this value is positive, this is an ascending identity column. If the value is negative, this is a descending identity column. If the identity column field is 0, this field is not applicable.
Identity column - MAXVALUE. This value specifies the maximum value at which an ascending identity column either cycles or stops generating values, or a descending identity column cycles to after reaching the minimum value. If the identity column field is 0, this field is not applicable.
Identity column - MINVALUE. This value specifies the minimum value at which a descending identity column either cycles or stops generating values, or an ascending identity column cycles to after reaching the maximum value. This value applies to identity column fields. If the identity column field is 0, this field is not applicable.
Identity column - ORDER. This value specifies whether the identity values must be generated in order of request. If the identity column field is 0, this field is not applicable. The possible values are:
| 0 | Identity values need not be generated in order of request. |
| 1 | Identity values must be generated in order of request. |
Identity column - Original START WITH. This value specifies the first value for the identity column as defined when the table was created. If the identity column field is 0, this field is not applicable.
Identity column - Current START WITH. This value specifies the first value for the identity column. If the START WITH value for the identity column was changed through the ALTER TABLE command, this value will show the current setting. If the identity column field is 0, this field is not applicable.
Input buffer position. The field's position within the input record.
Internal field name. The internal name used to identify the field the entry describes.
Length of alternative field name. The length of the alternative field name definition.
Length of default value. The length of the default value for this field. If the field has no default value, this field is zero.
Length of FLDL0200 format. The combined length of all data returned in format FLDL0200. Use this value to access the next list data entry.
Length of FLDL0300 format. The combined length of all data returned in format FLDL0300. Use this value to access the next list data entry.
Length of user-defined type name. The length of the user-defined type name. If the field has no user-defined type, this field is zero.
Maximum large object field length. The maximum length of data that can be contained for this field. This value applies to fields with the BLOB, CLOB or DBCLOB data type.
Null-capable fields indicator. Whether this format contains null-capable fields. The possible values are:
| 0 | The format does not contain null-capable fields. |
| 1 | The format contains null-capable fields. |
Null values allowed. Whether the result of this field can be the null value. The possible values are:
| 0 | The field does not allow the null value. |
| 1 | The field does allow the null value. |
Number of DBCS characters. The number of DBCS characters this field can contain if the field type is graphic data type. This value does not include the 2 bytes for the variable length portion of the field.
Offset to default value. The offset from the beginning of format FLDL0200 to the start of the default value for this field. If the field has no default value, this value is zero.
Output buffer position. The field's position within the output record.
Override processing. Whether overrides are to be processed. The possible values are:
| 0 | No override processing |
| 1 | Override processing |
Pad length for large object. This value applies fields with the BLOB, CLOB or DBCLOB data type. This value is the pad length of the buffer for this field.
Record format ID. The record format identifier.
Record format name specified. The record format specified in the call to the API.
Record format name used. The name of this record format.
Record length. The length of this record format.
Record text description. The text description of this record format.
Record text description CCSID.
| 0 | There is no record text description. |
| 1-65,535 | The CCSID for the record text description. |
Reserved. An ignored field.
ROWID column. This value specifies that this field has been designated as a ROWID column. The possible values are:
| 0 | The ROWID attribute was not specified on this field. |
| 1 | This field was created with the ROWID attribute. |
UCS-2 displayed field length. The display length of a field containing UCS-2 data. This value is zero if the field does not contain UCS-2 data. For information about UCS-2, see the Globalization topic in the iSeries Information Center.
User-defined type name. The name of the user-defined type object.
User-defined type library name. The library containing the user-defined type object.
Use. How the field is used:
| I | Input |
| O | Output |
| B | Both input and output |
| N | Neither |
Note: Use is from the program point of view and not necessarily the use specified in the DDS that created the file. For example, *DSPF subfile record fields return B even if the field is O in the DDS.
User space library name. The name of the library that contains the user space that is to receive the generated list.
User space name. The name of the user space that is to receive the generated list.
Variable length field indicator (overlay for MI mapping). Whether the field has been defined as *VARCHAR, VARLEN, or *VARGRF. Possible values are:
| 0 | The field is not variable length. |
| 1 | The field is variable length. |
Variable length fields in format indicator. Whether this format contains variable length fields. The possible values are:
| 0 | The format does not contain variable length fields. |
| 1 | The format contains variable length fields. |
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C20 E | Error found by program &1. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C22 E | Cannot get information about file &1. |
| CPF3C25 E | Value &1 for file override parameter is not valid. |
| CPF3C28 E | Record format &3 in file &1 not found. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9800 E | All CPF98xx messages could be signaled. xx is from 01 to FF. |
| Top | Database and File APIs | APIs by category |