friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apiref_5.4.0.1/cmnRetrieveRPG.htm

474 lines
25 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="security" content="public" />
<meta name="Robots" content="index,follow" />
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
<meta name="DC.Type" content="reference" />
<meta name="DC.Title" content="Example in OPM RPG: Retrieving the HOLD parameter (error code structure)" />
<meta name="abstract" content="This sample program shows exceptions being returned in the error code parameter." />
<meta name="description" content="This sample program shows exceptions being returned in the error code parameter." />
<meta name="DC.Relation" scheme="URI" content="opmScenario.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnHoldRPG.htm" />
<meta name="DC.Relation" scheme="URI" content="../apis/qwdrjobd.htm" />
<meta name="DC.Relation" scheme="URI" content="data.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnHoldRPG.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnRetrieveCOBOL.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnRetrieveILEC.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnRetrieveILERPG.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnRetrieveCOBOL.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnRetrieveILEC.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnRetrieveILERPG.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnAccessRPG.htm" />
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
<meta name="DC.Format" content="XHTML" />
<meta name="DC.Identifier" content="cmnRetrieveRPG" />
<meta name="DC.Language" content="en-us" />
<!-- 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. -->
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
<link rel="stylesheet" type="text/css" href="./ic.css" />
<title>Example in OPM RPG: Retrieving the HOLD parameter (error code structure)</title>
</head>
<body id="cmnRetrieveRPG"><a name="cmnRetrieveRPG"><!-- --></a>
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<h1 class="topictitle1">Example in OPM RPG: Retrieving the HOLD parameter (error code structure)</h1>
<div><p>This sample program shows exceptions being returned
in the error code parameter.</p>
<div class="section"><div class="note"><span class="notetitle">Note:</span> Read the <a href="codedisclaimer.htm">Code license and disclaimer information</a> for important
legal information.</div>
<p>In the Example in OPM RPG: Retrieving the HOLD
parameter (exception message), QUSBNB was set to a value of binary zero to
tell the API to send exceptions (escape messages) for any error conditions.
The example in this topic uses an error-code data structure as an alternative
to receiving exceptions.</p>
<p>Some languages do not support the use of exceptions,
so you may prefer to code for errors using error code structures.</p>
<p>In
your programs, you can use error code structures in the following ways:</p>
<ul><li>Define an 8-byte error code structure that provides feedback on whether
an error occurred. If an error does occur, you are not able to determine the
specifics of the problem.</li>
<li>Define a 16-byte error code structure that allows you to determine if
an error exists and to access the exception message ID. The exception message
IDs are the same as shown in Error messages.</li>
<li>Define a larger than 16-byte error code structure that provides the same
information as described in the previous two error code structures as well
as some or all of the exception data. The exception data is the message data
that is sent with the exception message. Because the vast majority of exception
messages do not have more than 512 bytes of message data, a 600-byte error
code structure would be adequate for almost all cases.</li>
</ul>
<div class="note"><span class="notetitle">Note:</span> Lengths of 1 through 7 bytes are not valid for the error code structure.</div>
</div>
<div class="section" id="cmnRetrieveRPG__HDRFORMEC"><a name="cmnRetrieveRPG__HDRFORMEC"><!-- --></a><h4 class="sectiontitle">Format of an error code structure</h4><p>The
format of the error code structure (QUSBN) is:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"><thead align="left"><tr><th colspan="2" valign="top" id="d0e62">Offset</th>
<th rowspan="2" valign="top" id="d0e64">Use</th>
<th rowspan="2" valign="top" id="d0e66">Type</th>
<th rowspan="2" valign="top" id="d0e68">Field</th>
</tr>
<tr><th valign="top" id="d0e71">Dec</th>
<th valign="top" id="d0e73">Hex</th>
</tr>
</thead>
<tbody><tr><td valign="top" headers="d0e62 d0e71 ">0</td>
<td valign="top" headers="d0e62 d0e73 ">0</td>
<td valign="top" headers="d0e64 ">INPUT</td>
<td valign="top" headers="d0e66 ">BINARY(4)</td>
<td valign="top" headers="d0e68 ">Bytes provided</td>
</tr>
<tr><td valign="top" headers="d0e62 d0e71 ">4</td>
<td valign="top" headers="d0e62 d0e73 ">4</td>
<td valign="top" headers="d0e64 ">OUTPUT</td>
<td valign="top" headers="d0e66 ">BINARY(4)</td>
<td valign="top" headers="d0e68 ">Bytes available</td>
</tr>
<tr><td valign="top" headers="d0e62 d0e71 ">8</td>
<td valign="top" headers="d0e62 d0e73 ">8</td>
<td valign="top" headers="d0e64 ">OUTPUT</td>
<td valign="top" headers="d0e66 ">CHAR(7)</td>
<td valign="top" headers="d0e68 ">Exception ID</td>
</tr>
<tr><td valign="top" headers="d0e62 d0e71 ">15</td>
<td valign="top" headers="d0e62 d0e73 ">F</td>
<td valign="top" headers="d0e64 ">OUTPUT</td>
<td valign="top" headers="d0e66 ">CHAR(1)</td>
<td valign="top" headers="d0e68 ">Reserved</td>
</tr>
<tr><td valign="top" headers="d0e62 d0e71 ">16</td>
<td valign="top" headers="d0e62 d0e73 ">10</td>
<td valign="top" headers="d0e64 ">OUTPUT</td>
<td valign="top" headers="d0e66 ">CHAR(*)</td>
<td valign="top" headers="d0e68 ">Exception data</td>
</tr>
</tbody>
</table>
</div>
<p>The error code structure can be found in the QSYSINC library in
the member QUSEC, as shown at <a href="#cmnRetrieveRPG__SPTELEVEN">(1)</a>.
Which of the files you use depends on the language. For more information on
the QSYSINC library, see Include files and the QSYSINC Library.</p>
<p>The
bytes provided field describes the size of the error code structure that you
declared in your program and how you want errors returned. (This was set to
0 as shown by <span class="uicontrol">(6)</span> in Example in OPM RPG: Retrieving
the HOLD parameter (exception message).)</p>
<p>The bytes available field describes
how many bytes the API could have passed back. If this field is zero, no exception
occurred. The correct method for testing if an error occurred when using a
nonzero-bytes-provided value is to check this field for a value greater than
zero, as shown at <a href="#cmnRetrieveRPG__SPTTEN">(2)</a>.</p>
<p>The
exception ID is the normal 7-character message ID, such as CPF9801, that occurs
for an object-not-found condition. Do not test this field to determine if
an error exists. The field is properly set by the system only if the number
of bytes available is greater than 0. Similarly, the exception data (message
data) information is not set properly unless an error exists; for example,
any information left from a prior call is not changed.</p>
<p>The following
program is the same as the previous program except that a 16-byte error code
structure is used:</p>
<pre> I*****************************************************************
I*****************************************************************
I*
I*Program Name: JOBDAPI
I*
I*Language: OPM RPG
I*
I*Descriptive Name: Get Job Description
I*
I*Description: This sample program shows exceptions being
I* returned in the error code parameter.
I*
I*Header Files Included: QUSEC - Error Code Parameter
I* QWDRJOBD - Retrieve Job Description API
I*
I*****************************************************************
I*****************************************************************
I*
I* Error Code Parameter Include for the APIs
I*
I/COPY QSYSINC/QRPGSRC,QUSEC <span class="uicontrol" id="cmnRetrieveRPG__SPTELEVEN"><a name="cmnRetrieveRPG__SPTELEVEN"><!-- --></a>(1)</span>
I*
I* Retrieve Job Description API Include
I*
I/COPY QSYSINC/QRPGSRC,QWDRJOBD
I*
I* Command String Data Structure
I*
ICMDSTR DS
I I 'SNDMSG MSG(''HOLD - 1 26 CMD1
I 'value is '
I 27 36 HOLD
I I ''') TOUSR(QPGMR)' 37 51 CMD2
I*
IMSG2 DS
I I 'SNDMSG MSG(''Progr- 1 43 MSG2A
I 'am failed with mes-
I 'sage ID '
I 44 50 MSGIDD
I I ''') TOUSR(QPGMR)' 51 65 MSG2B
I*
I* Miscellaneous Data Structure
I*
I DS
I I 390 B 1 40RCVLEN
I I 'JOBD0100' 5 12 FORMAT
C*
C* Beginning of Mainline
C*
C* Two parameters are being passed into this program.
C*
C *ENTRY PLIST
C PARM JOBD 10
C PARM JOBDL 10
C*
C* Move the two parameters passed into the LFNAM.
C*
C JOBD CAT JOBDL LFNAM 20
C*
C* Error code parameter is set to 16
C*
C Z-ADD16 QUSBNB <span class="uicontrol" id="cmnRetrieveRPG__SPTTWELVE"><a name="cmnRetrieveRPG__SPTTWELVE"><!-- --></a>(3)</span>
C*
C* Instead of specifying 'QWCRJOBD', I could have used the
C* constant QWDBGB that was defined in the QWDRJOBD include.
C*
C CALL 'QWDRJOBD'
C PARM QWDBH Receiver Var.
C PARM RCVLEN Length RCVVAR
C PARM FORMAT Format Name
C PARM LFNAM Qual. Job Desc
C PARM QUSBN Error Code
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C*
C*
C N01 MOVELQWDBHN HOLD
C*
C* Let's tell everyone what the hold value was for this job.
C*
C N01 Z-ADD51 LENSTR 155
C N01 CALL 'QCMDEXC'
C PARM CMDSTR
C PARM LENSTR
C*
C SETON LR
C RETRN
C*
C* End of MAINLINE
C*
C*
C* Subroutine to handle errors returned in the error code
C* parameter.
C*
C ERRCOD BEGSR
C QUSBNC IFGT 0 <span class="uicontrol" id="cmnRetrieveRPG__SPTTEN"><a name="cmnRetrieveRPG__SPTTEN"><!-- --></a>(2)</span>
C*
C* Process errors returned from the API.
C*
C SETON 01
C Z-ADD65 LENSTR 155
C MOVELQUSBND MSGIDD
C CALL 'QCMDEXC'
C PARM MSG2
C PARM LENSTR
C END
C ENDSR
</pre>
<p>The QUSBN error-code data structure is defined in the include
file QUSEC, as shown at <a href="#cmnRetrieveRPG__SPTELEVEN">(1)</a>,
and the program initializes the bytes provided field (QUSBNB) with a value
of 16, as shown at <a href="#cmnRetrieveRPG__SPTTWELVE">(3)</a>. This
sets the first field of the error code structure to tell the API not to send
an exception but to use the first 16 bytes of the QUSBN parameter to return
the error information. After the CALL to the API, the program accesses the
bytes available (QUSBNC), as shown at <a href="#cmnRetrieveRPG__SPTTEN">(2)</a>.
This contains the number of bytes of information about the error condition.
The program is coded so that it tests if the number exceeds zero. This is
the correct method of determining whether an error has occurred.</p>
<p>If
an error occurred, you may want to handle the error in many different methods.
The program shown extracts the specific error message ID that occurred and
sends the 7-character value as a message. The QUSBN parameter is used for
both input and output (see <a href="#cmnRetrieveRPG__HDRFORMEC">Format of
an error code structure</a>). The first 4 bytes are input to the API to
tell it how to handle exceptions. The remaining bytes are output from the
API about any exception conditions.</p>
<p>To see the value of the HOLD attribute,
use the following call statement to run the program against the QBATCH job
description in library QGPL:</p>
<pre>CALL JOBDAPI (QBATCH QGPL)</pre>
<p>You
should see that the value of the HOLD attribute is *NO:</p>
<pre>+--------------------------------------------------------------------------------+
| |
| |
| Display Messages |
| |
| |
| System: GENSYS90 |
| Queue . . . . . : QPGMR Program . . . . : *DSPMSG |
| Library . . . : QUSRSYS Library . . . : |
| Severity . . . : 00 Delivery . . . : *HOLD |
| Type reply (if required), press Enter. |
| From . . . : SMITH 07/23/94 10:25:14 |
| HOLD value is *NO |
| |
+--------------------------------------------------------------------------------+</pre>
</div>
<div class="section"><h4 class="sectiontitle">Example in OPM RPG: Handling error conditions</h4><p>For
this error condition, you should assume that the XYZ job description does
not exist. Use the following call statement to run the error condition:</p>
<pre>CALL JOBDAPI (XYZ *LIBL)</pre>
<p>You
should see that the CPF9801 message (Object not found) was issued:</p>
<pre>+--------------------------------------------------------------------------------+
| |
| |
| Display Messages |
| |
| System: GENSYS90 |
| Queue . . . . . : QPGMR Program . . . . : *DSPMSG |
| Library . . . : QUSRSYS Library . . . : |
| Severity . . . : 00 Delivery . . . : *HOLD |
| Type reply (if required), press Enter. |
| From . . . : SMITH 07/23/94 10:56:13 |
| Program failed with message ID CPF9801 |
| |
| |
+--------------------------------------------------------------------------------+</pre>
<p>Then run another error condition. For this error condition,
you should assume that the XYZ library does not exist. Use the following call
statement:</p>
<pre>CALL JOBDAPI (QPGMR XYZ)</pre>
<p>The output
is similar to the following:</p>
<pre>+--------------------------------------------------------------------------------+
| |
| |
| Display Messages |
| |
| System: GENSYS90 |
| Queue . . . . . : QPGMR Program . . . . : *DSPMSG |
| Library . . . : QUSRSYS Library . . . : |
| Severity . . . : 00 Delivery . . . : *HOLD |
| Type reply (if required), press Enter. |
| From . . . : SMITH 07/23/94 10:56:13 |
| Program failed with message ID CPF9810 |
| |
+--------------------------------------------------------------------------------+</pre>
<p>You should see that the CPF9810 message (Library not found)
was issued. An advantage of the error return variable is that it can contain
other information such as message data. The following are the changes needed
to return a 200-byte error code structure:</p>
<pre> I*****************************************************************
I*****************************************************************
I*
I*Program Name: JOBDAPI
I*
I*Language: OPM RPG
I*
I*Descriptive Name: Get Job Description
I*
I*Description: This sample program shows the incorrect
I* way of using the offset in a user space in RPG.
I*
I*Header Files Included: QUSEC - Error Code Parameter
I* (Copied into Program)
I* QWDRJOBD - Retrieve Job Description API
I*
I*****************************************************************
I* Error Code Parameter Include for the APIs
I*
I* The following QUSEC include is copied into this program
I* so that the variable-length field can be defined as
I* fixed length.
I*
I*** START HEADER FILE SPECIFICATIONS ****************************
I*
I*Header File Name: H/QUSEC
I*
I*Descriptive Name: Error Code Parameter.
I*
I*5763-SS1 (C) Copyright IBM Corp. 1994,1994
I*All rights reserved.
I*US Government Users Restricted Rights -
I*Use, duplication or disclosure restricted
I*by GSA ADP Schedule Contract with IBM Corp.
I*
I*Licensed Materials-Property of IBM
I*
I*
I*Description: Include header file for the error code parameter.
I*
I*Header Files Included: None.
I*
I*Macros List: None.
I*
I*Structure List: Qus_EC_t
I*
I*Function Prototype List: None.
I*
I*Change Activity:
I*
I*CFD List:
I*
I*FLAG REASON LEVEL DATE PGMR CHANGE DESCRIPTION
I*---- ------------ ----- ------ --------- ----------------------
I*$A0= D2862000 3D10 931201 DPOHLSON: New Include
I*
I*End CFD List.
I*
I*Additional notes about the Change Activity
I*End Change Activity.
I*** END HEADER FILE SPECIFICATIONS ******************************
I*****************************************************************
I*Record structure for Error Code Parameter
I**** ***
I*NOTE: The following type definition defines only the fixed
I* portion of the format. Varying-length field exception
I* data is not defined here.
I*****************************************************************
IQUSBN DS
I* Qus EC
I B 1 40QUSBNB
I* Bytes Provided
I B 5 80QUSBNC
I* Bytes Available
I 9 15 QUSBND
I* Exception Id
I 16 16 QUSBNF
I* Reserved
I* 17 17 QUSBNG
I*
I* Varying length
I 17 200 QUSBNG <span class="uicontrol" id="cmnRetrieveRPG__sixteen"><a name="cmnRetrieveRPG__sixteen"><!-- --></a>(4)</span>
.
.
.
C Z-ADD200 QUSBNB
C*
C CALL 'QWDRJOBD'
C PARM QWDBH Receiver Var.
C PARM RCVLEN Length RCVVAR
C PARM FORMAT Format Name
C PARM LFNAM Qual. Job Desc
C PARM QUSBN Error Code
</pre>
<p>The value placed in the QUSBNG variable <a href="#cmnRetrieveRPG__sixteen">(4)</a> is
the message data associated with the message ID that is identified as the
exception. The message data follows the same format as if you had entered
a Receive Message (RCVMSG) command and requested the message data (MSGDTA)
parameter. You can use the Display Message Description (DSPMSGD) command to
determine the layout of the message data for a particular message ID. When
you handle exceptions, the only information provided is the exception ID and
the message data associated with the exception. You cannot receive a diagnostic
message (if one were sent in addition to the escape message) in the error-code
data structure. You can use the message handling APIs to receive messages
from your program message queue and to access the other messages that may
be issued from the API.</p>
<p>When you instruct the API to return all errors
in the error-code data structure, the escape message does not appear in the
job log. The escape message not appearing in the job log is one of the major
differences between letting the API return errors in an error-code data structure
and letting the API send escape messages. For the error-code data structure,
the escape messages have been removed from the job log by the API. If a diagnostic
message is sent first, the diagnostic message exists in the job log and can
be received.</p>
<p>See the following for the same example in different languages:</p>
<ul><li>COBOL and ILE COBOL</li>
<li>ILE C</li>
<li>ILE RPG</li>
</ul>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="opmScenario.htm" title="This scenario demonstrates the use of an original program model (OPM) API in several different programs.">Scenario: Original Program Model (OPM) API</a></div>
</div>
<div class="relconcepts"><strong>Related concepts</strong><br />
<div><a href="data.htm" title="APIs support character data and binary data.">Data types</a></div>
</div>
<div class="relref"><strong>Related reference</strong><br />
<div><a href="cmnHoldRPG.htm" title="This example expects errors to be sent as escape messages.">Example in OPM RPG: Retrieving the HOLD parameter (exception message)</a></div>
<div><a href="../apis/qwdrjobd.htm">Error messages</a></div>
<div><a href="cmnRetrieveCOBOL.htm" title="This example shows how to make use of an error returned in the error code structure.">Example in ILE COBOL: Retrieving the HOLD parameter (error code structure)</a></div>
<div><a href="cmnRetrieveILEC.htm" title="This example shows how to make use of an error returned in the error code structure.">Example in ILE C: Retrieving the HOLD parameter (error code structure)</a></div>
<div><a href="cmnRetrieveILERPG.htm" title="This program retrieves the HOLD value from a job description. It expects errors to be returned via the error code parameter.">Example in ILE RPG: Retrieving the HOLD parameter (error code structure)</a></div>
<div><a href="cmnAccessRPG.htm" title="The following program prints out the name of the job description or prints an error if the API could not find the job description name specified.">Example in OPM RPG: Accessing the HOLD attribute</a></div>
</div>
</div>
</body>
</html>
Reference in New Issue Copy Permalink