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.
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.
Offset
Type
Field
Dec
Hex
0
0
BINARY(4)
Size of fixed header for DBOP0100
4
4
CHAR(8)
Format name
12
C
BINARY(4)
Offset to the referenced file array
16
10
BINARY(4)
Number of files in the referenced file array
20
14
BINARY(4)
Length of the referenced file array
element
24
18
CHAR(10)
Job name
34
22
CHAR(10)
Current user name
44
2C
CHAR(6)
Job number
50
32
CHAR(10)
User name
60
3C
CHAR(1)
Database query open
61
3D
CHAR(*)
Reserved
The following structure shows the format of each array element of the
Referenced File Array:
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.
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.
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:
