List Open Files (QDMLOPNF)
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format of receiver information | Input | Char(8) |
| 4 | Job identification information | Input | Char(*) |
| 5 | Format of job identification information | Input | Char(8) |
| 6 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The List Open Files (QDMLOPNF) API generates a list of *FILE objects that are currently open in the job or that were opened by the thread that is specified in the job identification information input parameter.
The QSYS2.OPEN_FILES table function can be used as an alternative to this API. See OPEN_FILES table function for more information.
Authorities and Locks
- Job Authority
- This API must be called from within the job for which the information is being retrieved, or the caller of the API must be running under a user profile that is the same as the job user identity of the job for which the information is being retrieved. Otherwise, the caller of the API must be running under a user profile that has job control (*JOBCTL) special authority.
The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work management topic collection.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that is to receive 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 of receiver variable parameter correctly. As a result, the API returns only the amount of data specified in the length of receiver variable.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
- Format of receiver information
- INPUT; CHAR(8)
The format of the information returned in the receiver variable. The possible format name is:
OPNF0100 See Format OPNF0100 for details on the list of files that this job or thread has open.
- Job identification information
- INPUT; CHAR(*)
The information that is used to identify the job or thread for which the list of open files is to be returned. See Format JIDF0100 for details.
- Format of job identification information
- INPUT; CHAR(8)
The format of the job identification information. The possible format name is:
JIDF0100 See Format JIDF0100 for details.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format OPNF0100
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of open files available |
| 12 | C | BINARY(4) | Offset to list of open files |
| 16 | 10 | BINARY(4) | Number of open files returned |
| 20 | 14 | BINARY(4) | Length of open file entry |
| 24 | 18 | CHAR(10) | Job name used |
| 34 | 22 | CHAR(10) | Job user name used |
| 44 | 2C | CHAR(6) | Job number used |
| 50 | 32 | CHAR(8) | Thread identifier used |
| 58 | 3A | CHAR(*) | Reserved |
| These fields repeat, in the order listed, for the number of open files. | CHAR(10) | File name | |
| CHAR(10) | File library | ||
| CHAR(10) | Member or device name | ||
| CHAR(10) | File type | ||
| CHAR(10) | Record format | ||
| CHAR(10) | Activation group name | ||
| CHAR(8) | Thread identifier | ||
| CHAR(1) | Open option | ||
| CHAR(3) | Reserved | ||
| BINARY(8) | Activation group number | ||
| BINARY(8) | Write count | ||
| BINARY(8) | Read count | ||
| BINARY(8) | Write/read count | ||
| BINARY(8) | Other I/O count | ||
| BINARY(8) | Relative record number | ||
| BINARY(8) | Number of shared opens | ||
| BINARY(4) | Object auxiliary storage pool number | ||
| BINARY(4) | Library auxiliary storage pool number | ||
| CHAR(10) | Object auxiliary storage pool name | ||
| CHAR(10) | Library auxiliary storage pool name | ||
Field Descriptions
Activation group name. The name of the activation group to which an open file is scoped. This field can contain the following special values:
| *DFTACTGRP | The file is scoped to the default activation group. |
| *JOB | The file is scoped to the job, not a specific activation group. |
| *NEW | The file is scoped to a *NEW activation group. |
Activation group number. The number of the activation group to which an open file is scoped. This field will contain zero for files scoped to the job.
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
File library. The name of the library that contains the open file. If the file is an inline data file, blanks are returned. For DDM files, this is the library in which the DDM file is located.
File name. The name of the file that is open. This field will contain the value QINLINE for unnamed inline data files. For DDM files, this is the name of the DDM file.
File type. The type of file that is open.
| BSCF | Binary Synchronous Communications (BSC) file |
| CMNF | Communications file |
| DDMF | Distributed Data Management file |
| DKTF | Diskette file (spooled and non-spooled) |
| DSPF | Display file |
| ICFF | Intersystem Communications Function file |
| LF | Logical file |
| MXDF | Mixed file |
| PF | Physical file |
| PRTF | Printer file (spooled and non-spooled) |
| SAVF | Save file |
| TAPF | Tape file |
| *INLINE | Inline data file |
Job name used. The name of the job for which open files were listed.
Job number used. The number of the job for which open files were listed.
Job user name used. The user name of the job for which open files were listed.
Length of open file entry. The length of each open file entry.
Library auxilliary storage pool name. The name of the auxilliary storage pool (ASP) in which the library of the open file resides. This field can contain the following special values:
| *SYSBAS | The library resides in the system ASP or a basic user ASP. |
| *N | The ASP name could not be determined at this time. |
Library auxiliary storage pool number. The number of the auxiliary storage pool (ASP) in which the library of the open file resides. Possible values are:
| 1 | System ASP |
| 2-32 | Basic user ASPs |
| 33-255 | Independent ASPs |
Member or device name. If the file type is physical (PF) or logical (LF), this is the name of the database member. If multiple member processing is being performed, the value *ALL is returned. For device files (BSCF, CMNF, DKTF, DSPF, ICFF, MXDF, PRTF, SAVF, or TAPF), this is the name of the last program device used for an I/O operation. This field is blank for device files when no I/O operation has been performed, and always for inline data files. If the file is a spooled file, the value *SPOOL is returned. If the file is a DDM file, blanks are returned.
Number of open files available. The number of open files available to be returned.
Number of open files returned. The number of complete open file entries that are returned.
Number of shared opens. The number of times the file was opened for shared processing. This field will contain zero for open operations that are not shared.
Object auxilliary storage pool name. The name of the auxilliary storage pool (ASP) in which the open file resides. This field can contain the following special values:
| *SYSBAS | The object resides in the system ASP or a basic user ASP. |
| *N | The ASP name could not be determined at this time. |
Object auxiliary storage pool number. The number of the auxiliary storage pool (ASP) in which the open file resides. Possible values are:
| 1 | System ASP |
| 2-32 | Basic user ASPs |
| 33-255 | Independent ASPs |
Offset to list of open files. The offset in bytes from the beginning of the receiver variable to the first open file entry.
Open option. The type of open operation that is performed:
| 0 | The file was opened for input operations only. |
| 1 | The file was opened for output operations only. |
| 2 | The file was opened for all operations (input, output, update, and delete). |
Other I/O count. Number of successful I/O operations of the following types:
- update
- delete
- change end-of-data
- force end-of-data
- force end-of-volume
- release record lock
- acquire or release program device
Read count. Number of successful read operations. If record blocking is not in effect for the file, this is the number of records. If record blocking is in effect for the file, this is the number of record blocks.
Record format. The name of the last record format that was used for an I/O operation to the file. If no record format name was used or no I/O operations have been performed, this field is blank.
Relative record number. Relative record number of the last record referred to by an I/O or open operation for database files. Zero is returned for nondatabase files and database files on which no I/O operations have been performed.
Reserved. An ignored field.
Thread identifier. An 8-byte thread handle assigned by the system. It identifies the thread in which the file was opened.
Thread identifier used. The identifier of the thread for which open files were listed. A value of zero indicates open files were returned for all threads within the job.
Write count. The number of successful write operations. If record blocking is not in effect for the file, this is the number of records. If record blocking is in effect for the file, this is the number of record blocks.
Write/Read count. The number of successful write/read operations.
Format JIDF0100
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(16) | Internal job identifier |
| 42 | 2A | CHAR(2) | Reserved |
| 44 | 2C | BINARY(4) | Thread indicator |
| 48 | 30 | CHAR(8) | Thread identifier |
Field Descriptions
Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with the job name.
Job name. A specific job name or one of the following special values.
| * | The job in which this program is running. The job number and user name must contain blanks. |
| *INT | The internal job identifier locates the job. The job number and user name must contain blanks. |
Job number. A specific job number, or blanks when the job name specified is a special value.
Reserved. An unused field. This field must contain hexadecimal zeros.
Thread identifier. The unique value used to identify the thread within the job. If the thread indicator is not 0, this field must contain hexadecimal zeroes.
Thread indicator. The value that is used to specify the thread within the job for which information is to be retrieved. The following values are supported:
| 0 | The value in the thread identifier field should be used to locate the thread. |
| 1 | Information should be retrieved for the thread in which this program is running. The combination of the internal job identifier, job name, job number, and user name fields also must identify the job containing the current thread. |
| 2 | Information should be retrieved for the initial thread of the identified job. |
| 3 | Information should be retrieved for all threads within the specified job. |
User name. A specific user profile name, or blanks when the job name specified is a special value.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF136A E | Job not active. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C3B E | Value for parameter not valid. |
| CPF3C51 E | Internal job identifier not valid. |
| CPF3C52 E | Internal job identifier no longer valid. |
| CPF3C53 E | Job &3/&2/&1 not found. |
| CPF3C55 E | Job does not exist. |
| CPF3C57 E | Not authorized to retrieve job information. |
| CPF3C58 E | Job name specified is not valid. |
| CPF3C59 E | Internal identifier is not blanks and job name is not *INT. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPF9999 E | Function check. |
API introduced: V5R1