RPGIV @ Work

A unique site for RPG and System i Lovers

Welcome!

Hi, this site will provide all what you need in System i and RPG developments.

My Name is Chamara Withanachchi, System i Expert and RPG Developer. And in the field for last 11 years.

I hope you will find lot of valuable information from this site

List Fields - QUSLFLD Print E-mail
User Rating: / 2
PoorBest 
Written by Chamara Withanachchi   

List Fields (QUSLFLD) API


  Required Parameter Group:

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)

  Optional Parameter:

6 Error code I/O Char(*)

  Default Public Authority: *USE

  Threadsafe: No

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:

  • Generate a list of field format names.
  • Gather additional information about specific field formats.
  • Create a product similar to the Structured Query Language (SQL) using the Open Query File (OPNQRYF) command.
  • Create applications similar to the data file utility (DFU).
  • Create a compiler supporting externally described data.
  • Create applications that use data defined to the system.

Authorities and Locks

User Space Authority
*CHANGE
User Space Library Authority
*EXECUTE
File Library Authority
*USE
File Authority
*OBJOPR
User Space Lock
*EXCLRD
File Lock
*SHRRD

Required Parameter Group

Qualified user space name
INPUT; CHAR(20)

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

Format name
INPUT; CHAR(8)

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
Qualified file name
INPUT; CHAR(20)

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

Record format name
INPUT; CHAR(10)

The record format name whose fields are to be returned.

Override processing
INPUT; CHAR(1)

Whether overrides are to be processed. The possible values are:

0 No override processing
1 Override processing

Optional Parameter

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure. If this parameter is omitted, diagnostic and escape messages are issued to the application.


Format of the Generated List

The field list consists of:

  • A user area
  • A generic header
  • An input parameter section
  • A header section
  • The FLDL0100, FLDL0200, or FLDL0300 list data section

For details about the user area and generic header. For details about the remaining items, see the following sections. For descriptions of each field in the list returned.

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.


Input Parameter Section

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


Header Section

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


FLDL0100 List Data Section

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


FLDL0200 List Data Section

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


FLDL0300 List Data Section

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


Field Descriptions

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.

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.


Error Messages

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.
<Previous   Next>