friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
0332907f0f
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/xopendbf.htm

580 lines
17 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Open Database File Exit Program</title>
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Begin Header Records --><!-- Created by Mark Anderson for V5R3 -->
<!-- Change history: -->
<!-- 050922 CSA V5R4 updates, 3602.6 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!--Java sync-link-->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Open Database File Exit Program</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Open Database File Input
Information</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">2</td>
<td align="left" valign="top" width="50%">Return Code</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Exit Point Name: QIBM_QDB_OPEN<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Format Name: DBOP0100<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;QSYSINC Member Name: EDBOPNDB<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>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 <a href="reg1.htm">
Registration Facility APIs</a>.</p>
<p>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,</p>
<ul>
<li>If the file is being opened as the result of an SQL statement, pseudo opens
will not call the exit program.</li>
<li>Shared opens will not call the exit program.</li>
</ul>
<p> 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.</p>
<p>Authorities and Locks</p>
<dl>
<dt><em> User Profile Authority</em></dt>
<dd>*ALLOBJ and *SECADM to add or remove exit programs to the registration
facility<br>
<br>
</dd>
</dl>
<h3>Required Parameter Group</h3>
<dl>
<dt><b>Open Database File Input Information</b></dt>
<dd>INPUT;CHAR(*)<br>
<p>Information needed by the exit program for the database files involved in
the open. For the format of this parameter, see <a href="#SQLR0100">DBOP0100
Format</a>.</p>
<br>
</dd>
</dl>
<dl>
<dt><b>Open Database File Output Information</b></dt>
<dd>OUTPUT;BINARY(4)<br>
<br>
</dd>
</dl>
<p><strong>Return code. The return code to indicate whether the open should be
canceled. The valid values are:</strong></p>
<dl>
<dt><em>0</em></dt>
<dd>The open should be rejected. Any remaining exit programs will not be
called.</dd>
<dt><em>1</em></dt>
<dd>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.</dd>
</dl>
<br>
<h3><a name="SQLR0100">DBOP0100 Format</a></h3>
<p>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 <a
href="#FieldDESCR">Field Descriptions</a>.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Size of fixed header for DBOP0100</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Format name</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to the referenced file array</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of files in the referenced file array</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of the referenced file array
element</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Job name</td>
</tr>
<tr>
<td align="center" valign="top">34</td>
<td align="center" valign="top">22</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">User name</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">
<img src="delta.gif" alt="Start of change">CHAR(6)
<img src="deltaend.gif" alt="End of change"></td>
<td align="left" valign="top">Job number</td>
</tr>
<tr>
<td align="center" valign="top">
<img src="delta.gif" alt="Start of change">50</td>
<td align="center" valign="top">32
<img src="deltaend.gif" alt="End of change"></td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Current user name</td>
</tr>
<tr>
<td align="center" valign="top">
<img src="delta.gif" alt="Start of change">60</td>
<td align="center" valign="top">3C</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Database query open</td>
</tr>
<tr>
<td align="center" valign="top">61</td>
<td align="center" valign="top">3D
<img src="deltaend.gif" alt="End of change"></td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<p>The following structure shows the format of each array element of the
Referenced File Array:</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Database file name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Database file library name</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Database file member name</td>
</tr>
<tr>
<td align="center" valign="top">30</td>
<td align="center" valign="top">1E</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Database file type</td>
</tr>
<tr>
<td align="center" valign="top">36</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Database open underlying physical file</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Database open input option</td>
</tr>
<tr>
<td align="center" valign="top">41</td>
<td align="center" valign="top">29</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Database open output option</td>
</tr>
<tr>
<td align="center" valign="top">42</td>
<td align="center" valign="top">2A</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Database open update option</td>
</tr>
<tr>
<td align="center" valign="top">43</td>
<td align="center" valign="top">2B</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Database open delete option</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="FieldDESCR">Field Descriptions</a></h3>
<p><strong>Current user name.</strong> The current user profile opening the
database file.</p>
<p><strong>Database file library name.</strong> The database file library name
that is referenced in the open request.</p>
<p><strong>Database file member name.</strong> The database file member name
that is referenced in the open request. When processing partition tables the
member will be returned as *ALL.</p>
<p><strong>Database file name.</strong> A database file name that is referenced
in the open request. This is always the 10-character system name.</p>
<p><strong>Database file type.</strong> The type of the database file.</p>
<dl>
<dt><em>0</em></dt>
<dd>Physical database file.</dd>
<dt><em>1</em></dt>
<dd>Logical database file.</dd>
</dl>
<p><strong>Database open delete option.</strong> The delete option specified
for the file on the open request.</p>
<dl>
<dt><em>0</em></dt>
<dd>The file is not being opened for delete operations.</dd>
<dt><em>1</em></dt>
<dd>The file is being opened for delete operations.</dd>
</dl>
<p><strong>Database open input option.</strong> The input option specified for
the file on the open request.</p>
<dl>
<dt><em>0</em></dt>
<dd>The file is not being opened for input (read) operations.</dd>
<dt><em>1</em></dt>
<dd>The file is being opened for input (read) operations.</dd>
</dl>
<p><strong>Database open output option.</strong> The output option specified
for the file on the open request.</p>
<dl>
<dt><em>0</em></dt>
<dd>The file is not being opened for output (insert) operations.</dd>
<dt><em>1</em></dt>
<dd>The file is being opened for output (insert) operations.</dd>
</dl>
<p><strong>Database open underlying physical file.</strong> The physical file
underlying a logical file or view that was referenced in the open request.</p>
<dl>
<dt><em>0</em></dt>
<dd>The file was referenced in the open request directly or indirectly through
an alias.</dd>
<dt><em>1</em></dt>
<dd>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.</dd>
</dl>
<p><strong>Database open update option.</strong> The update option specified
for the file on the open request.</p>
<dl>
<dt><em>0</em></dt>
<dd>The file is not being opened for update operations.</dd>
<dt><em>1</em></dt>
<dd>The file is being opened for update operations.</dd>
</dl>
<p><img src="delta.gif" alt="Start of change"><strong>Database query open.
</strong> The interface used to run the database query against the files.</p>
<dl>
<dt><em>0</em></dt>
<dd>The file is not being opened for a database query.</dd>
<dt><em>1</em></dt>
<dd>The file is being queried by interactive SQL, STRSQL.</dd>
<dt><em>2</em></dt>
<dd>The file is being queried by other SQL interfaces.</dd>
<dt><em>3</em></dt>
<dd>The file is being queried by Query (QQQQRY) API.</dd>
<dt><em>4</em></dt>
<dd>The file is being queried by Open Query File command,OPNQRYF.</dd>
<dt><em>5</em></dt>
<dd>The file is being queried by other non-SQL query interfaces.</dd>
<dt><em>6</em></dt>
<dd>The file is being queried by the database host server.</dd>
<dt><em>7</em></dt>
<dd>The file is being queried by SQL Call Level Interface,CLI.</dd>
<dt><em>8</em></dt>
<dd>The file is being queried by Process Extended Dynamic SQL (QSQPRCED) API.
<img src="deltaend.gif" alt="End of change"></dd>
</dl>
<p><strong>Format name.</strong> The name of the format being used.</p>
<p><strong>Job name.</strong> The name of the job issuing the open request.</p>
<p><strong>Job number.</strong> The number of the job issuing the open
request.</p>
<p><strong>Length of referenced file array element.</strong> The length of each
element in the referenced file array.</p>
<p><strong>Number of files in the referenced file array.</strong> The number of
elements in the referenced file array.</p>
<p><strong>Offset to the referenced file array.</strong> Indicates the offset
from the start of the Open Database File Input Information to an array of files
referenced in the open request.</p>
<dl compact>
<dt><strong>Reserved.</strong> A reserved field.</dt>
</dl>
<p><strong>Size of fixed header for DBOP0100.</strong> Size of header
information.</p>
<p><strong>User name.</strong> The user name under which the job that is issuing
the open request is started.</p>
<br>
<h3><a name="Usage_Notes">Usage Notes</a></h3>
<ul>
<li>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.</li>
<li>Exit program(s) will be called for user open file requests.</li>
<li>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.</li>
<li>Exit program(s) will not be called for temporary files created by the system
during query processing.</li>
<li><img src="delta.gif" alt="Start of change">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.):
<ul>
<li>QTEMP</li>
<li>QSYS or QSYSxxxxx</li>
<li>QSYS2 or QSYS2xxxxx</li>
<li>SYSIBM or SYSIBxxxxx</li>
<li>QRCL or QRCYxxxxx</li>
<li>QRECOVERY or QRCYxxxxx</li>
<li>QRPLOBJ or QRPLxxxxx</li>
<li>QSPL or QSPLnnnn <img src="deltaend.gif" alt="End of change"></li>
</ul>
<li>If an open request is issued for an MQT (Materialized Query Table), the MQT
will be returned, not the files used to create it.</li>
<li>In the case of multi-dataspace logical files, each underlying file will be
returned.</li>
<li><img src="delta.gif" alt="Start of change">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).
<img src="deltaend.gif" alt="End of change"></li>
<li>Exit program(s) will run in the job that issues the open request.</li>
<li>Exit program(s) registered after a job has started may not be called for that
existing job.</li>
<li><img src="delta.gif" alt="Start of change">Exit program(s) removed after a
job has started may continue to be called for that existing job.
<img src="deltaend.gif" alt="End of change"></li>
<li>Exit program(s) must be defined in the system ASP.</li>
<li><img src="delta.gif" alt="Start of change">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.
<img src="deltaend.gif" alt="End of change"></li>
</ul>
<hr>
Exit program introduced: V5R3
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"file1.htm">Database and File APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink