Open Database File Exit Program

The Open Database File exit program is called when a job is opening a database file. This exit is called in the job that is attempting to open the file. The exit program is passed a list of files referenced in the open request and the open options. The exit program may set a return code value to end the open request. When an open request is issued, the operating system calls the user-written exit program through the registration facility. For information about adding an exit program to an exit point, see the Registration Facility APIs.

If the file being opened is a logical file or a query, multiple files may be passed to the exit program. The originally requested files will be passed in as well as any underlying physical files. Only full opens will call the exit program. Hence,

• If the file is being opened as the result of an SQL statement, pseudo opens will not call the exit program.
• Shared opens will not call the exit program.

The Open Database File Exit Program can only be used with database objects. An open of a DDM file will not call the exit program on the source system, but it will call the exit program on the target system.

Authorities and Locks

User Profile Authority

*ALLOBJ and *SECADM to add or remove exit programs to the registration facility

Required Parameter Group

Open Database File Input Information

INPUT;CHAR(*)

Information needed by the exit program for the database files involved in the open. For the format of this parameter, see DBOP0100 Format.

Open Database File Output Information

OUTPUT;BINARY(4)

Return code. The return code to indicate whether the open should be canceled. The valid values are:

0

The open should be rejected. Any remaining exit programs will not be called.

1

The open request should be accepted. The next exit program will be called or the open request will continue if there are no other exit programs. This is the default action.

DBOP0100 Format

The following tables show the format of the input information parameter for the exit program. For detailed descriptions of the fields in the table, see Field Descriptions.

The following structure shows the format of each array element of the Referenced File Array:

Field Descriptions

Current user name. The current user profile opening the database file.

Database file library name. The database file library name that is referenced in the open request.

Database file member name. The database file member name that is referenced in the open request. When processing partition tables the member will be returned as *ALL.

Database file name. A database file name that is referenced in the open request. This is always the 10-character system name.

Database file type. The type of the database file.

0

Physical database file.

1

Logical database file.

Database open delete option. The delete option specified for the file on the open request.

0

The file is not being opened for delete operations.

1

The file is being opened for delete operations.

Database open input option. The input option specified for the file on the open request.

0

The file is not being opened for input (read) operations.

1

The file is being opened for input (read) operations.

Database open output option. The output option specified for the file on the open request.

0

The file is not being opened for output (insert) operations.

1

The file is being opened for output (insert) operations.

Database open underlying physical file. The physical file underlying a logical file or view that was referenced in the open request.

0

The file was referenced in the open request directly or indirectly through an alias.

1

The file is an underlying physical file of a logical file or view that was referenced in the open request. This file was not directly referenced in the open request.

Database open update option. The update option specified for the file on the open request.

0

The file is not being opened for update operations.

1

The file is being opened for update operations.

Database query open. The interface used to run the database query against the files.

0

The file is not being opened for a database query.

1

The file is being queried by interactive SQL, STRSQL.

2

The file is being queried by other SQL interfaces.

3

The file is being queried by Query (QQQQRY) API.

4

The file is being queried by Open Query File command,OPNQRYF.

5

The file is being queried by other non-SQL query interfaces.

6

The file is being queried by the database host server.

7

The file is being queried by SQL Call Level Interface,CLI.

8

The file is being queried by Process Extended Dynamic SQL (QSQPRCED) API.

Format name. The name of the format being used.

Job name. The name of the job issuing the open request.

Job number. The number of the job issuing the open request.

Length of referenced file array element. The length of each element in the referenced file array.

Number of files in the referenced file array. The number of elements in the referenced file array.

Offset to the referenced file array. Indicates the offset from the start of the Open Database File Input Information to an array of files referenced in the open request.

Reserved. A reserved field.

Size of fixed header for DBOP0100. Size of header information.

User name. The user name under which the job that is issuing the open request is started.

Usage Notes

• If an exit program is being used for security reasons, it may want to ignore any referenced file array elements with a database open underlying physical file value of 1 since the user did not directly reference the underlying physical file. For example, the user may have authority to directly access the logical file, but not the underlying physical file.
• Exit program(s) will be called for user open file requests.
• If an exit program fails for any reason (not found, not authorized, function check in the program) the messages will be left in the joblog, but processing will continue.
• Exit program(s) will not be called for temporary files created by the system during query processing.
• Exit program(s) will not be called for files in the following system libraries (where 'xxxxx' is the number of a primary auxiliary storage pool (ASP) and 'nnnn' is the number of a basic user ASP.):
  • QTEMP
  • QSYS or QSYSxxxxx
  • QSYS2 or QSYS2xxxxx
  • SYSIBM or SYSIBxxxxx
  • QRCL or QRCYxxxxx
  • QRECOVERY or QRCYxxxxx
  • QRPLOBJ or QRPLxxxxx
  • QSPL or QSPLnnnn
• If an open request is issued for an MQT (Materialized Query Table), the MQT will be returned, not the files used to create it.
• In the case of multi-dataspace logical files, each underlying file will be returned.
• Exit program(s) registered for this exit point must be threadsafe and compiled with ACTGRP(*CALLER) because the exit program may be called as the result of an open file operation from an SQL External function. SQL external functions do not allow ACTGRP(*NEW).
• Exit program(s) will run in the job that issues the open request.
• Exit program(s) registered after a job has started may not be called for that existing job.
• Exit program(s) removed after a job has started may continue to be called for that existing job.
• Exit program(s) must be defined in the system ASP.
• When an exit program performs a file open or an SQL function, the open exit program will be called recursively. The exit program doing these operations must be coded to avoid recursion loops.
• Exit program data can be specified to control whether the exit program is called for a specific file. Three exit program data values are supported that are used in conjunction with the object audit attribute:
  • If the exit program data length = 7 and the exit program data = '*OBJAUD', the exit program will be called only if at least one of the files referenced in the open have an object audit value of:
    • *CHANGE
    • *ALL
    • *USRPRF and user's object auditing value for job is *CHANGE or *ALL (See the OBJAUD keyword on the CHGUSRAUD command)
  • If the exit program data length = 12 and the exit program data = 'OBJAUD(*ALL)', the exit program will be called only if at least one of the files referenced in the open have an object audit value of:
    • *ALL
    • *USRPRF and user's object auditing value for job is *ALL (See the OBJAUD keyword on the CHGUSRAUD command)
  • If the exit program data length = 15 and the exit program data = 'OBJAUD(*CHANGE)', the exit program will be called only if at least one of the files referenced in the open have an object audit value of:
    • *CHANGE
    • *USRPRF and user's object auditing value for job is *CHANGE (See the OBJAUD keyword on the CHGUSRAUD command)
      

Note that auditing does not actually have to be active for this to apply.

The open exit will be called for all the files referenced in the open.
For example, physical file T1 has an object audit attribute of *NONE and physical file T2 has an object audit attribute of *CHANGE. *OBJAUD was specified in the exit program data. An open of T1 will not call the exit. An open of T2 will call the exit. A join query that includes both T1 and T2, will call the open exit for both T1 and T2, not just T2.

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