List Fields (QUSLFLD) API


  Required Parameter Group:


  Optional Parameter:


  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:


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:


Format name
INPUT; CHAR(8)

The format of the information returned. You must use the following format name:

For more information, see Format of the Generated List.

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:


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:


Optional Parameter

Error code
I/O; CHAR(*)

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.


Format of the Generated List

The field list consists of:

For details about the user area and generic header, see User spaces. 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 Examples: APIs and exit programs.


Input Parameter Section



Header Section



FLDL0100 List Data Section



FLDL0200 List Data Section

dir

FLDL0300 List Data Section



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:

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:

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:

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:

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:

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:

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:

Date and time fields indicator. Whether this format contains date and time fields. The possible values are:

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:

Date and time separator. This value applies only to date or time fields. The possible values are:

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:

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. Possible values are:

Field data CCSID. Possible values are:

Field data encoding scheme. The encoding scheme associated with the field data CCSID.

Field edit words CCSID Possible values are:

Field length in bytes. The number of bytes the field occupies.

Field name. The name of the field the entry describes.

Field Procedure library name. The name of the library in which the field procedure program is located.

Field Procedure program name. The name of the field procedure program that will be called when this field is written/inserted into, read/fetched from or updated.

Field text description. The description of the field.

Field text description CCSID. Possible values are:

Record text description CCSID. Possible values are:

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.

Format name. The content and format of the information returned for each field. The possible values are:

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:

Graphic fields indicator. Whether this format contains graphic fields. The possible values are:

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:

Identity column. This value specifies whether or not this column was created as an identity column. The possible values are:

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:

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:

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 identity column field is 0, this field is not applicable.

Implicitly hidden. This value specifies whether or not this field is implicitly hidden. The possible values are:

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:

Null values allowed. Whether the result of this field can be the null value. The possible values are:

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:

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. Possible values are:

Reserved. An ignored field.

Row change timestamp GENERATED. This value defines when DB2 will generate a value for the row change timestamp column. If the column is not a row change timestamp column, this field is not applicable. The possible values are:

ROWID column. This value specifies that this field has been designated as a ROWID column. The possible values are:

Start of change

Timestamp Precision. This value applies for a timestamp field. This value is the timestamp precision.

End of change

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 i5/ topic collection.

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:

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:

Variable length fields in format indicator. Whether this format contains variable length fields. The possible values are:



Error Messages



API introduced: V1R3

[ Back to top | Database and File APIs | APIs by category ]