375 lines
20 KiB
HTML
375 lines
20 KiB
HTML
|
<?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>
|