ibm-information-center/dist/eclipse/plugins/i5OS.ic.apiref_5.4.0.1/cmnHoldRPG.htm

375 lines
20 KiB
HTML
Raw Normal View History

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 (exception message)" />
<meta name="abstract" content="This example expects errors to be sent as escape messages." />
<meta name="description" content="This example expects errors to be sent as escape messages." />
<meta name="DC.Relation" scheme="URI" content="opmScenario.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnDesc.htm" />
<meta name="DC.Relation" scheme="URI" content="../apis/qwdrjobd.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnHoldCOBOL.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnHoldILEC.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnHoldILERPG.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnHoldCOBOL.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnHoldILEC.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnHoldILERPG.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnRetrieveRPG.htm" />
<meta name="DC.Relation" scheme="URI" content="cmnRetrieveRPG.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="cmnHoldRPG" />
<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 (exception message)</title>
</head>
<body id="cmnHoldRPG"><a name="cmnHoldRPG"><!-- --></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 (exception message)</h1>
<div><p>This example expects errors to be sent as escape messages.</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 following program example, all the pieces
have been put together with an RPG program that accesses the hold on job queue
information from a job description. A message is sent for the value found.
To make the RPG program more general purpose, two parameters for the job description
(JOBD) name and library (JOBDL) name are passed to it, as shown at <a href="#cmnHoldRPG__SPTJOBDAPJ">(5)</a>.
The program example, which is named JOBDAPI (this program name is also used
in other examples in this chapter), does not handle errors. Any errors that
are received are returned as exception messages.</p>
<pre> I*****************************************************************
I*****************************************************************
I*
I*Program Name: JOBDAPI
I*
I*Language: OPM RPG
I*
I*Descriptive Name: Job Description
I*
I*Description: This example expects errors to be sent as escape
I* messages.
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
I*
I* Retrieve Job Description API Include
I*
I/COPY QSYSINC/QRPGSRC,QWDRJOBD <span class="uicontrol" id="cmnHoldRPG__SPTONE"><a name="cmnHoldRPG__SPTONE"><!-- --></a>(1)</span>
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*
I* Miscellaneous Data Structure
I*
I DS
I* <span class="uicontrol" id="cmnHoldRPG__SPTTWO"><a name="cmnHoldRPG__SPTTWO"><!-- --></a>(2)</span>
I I 390 B 1 40RCVLEN
I I 'JOBD0100' 5 12 FORMAT
I* <span class="uicontrol" id="cmnHoldRPG__SPTTHREE"><a name="cmnHoldRPG__SPTTHREE"><!-- --></a>(3)</span>
C*
C* Beginning of Mainline
C*
C* Two parameters are being passed into this program.
C*
C *ENTRY PLIST <span class="uicontrol" id="cmnHoldRPG__SPTJOBDAPJ"><a name="cmnHoldRPG__SPTJOBDAPJ"><!-- --></a>(5)</span>
C PARM JOBD 10
C PARM JOBDL 10
C*
C* Move the two parameters passed into LFNAM.
C*
C JOBD CAT JOBDL LFNAM 20 <span class="uicontrol" id="cmnHoldRPG__NUMBER6"><a name="cmnHoldRPG__NUMBER6"><!-- --></a>(6)</span>
C* Error code bytes provided is set to 0
C*
C Z-ADD0 QUSBNB <span class="uicontrol" id="cmnHoldRPG__SPTFOUR"><a name="cmnHoldRPG__SPTFOUR"><!-- --></a>(4)</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*
C MOVELQWDBHN HOLD
C*
C* Let's tell everyone what the hold value was for this jobd.
C*
C Z-ADD51 LENSTR 155
C CALL 'QCMDEXC'
C PARM CMDSTR
C PARM LENSTR
C*
C SETON LR
C RETRN
C*
C* End of MAINLINE
C*
</pre>
<p>The program declares the variables to be used. The QWDBH variable
is length 390 as shown by <a href="#cmnHoldRPG__SPTTWO"> <span class="uicontrol">(2)</span></a>.</p>
<p>In
the example, the program places a value of JOBD0100 in the format variable.
A literal could have been used instead for those languages that support a
literal on a call, as shown at <a href="#cmnHoldRPG__SPTJOBDAPJ">(5)</a>.
The program generates the qualified name of the job description (JOBD) by
concatenating the simple name and the library qualifier, as shown at <a href="#cmnHoldRPG__NUMBER6">(6)</a>. A 20-character variable must be used,
and the simple name must begin in byte 1 with the library qualifier in byte
11. Because CAT is used, a simple concatenation of two 10-byte variables occurs
so that the names are in the correct place for the LFNAM parameter.</p>
<p>The
QWDRJOBD API is called with the correct parameter list. The API uses the parameter
list and accesses the job description specified. The API extracts the values
from the internal object form and places them in a data structure that matches
the JOBD0100 format. The API then returns with the data structure placed in
variable QWDBH, which is located in member QWDRJOBD in the QSYSINC library.</p>
<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:25:14 |
| HOLD value is *NO |
| |
+--------------------------------------------------------------------------------+</pre>
<p>The API does not need to be called each time that you want
a separate field because all fields are returned that would fit within the
size indicated by the length of receiver variable (RCVLEN) parameter. You
can run the program against the QBATCH job description in library QGPL by
using the following call statement:</p>
<pre>CALL JOBDAPI PARM(QBATCH QGPL)</pre>
<p>If
QGPL is on the library list, you can run the program against the QBATCH job
description by using the following call statement:</p>
<pre>CALL JOBDAPI PARM(QBATCH *LIBL)</pre>
<p>You
can run the program on one of your own job descriptions or on a test job description
where you have specified HOLD(*YES).</p>
</div>
<div class="section"><h4 class="sectiontitle">Example in OPM RPG: Handling error conditions</h4><p>For
this example, assume that the XYZ job description does not exist:</p>
<pre>CALL JOBDAPI PARM(XYZ *LIBL)</pre>
<p>You
probably will receive the inquiry message CPA0701 that states an unmonitored
exception (CPF9801) has occurred and offers several possible replies. At this
point, you would enter C for Cancel and press the Enter key.</p>
<p>If you
displayed the low-level messages, you would see the following: CPF9801 (Object
not found), followed by the inquiry message (CPA0701), followed by your reply.</p>
<p>When
you specify the error code parameter as zero, you are specifying that exceptions
be sent as escape messages. You can code the RPG program so that any errors
on the call set the indicator 01 to on, as shown at <a href="#cmnHoldRPG__SPTSEVEN">(10)</a>.
This causes a different path to be taken in the code.</p>
<p>For RPG, the CALL
operation specifies the error indicator. Based on whether the error indicator
is on or off, a set of instructions can be processed. The API must receive
an error code parameter that consists of a binary 4 field with a value of
binary zeros, as shown at <a href="#cmnHoldRPG__SPTEIGHT">(11)</a>).
The message ID can be accessed from the program-status data structure. You
would define this as follows:</p>
<pre> I* Program status DS (<a href="#cmnHoldRPG__SPTNINE">(12)</a>)
IPGMSTS SDS
I 40 46 MSGIDD</pre>
<p>If you are going to do something about an error condition,
you must test for an error condition in RPG:</p>
<ul><li>If you use the error-code data structure, test the bytes available field.</li>
<li>If you let exceptions occur, test the error indicator on the CALL operation
(<a href="#cmnHoldRPG__SPTSEVEN">(10)</a>).</li>
</ul>
<p>Because you must test for some condition (one of the error messages
in Error Messages), no great difference exists in how you handle error conditions
in RPG. The error-code data structure is a little more straightforward (the
program-status data structure is not used). The only disadvantage of the error-code
data structure is that the escape message that occurred was removed from the
job log.</p>
<p>The following program shows how to code for an error condition,
test for that condition, and send a message to the QPGMR message queue if
the condition occurs:</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 program handles any errors that are
I* returned
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
I*
I* Retrieve Job Description API Include
I*
I/COPY QSYSINC/QRPGSRC,QWDRJOBD
I* Program status DS
IPGMSTS SDS <span class="uicontrol" id="cmnHoldRPG__SPTNINE"><a name="cmnHoldRPG__SPTNINE"><!-- --></a>(12)</span>
I 40 46 MSGIDD
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*
IMSG3 DS
I I 'SNDMSG MSG(''No such- 1 35 MSG3A
I ' *JOBD exists'') '
I I 'TOUSR(QPGMR)' 36 47 MSG3B
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 LFNAM.
C*
C JOBD CAT JOBDL LFNAM 20
C* Error code bytes provided is set to 0
C*
C Z-ADD0 QUSBNB <span class="uicontrol" id="cmnHoldRPG__SPTEIGHT"><a name="cmnHoldRPG__SPTEIGHT"><!-- --></a>(11)</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' 01 <span class="uicontrol" id="cmnHoldRPG__SPTSEVEN"><a name="cmnHoldRPG__SPTSEVEN"><!-- --></a>(10)</span>
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 01 EXSR ERROR Error Subroutine
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* Subroutine to handle errors received on the CALL
C*
C ERROR BEGSR
C MSGIDD IFEQ 'CPF9801'
C*
C* Process errors returned from the API.
C*
C Z-ADD47 LENSTR 155
C CALL 'QCMDEXC'
C PARM MSG3
C PARM LENSTR
C END
C ENDSR
</pre>
<p>If the CPF9801 exception occurs, your program sends a message
to the QPGMR message queue as shown in the following display:</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/25/94 11:10:12 |
| No such *JOBD exists |
| |
+--------------------------------------------------------------------------------+</pre>
<p>If another exception occurs (for example, a library name that
is not valid), you do not receive an indication that an error occurred because
of the way the error subroutine is currently coded.</p>
<p>In addition, you
can use the Message Handling APIs to receive the messages sent to your program
message queue.</p>
<p>The call to the API fails if you specify a valid job
description but use a library qualifier such as *ALLUSR. The value *ALLUSR
is not supported by the description of the required parameter group.</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="cmnDesc.htm" title="For most APIs, the API description information has similar section headings.">API description</a></div>
</div>
<div class="relref"><strong>Related reference</strong><br />
<div><a href="../apis/qwdrjobd.htm">Error Messages</a></div>
<div><a href="cmnHoldCOBOL.htm" title="This example expects errors sent as escape messages.">Example in ILE COBOL: Retrieving the HOLD parameter (exception message)</a></div>
<div><a href="cmnHoldILEC.htm" title="This example expects errors sent as escape messages.">Example in ILE C: Retrieving the HOLD parameter (exception message)</a></div>
<div><a href="cmnHoldILERPG.htm" title="This program retrieves the HOLD value from a job description. It expects errors to be sent as escape messages.">Example in ILE RPG: Retrieving the HOLD parameter (exception message)</a></div>
<div><a href="cmnRetrieveRPG.htm" title="This sample program shows exceptions being returned in the error code parameter.">Example in OPM 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>