325 lines
9.2 KiB
HTML
325 lines
9.2 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>Send Scope Message (QMHSNDSM) API</title>
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- 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. -->
|
||
|
|
<!-- MH1TEMP SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
||
|
|
<!-- RCHVMW2 on 26 Jan 1999 at 10:37:34 -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!--File Edited Oct 2001 by v2cdijab -->
|
||
|
|
<!--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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>Send Scope Message (QMHSNDSM) API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
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%">Scope type</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Char(10)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">Qualified scope program name</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(20)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">Scope program data</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">Scope program data length</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">5</td>
|
||
|
|
<td align="left" valign="top">Message key</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">Char(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">6</td>
|
||
|
|
<td align="left" valign="top">Error code</td>
|
||
|
|
<td align="left" valign="top">I/O</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Send Scope Message (QMHSNDSM) API sends a scope message to a call stack
|
||
|
|
entry.</p>
|
||
|
|
|
||
|
|
<p>Scope messages are a way to call a program when the call stack entry that
|
||
|
|
called the QMHSNDSM API ends or when the job using this API ends. The exit can
|
||
|
|
be normal or abnormal. The three scope types, *EXT, *PGM, and *CSE, indicate
|
||
|
|
when the scope handling program should be called. To have the scope handling
|
||
|
|
program run at job or routing step ending, specify *EXT for the scope type parameter. The
|
||
|
|
difference between program scoping (*PGM) and call stack entry (*CSE) scoping
|
||
|
|
is how they handle a transfer control. When a transfer control occurs, the
|
||
|
|
scope handling program is called for scope type *PGM because the program or ILE
|
||
|
|
procedure ended, but the scope handling program is not called for scope type
|
||
|
|
*CSE because the call stack is still active.</p>
|
||
|
|
|
||
|
|
<p>When a scope message is sent in a multithreaded job with a scope type of
|
||
|
|
*PGM or *CSE, the scope handling program runs in the thread that used the
|
||
|
|
QMHSNDSM API to send the scope message. When a multithreaded job uses a scope
|
||
|
|
type of *EXT, the scope handling program runs in the initial thread when the
|
||
|
|
job or routing step ends.</p>
|
||
|
|
|
||
|
|
<p>You must also specify a scope-handling program to be run when the job,
|
||
|
|
program or call stack entry exits. You must have at least *EXECUTE authority to
|
||
|
|
the scope-handling program library and at least *USE authority to the program.
|
||
|
|
If the user has below the minimum authorization, the scope message is sent but
|
||
|
|
an authorization violation is signaled when the scope-handling program is
|
||
|
|
called and it is not run. Any adopted authority the sending program may have
|
||
|
|
does not affect the user's authority to the scope-handling program. The
|
||
|
|
scope-handling program runs in the same state as the sender of the scope
|
||
|
|
message.</p>
|
||
|
|
|
||
|
|
<p>This API returns the message key which can be used to end scoping by
|
||
|
|
deleting the message.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>Scope program</em></dt>
|
||
|
|
|
||
|
|
<dd>*USE</dd>
|
||
|
|
|
||
|
|
<dt><em>Scope program library</em></dt>
|
||
|
|
|
||
|
|
<dd>*EXECUTE</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Scope type</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(10)
|
||
|
|
|
||
|
|
<p>The type of scoping to be done. Valid values are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="10 90" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*EXT</em></td>
|
||
|
|
<td align="left" valign="top">Scope handling program is called when the
|
||
|
|
caller's job or routing step ends.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*PGM</em></td>
|
||
|
|
<td align="left" valign="top">The scope-handling program is called when the
|
||
|
|
caller's program ends or a transfer control is issued.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*CSE</em></td>
|
||
|
|
<td align="left" valign="top">The scope handling program is called only when
|
||
|
|
the call stack entry ends. A transfer control does <strong>not</strong> cause
|
||
|
|
the scope handling program to be called.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Qualified scope program name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(20)
|
||
|
|
|
||
|
|
<p>The name of the scope handling program and the library in which it resides.
|
||
|
|
The first ten characters represent the program name, the second ten characters
|
||
|
|
the library name.</p>
|
||
|
|
|
||
|
|
<p>The library can have these special values:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*LIBL</em></td>
|
||
|
|
<td align="left" valign="top">The library list is used to find the scope
|
||
|
|
handling program</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*CURLIB</em></td>
|
||
|
|
<td align="left" valign="top">The current library is used to find the scope
|
||
|
|
handling program</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Scope program data</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>Data that is passed to the scope handling program as its one and only
|
||
|
|
parameter.</p>
|
||
|
|
|
||
|
|
<p>The user is responsible for the format of this data. Any pointers contained
|
||
|
|
in the data must begin on a 16-byte boundary.</p>
|
||
|
|
|
||
|
|
<p>This data is copied to another area in storage when the scope message is
|
||
|
|
sent. When the scope program is called, a space pointer pointing to the copied
|
||
|
|
data is passed to the scope handling program.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Scope program data length</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length, in bytes, of the scope program data. The valid range is 0
|
||
|
|
through 32 767. If a data length of zero is specified, a null pointer is passed
|
||
|
|
to the scope handling program.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Message key</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; CHAR(4)
|
||
|
|
|
||
|
|
<p>The key to the scope message being sent.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Error code</strong></dt>
|
||
|
|
|
||
|
|
<dd>I/O; CHAR(*)
|
||
|
|
|
||
|
|
<p>The structure in which to return error information. For the format of the
|
||
|
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="15%">CPF24B4 E</td>
|
||
|
|
<td align="left" valign="top" width="85%">Severe error while addressing
|
||
|
|
parameter list.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF2401 E</td>
|
||
|
|
<td align="left" valign="top">Not authorized to library &1.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3CF1 E</td>
|
||
|
|
<td align="left" valign="top">Error code parameter not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C1D E</td>
|
||
|
|
<td align="left" valign="top">Length specified in parameter &1 not
|
||
|
|
valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C90 E</td>
|
||
|
|
<td align="left" valign="top">Literal value cannot be changed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9801 E</td>
|
||
|
|
<td align="left" valign="top">Object &2 in library &3 not found.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9805 E</td>
|
||
|
|
<td align="left" valign="top">Object &2 in library &3 destroyed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9810 E</td>
|
||
|
|
<td align="left" valign="top">Library &1 not found.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9830 E</td>
|
||
|
|
<td align="left" valign="top">Cannot assign library &1.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
|
<td align="left" valign="top">Program or service program &1 in library
|
||
|
|
&2 ended. Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V2R1
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"mh1.htm">Message Handling APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|