List Database File Members (QUSLMBR) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Qualified database file name | Input | Char(20) |
| 4 | Member name | Input | Char(10) |
| 5 | Override processing | Input | Char(1) |
Optional Parameter:
| 6 | Error code | I/O | Char(*) |
Service Program Name: QUSLMBR
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The List Database File Members (QUSLMBR) API generates a list of database file members and places the list in a specified user space. When you specify a generic member name, you can generate a subset of the member list. You can use the QUSLMBR API with database file types *PF, *LF, and *DDMF. The generated list replaces any existing information in the user space. The file members listed in the user space are not in any predictable order. To retrieve additional information about each member in the list, see the Retrieve Member Description (QUSRMBRD) API.
You can use the QUSLMBR API to:
- List members more quickly than by using the *MBRLIST value on the TYPE parameter of the Display File Description (DSPFD) command.
- Retrieve information for all of the members of a database file more quickly and easily than by multiple calls to the Retrieve Member Description (QUSRMBRD) API. It is your discretion to decide which API best suits the needs of your application. For example, if you want to selectively retrieve member descriptions for a subset of the member list, you might want to use both the QUSLMBR and QUSRMBRD APIs.
- Ensure that the last date the source was changed matches the date of the source used to create the object.
Authorities and Locks
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- File Authority
- *OBJOPR
- User Space Lock
- *EXCLRD
- File Lock
- *SHRRD
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that is to receive the created list. The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. 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 content and format of the information returned for each member. The possible format names are:
MBRL0100 Member name MBRL0200 Member name and source information This format requires more processing than the MBRL0100 format. MBRL0310 Member name and basic description. The member information is the same as that generated by the Retrieve Member Description (QUSRMBRD) API using format MBRD0100. This format requires more system processing and takes longer to produce than the MBRL0200 format. MBRL0320 Member name and expanded description. The member information is the same as that generated by the Retrieve Member Description (QUSRMBRD) API using format MBRD0200. The additional information requires more system processing and takes longer to produce than the MBRL0310 format. MBRL0330 Member name and full description. The member information is the same as that generated by the Retrieve Member Description (QUSRMBRD) API using format MBRD0300. The additional information requires more system processing and takes longer to produce than the MBRL0320 format. For more information, see MBRL0100 List Data Section, MBRL0200 List Data Section, or MBRL0300 List Data Section.
- Qualified database file name
- INPUT; CHAR(20)
The name of the database file whose member names are to be placed in the list. The first 10 characters contain the database file name, and the second 10 characters contain the name of the library where the file is located. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list
- Member name
- INPUT; CHAR(10)
A specific member name, a generic member name, or this special value:
*ALL All members
- Override processing
- INPUT; CHAR(1)
Whether overrides are to be processed. The following character values are used:
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, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
Format of the Generated Lists
The file member list consists of:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section:
- MBRL0100 format
- MBRL0200 format
- MBRL0300 format
The MBRL0300 list data section is generated if MBRL0310, MBRL0320, or MBRL0330 is specified as the format name parameter.
For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the list returned, see Field Descriptions.
When you retrieve list entry information from a user space, 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. For examples of how to process lists, see Examples: APIs and exit programs.
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) | Member 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 attribute |
| 30 | 1E | CHAR(50) | File text description |
| 80 | 50 | BINARY(4) | Total number of members in file |
| 84 | 54 | CHAR(1) | Source file |
| 85 | 55 | CHAR(3) | Reserved |
| 88 | 58 | BINARY(4) | File text description CCSID |
MBRL0100 List Data Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Member name used |
MBRL0200 List Data Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Member name used |
| 10 | A | CHAR(10) | Source type |
| 20 | 14 | CHAR(13) | Creation date and time |
| 33 | 21 | CHAR(13) | Last source change or table refresh date and time |
| 46 | 2E | CHAR(50) | Member text description |
| 96 | 60 | BINARY(4) | Member text description CCSID |
MBRL0300 List Data Section
The MBRL0300 format provides an offset to a retrieved member description. When the member description information cannot be retrieved, the Offset to member description information will be returned as an offset of zero and the message indicating why the information could not be currently retrieved will be left in the Job Log. Also, no Error code parameter, or escape messages will be issued to the application when the member description information cannot be retrieved. The member descriptions have the same format as those generated by the Retrieve Member Description (QUSRMBRD) API. The following relationship exists between the QUSLMBR format name and the QUSRMBRD member descriptions:
- MBRL0310 generates an MBRD0100 description.
- MBRL0320 generates an MBRD0200 description.
- MBRL0330 generates an MBRD0300 description.
For more information about the member description formats, see Retrieve Member Description (QUSRMBRD) API.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Member name used |
| 10 | A | CHAR(2) | Reserved |
| 12 | C | BINARY(4) | Offset to member description information (an offset of zero indicates that no information was retrieved) |
| 16 | 10 | CHAR(16) | Reserved |
Field Descriptions
Creation date and time. The date and time the member was created. The format of this field is in the CYYMMDDHHMMSS as follows:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
File attribute. The type of file found:
| PF | Physical file |
| LF | Logical file |
| DDMF | Distributed data management file |
File library name specified. The name of the library containing the file whose member names are to be placed in the list.
File library name used. The name of the library containing the file whose member names are placed in the list.
File name specified. The name of the file specified in the call to the API.
File name used. The name of the file whose member names are placed in the list.
File text description. The description of the file.
File text description CCSID. The CCSID for the file text description. The job default CCSID of the current process will be used to translate the text. For more information about CCSID, see the i5/OS globalization topic collection.
Format name. The content and format of the information returned for each member.
Last source change or table refresh date and time. For source files, the date and time that this source member was last changed. For SQL materialized query tables, the date and time that the last SQL Refresh Table statement refreshed this member. If the member has never been refreshed, this field will contain hexadecimal zeroes. This field is in the CYYMMDDHHMMSS format where the format is the same as for the creation date and time field.
Member name specified. The name of the member specified in the call to the API.
Member name used. The name of a member found in the file.
Member text description. Description of the member found in the file.
Member text description CCSID. The CCSID for the member text description. The job default CCSID of the current process will be used to translate the text. For more information about CCSID, see the i5/OS globalization topic collection.
Offset to member description information. The number of bytes from the beginning of the user space to the beginning of the retrieved member description.
Override processing. Whether overrides are to be processed. The possible values are:
| 0 | No override processing |
| 1 | Override processing |
Reserved. An ignored field.
Source file. Whether the file is a source file or a data file. The possible values are:
| 0 | Data file |
| 1 | Source file |
Source type. The type of source member if this is a source file. Some possible values are:
- CL
- COBOL
- RPG
- TXT
Total number of members in file. The total number of members in the file specified.
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.
Usage Notes
In multithreaded jobs, this API is not threadsafe and fails for distributed data management (DDM) files of type *SNA.
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. |
| CPF3C23 E | Object &1 is not a database file. |
| CPF3C25 E | Value &1 for file override parameter is not valid. |
| CPF3C27 E | Cannot get information about member &3 from file &1. |
| 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. |
API introduced: V1R3
[ Back to top | Database and File APIs | APIs by category ]