ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/XDLTRCV.htm

692 lines
20 KiB
HTML

<!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>Delete Journal Receiver 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 ========================================== -->
<!-- JC1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!--Edited by Kersten Oct 2001 -->
<!-- This file has undergone html cleanup June 2002 by JET -->
<!--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>Delete Journal Receiver 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%">Delete journal receiver exit
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">2</td>
<td align="left" valign="top">Status information</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;QSYSINC Member Name: EDLTRCV1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Name: QIBM_QJO_DLT_JRNRCV<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Format Names: DRCV0100<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Delete Journal Receiver exit program is called when a journal receiver
is to be deleted on the server.</p>
<p>When a journal receiver is to be deleted on the server, the operating system
calls the user-written exit programs through the registration facility. The
exit programs will be called before the journal receiver is actually deleted
and can indicate whether the exit program considers the receiver eligible for
deletion.</p>
<p>The exit point supports an unlimited number of exit programs. For
information about adding an exit program to an exit point, see the Registration
Facility.</p>
<p><strong>Note:</strong> If the Delete Journal Receiver exit program returns
any error messages, the journal receiver will not be considered eligible for
deletion.</p>
<br>
<h3>Restrictions</h3>
<ul>
<li>When a user specifies DLTRCV(*YES) as an attribute of a journal, the system
will attempt to delete the journal receiver when the system sees it is no
longer required for recovery purposes. Before the journal receiver is deleted,
the system will call all of the exit programs registered for the
QIBM_QJO_DLT_JRNRCV exit point. If any of the exit programs give an indication
that the journal receiver is not eligible for deletion, then the journal
receiver will not be deleted. Instead, the system will retry the deletion in
the time specified for the DLTRCVDLY value for the journal. These system
deletion attempts take place in system jobs, during an IPL and during the vary
on of an independent ASP; therefore, the exit program will be allowed to run
for only 5 minutes when called during either of these conditions. If the exit
program has not completed in that time, the system cancels the call, and the
journal receiver will not be considered eligible for deletion.<br>
<p><strong>Note:</strong> Since these attempts do occur in system jobs, we
recommend that the exit program not send any diagnostic, informational, or
completion messages to the job log because those messages would only be in the
system job logs.</p>
</li>
<li>If the delete journal receiver is called as part of process end, the exit
program can run for only 5 minutes. If it exceeds 5 minutes, the call is
canceled, and the journal receiver is not eligible for deletion.<br>
</li>
<li>During the call to the exit programs, the debug functions, accessed via
Start Debug (STRDBG), are not available to help debug any exit program
problems.<br>
</li>
<li>During the call to the exit programs the ASP group associated with the job
will not be able to be changed. The ASP group associated with the job will be
the ASP group associated with the journal receiver to be deleted.<br>
</li>
<li>The exit programs must exist in the system Auxiliary Storage Pool (ASP) or
in a basic user ASP. It cannot exist in an independent ASP. Any ASP group could
be associated with the job when the exit program is called. If the exit program
is not found, the journal receiver will not be considered eligible for
deletion.</li>
</ul>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><strong>User Profile Authority</strong></dt>
<dd>*ALLOBJ and *SECADM to add exit programs to the registration facility</dd>
<dd>*ALLOBJ and *SECADM to remove exit programs from the registration
facility</dd>
</dl>
<br>
<h3>Program Data</h3>
<p>When you register the exit program, the following program data can be
optionally provided. This program data specifies the user profile under which
the exit program being registered will run. If the program data is not
provided, the exit programs will run under the QUSER user profile.</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%">User profile</td>
</tr>
</table>
<br>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt>Delete journal receiver exit information</dt>
<dd>INPUT; CHAR(*)
<p>Information that is needed by the exit program for notification of any
journal receiver deletions. For details, see <a href="#HDRDLTFMT1">Format of
Delete Journal Receiver Exit Information</a>.</p>
</dd>
<dt>Status information</dt>
<dd>OUTPUT; CHAR(*)
<p>Information that is returned by the exit program stating whether the
deletion can occur or not. For details, see <a href="#HDRDLTFMT2">Format of
Status Information</a>.</p>
</dd>
</dl>
<br>
<h3><a name="HDRDLTFMT1">Format of Delete Journal Receiver Exit
Information</a></h3>
<p>The following table shows the structure of the delete journal receiver exit
information for exit point format DRCV0100. For a description of the fields in
this format, see <a href="#HDRDRCVI">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%">Delete journal receiver exit information
length</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Exit point name</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Exit point format name</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Journal receiver name</td>
</tr>
<tr>
<td align="center" valign="top">42</td>
<td align="center" valign="top">2A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Journal receiver library name</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Journal name</td>
</tr>
<tr>
<td align="center" valign="top">62</td>
<td align="center" valign="top">3E</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Journal library name</td>
</tr>
<tr>
<td align="center" valign="top">72</td>
<td align="center" valign="top">48</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Called by system job</td>
</tr>
<tr>
<td align="center" valign="top">73</td>
<td align="center" valign="top">49</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Called during IPL or vary on of an independent
ASP.</td>
</tr>
<tr>
<td align="center" valign="top">74</td>
<td align="center" valign="top">4A</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Called during process end</td>
</tr>
<tr>
<td align="center" valign="top">75</td>
<td align="center" valign="top">4B</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Journal type</td>
</tr>
<tr>
<td align="center" valign="top">76</td>
<td align="center" valign="top">4C</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Remote journal type</td>
</tr>
<tr>
<td align="center" valign="top">77</td>
<td align="center" valign="top">4D</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Save status</td>
</tr>
<tr>
<td align="center" valign="top">78</td>
<td align="center" valign="top">4E</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Partial status</td>
</tr>
<tr>
<td align="center" valign="top">79</td>
<td align="center" valign="top">4F</td>
<td align="left" valign="top">CHAR(13)</td>
<td align="left" valign="top">Detached date and time</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRDLTFMT2">Format of Status Information</a></h3>
<p>The following table shows the structure of the status information. For a
description of the fields in this format, see <a href="#HDRDRCVI">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%">Delete status information length</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Delete status</td>
</tr>
</table>
<br>
<h3><a name="HDRDRCVI">Field Descriptions</a></h3>
<p><strong>Called by system job.</strong> Whether this call was from a user job
or a system job. The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The call is from a user job.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">The call is from a system job, and is therefore limited to 5
minutes.</td>
</tr>
</table>
<p><strong>Called during IPL or vary on of an independent ASP.</strong> Whether
this call was during an IPL or during the vary on of an independent ASP. The
possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The call is not during an IPL or vary on of an independent
ASP.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">The call is during an IPL or vary on of an independent ASP,
and is therefore limited to 5 minutes.</td>
</tr>
</table>
<p><strong>Called during process end.</strong> Whether this call was during
process end. The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The call is not during process end.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">The call is during process end.</td>
</tr>
</table>
<p><strong>Delete journal receiver exit information length.</strong> The length
in bytes of all data passed to the delete journal receiver exit program.</p>
<p><strong>Delete status.</strong> The status value that indicates whether the
exit program considers the journal receiver eligible for deletion. The possible
values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The journal receiver is not eligible for deletion. Therefore,
the delete journal receiver command will be ended, and the receiver will not be
deleted.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">The journal receiver is eligible for deletion.</td>
</tr>
</table>
<p><strong>Note:</strong> If any other value is specified for this item, it
will be ignored, and the journal receiver will <strong>not</strong> be eligible
for deletion.</p>
<p><strong>Delete status information length.</strong> The length in bytes of
all data returned from the Delete Journal Receiver exit program. The only valid
value for this field is 5. If anything else is entered, the receiver is not
considered eligible for deletion.</p>
<p><strong>Detached date and time.</strong> The date and time that this journal
receiver was detached from the journal. For a journal receiver that was
attached to a *REMOTE journal, this is the date and time that the journal
receiver was detached on the local system. This field is in the CYYMMDDHHMMSS
format as follows:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>C</em></td>
<td valign="top">Century, where 0 indicates years 19<em>xx</em> and 1 indicates
years 20<em>xx</em>.</td>
</tr>
<tr>
<td valign="top"><em>YYYY</em></td>
<td valign="top">Year</td>
</tr>
<tr>
<td valign="top"><em>MM</em></td>
<td valign="top">Month</td>
</tr>
<tr>
<td valign="top"><em>DD</em></td>
<td valign="top">Day</td>
</tr>
<tr>
<td valign="top"><em>HH</em></td>
<td valign="top">Hours</td>
</tr>
<tr>
<td valign="top"><em>MM</em></td>
<td valign="top">Minutes</td>
</tr>
<tr>
<td valign="top"><em>SS</em></td>
<td valign="top">Seconds</td>
</tr>
</table>
<p>If the journal receiver was never attached to a journal, this field will be
blank. If the journal receiver was never detached from a journal, or if this
journal receiver is a partial receiver, this field will be all zeros.</p>
<p><strong>Exit point format name.</strong> The format name for the delete
journal receiver exit program. The possible format name follows:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>DRCV0100</em></td>
<td valign="top">The format name that is used before a user journal receiver is
to be deleted.</td>
</tr>
</table>
<p><strong>Exit point name.</strong> The name of the exit point that is calling
the exit program.</p>
<p><strong>Journal library name.</strong> The library name of the journal that
is associated with the journal receiver library being deleted. If there is no
journal associated with this journal receiver, this field will be blank.</p>
<p><strong>Journal name.</strong> The name of the journal that is associated
with the journal receiver being deleted. If there is no journal associated with
this journal receiver, this field will be blank.</p>
<p><strong>Journal receiver library name.</strong> The name of the journal
receiver library being deleted.</p>
<p><strong>Journal receiver name.</strong> The name of the journal receiver
being deleted.</p>
<p><strong>Journal type.</strong> An indication of whether the journal
currently associated with the journal receiver being deleted is local or
remote. The possible values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>blank</em></td>
<td valign="top">The journal receiver has not yet been attached to any journal
or the receiver is not currently associated with any journal.</td>
</tr>
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">*LOCAL</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">*REMOTE</td>
</tr>
</table>
<p><strong>Partial status.</strong> An indication of whether the journal
receiver is a partial receiver. A journal receiver is partial for one of the
following reasons:</p>
<ul>
<li>It was restored from a version that was saved while it was attached to the
journal. Additional journal entries may have been written that were not
restored.<br>
<br>
</li>
<li>It was one of a pair of dual journal receivers, and it was found damaged
while attached to the journal. The journal receiver has since been detached.
This journal receiver is considered partial because additional journal entries
may have been written to the dual journal receiver.<br>
<br>
</li>
<li>It is associated with a remote journal and it does not contain all the
journal entries that are in the associated journal receiver attached to the
source journal.</li>
</ul>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The journal receiver is not a partial journal receiver.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">The journal receiver is a partial journal receiver.</td>
</tr>
</table>
<p><strong>Remote journal type.</strong> If this journal receiver was attached
to a remote journal, this field is the remote journal type for that journal,
when this journal receiver was attached. The possible values are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td valign="top"><em>blank</em></td>
<td valign="top">The journal receiver has not yet been attached to any
journal.</td>
</tr>
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The journal receiver was attached to a local journal.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">The journal receiver was attached to a *TYPE1 remote
journal.</td>
</tr>
<tr>
<td valign="top"><em>2</em></td>
<td valign="top">The journal receiver was attached to a *TYPE2 remote
journal.</td>
</tr>
</table>
<p><strong>Save status.</strong> An indication of whether the journal receiver
has been saved after it was detached. The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The journal receiver has not been saved after it was
detached.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">The journal receiver has been saved after it was
detached.</td>
</tr>
</table>
<p><strong>User profile.</strong> The exit program will be called under this
user profile. If the user profile is not valid at the time the exit programs
are called, the QUSER user profile will be used.</p>
<br>
<h3>IPL Processing Guidelines</h3>
<p>The following operations may be performed during the IPL. If any other
actions take place, the Delete Journal Receiver exit program may not run
successfully or the results will be unpredictable.</p>
<ul>
<li>Working with physical files, including creating, changing, opening,
closing, clearing, and deleting<br>
<br>
</li>
<li>Database input and output operations<br>
<br>
</li>
<li>Working with data areas, including creating, changing, retrieving, and
deleting<br>
<br>
</li>
<li>Working with data queues, including creating and deleting<br>
<br>
</li>
<li>Working with message queues, including creating, clearing, changing, and
deleting</li>
</ul>
<p>Some examples of things your exit program might not be able to do during IPL
are:</p>
<ul>
<li>Signal any inquiry messages</li>
<li>Submit any other jobs</li>
<li>Use or attempt to start any remote communications activities</li>
<li>Start any subsystems</li>
</ul>
<br>
<hr>
API introduced: V4R2
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#top_Of_Page">top</a> | <a href=
"jc1.htm">Journal and Commit APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>