167 lines
8.7 KiB
HTML
167 lines
8.7 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="Use the error code parameter" />
|
||
|
|
<meta name="abstract" content="The examples in this topic present a program used for creating a user space." />
|
||
|
|
<meta name="description" content="The examples in this topic present a program used for creating a user space." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="pgmerr.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="pgmerr_errorco" />
|
||
|
|
<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>Use the error code parameter</title>
|
||
|
|
</head>
|
||
|
|
<body id="pgmerr_errorco"><a name="pgmerr_errorco"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Use the error code parameter</h1>
|
||
|
|
<div><p>The examples in this topic present a program used for creating
|
||
|
|
a user space.</p>
|
||
|
|
<div class="section"><p>The error code parameter provides a way for you to
|
||
|
|
determine whether the API encountered any errors.</p>
|
||
|
|
<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>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="pgmerr_errorco__error_correct"><a name="pgmerr_errorco__error_correct"><!-- --></a><h4 class="sectiontitle">Example of incorrect coding: Use the error
|
||
|
|
code parameter</h4><p>The common error shown in the following example is
|
||
|
|
the use of the error code structure to indicate to the API not to send exception
|
||
|
|
messages for errors found. Additionally, the example does not examine the
|
||
|
|
error code structure to determine if the API call was successful or not. To
|
||
|
|
demonstrate the improper use of the error code structure, an incorrect value
|
||
|
|
is used on the replace parameter of the QUSCRTUS API. The replace parameter
|
||
|
|
is a required parameter. The coded error (*XXXXXXX) is shown at location <a href="#pgmerr_errorco__SPTRK2A">(1)</a> in the incorrect and also at location <a href="#pgmerr_errorco__SPTRK2B">(2)</a> in the correct coding.</p>
|
||
|
|
<p>Both
|
||
|
|
the incorrect <a href="#pgmerr_errorco__SPTRK1A">(3)</a> and correct
|
||
|
|
coding <a href="#pgmerr_errorco__SPTRK1B">(4)</a> show the program monitoring
|
||
|
|
for any error from the call to the API. However, the program does not examine
|
||
|
|
the bytes available field after calling the QUSCRTUS API.</p>
|
||
|
|
<p>Because of
|
||
|
|
the error on the replace parameter, the requested user space is not created.
|
||
|
|
The calling program, however, is not aware of this as shown at <a href="#pgmerr_errorco__SPTRK3A">(5)</a>.</p>
|
||
|
|
<pre> *****************************************************************
|
||
|
|
*
|
||
|
|
*Program Name: PGM1
|
||
|
|
*
|
||
|
|
*Program Language: RPG
|
||
|
|
*
|
||
|
|
*Description: This sample program illustrates the incorrect
|
||
|
|
* way of using the error code parameter.
|
||
|
|
*
|
||
|
|
*Header Files Included: QUSEC - Error Code Parameter
|
||
|
|
*
|
||
|
|
*APIs Used: QUSCRTUS - Create User Space
|
||
|
|
*
|
||
|
|
*****************************************************************
|
||
|
|
* BRING IN THE ERROR STRUCTURE FROM QSYSINC
|
||
|
|
I/COPY QSYSINC/QRPGSRC,QUSEC
|
||
|
|
**
|
||
|
|
ISPCNAM DS
|
||
|
|
I I 'SPCNAME ' 1 10 SPC
|
||
|
|
I I 'PAM ' 11 20 LIB
|
||
|
|
** OTHER ASSORTED VARIABLES
|
||
|
|
I DS
|
||
|
|
I I 2000 B 1 40SIZ
|
||
|
|
I B 5 80START
|
||
|
|
I I X'00' 9 9 INTVAL
|
||
|
|
*
|
||
|
|
* Initialize the bytes provided field (QUSBNDB) of the error code
|
||
|
|
* structure. Languages such as RPG and CL tend to initialize the bytes
|
||
|
|
* provided field to blanks, which when passed to an API is viewed as a
|
||
|
|
* very large (and incorrect) binary value. If you receive CPF3CF1 when
|
||
|
|
* calling an API, the bytes provided field should be the first field
|
||
|
|
* you examine as part of problem determination.
|
||
|
|
C Z-ADD16 QUSBNB <span class="uicontrol" id="pgmerr_errorco__SPTRK1A"><a name="pgmerr_errorco__SPTRK1A"><!-- --></a>(3)</span>
|
||
|
|
*
|
||
|
|
* CREATE THE SPACE TO HOLD THE DATA
|
||
|
|
C CALL 'QUSCRTUS'
|
||
|
|
C PARM SPCNAM
|
||
|
|
C PARM 'EXT_ATTR'EXTATR 10
|
||
|
|
C PARM SIZ
|
||
|
|
C PARM INTVAL
|
||
|
|
C PARM '*ALL 'PUBAUT 10
|
||
|
|
C PARM 'NO TEXT 'TXTDSC 50
|
||
|
|
C PARM '*XXXXXXX'REPLAC 10 <span class="uicontrol" id="pgmerr_errorco__SPTRK2A"><a name="pgmerr_errorco__SPTRK2A"><!-- --></a>(1)</span>
|
||
|
|
C PARM QUSBN
|
||
|
|
** Program does not check the error code parameter <span class="uicontrol" id="pgmerr_errorco__SPTRK3A"><a name="pgmerr_errorco__SPTRK3A"><!-- --></a>(5)</span>
|
||
|
|
**
|
||
|
|
C SETON LR
|
||
|
|
</pre>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="pgmerr_errorco__error_incorrect"><a name="pgmerr_errorco__error_incorrect"><!-- --></a><h4 class="sectiontitle">Example: Use the error code parameter
|
||
|
|
of correct coding</h4><p>You can add code to help you discover what errors
|
||
|
|
may be in a program. In the following example program, code has been added
|
||
|
|
to monitor error information passed back in the error code parameter (QUSBN).
|
||
|
|
The code at <a href="#pgmerr_errorco__SPTRK4B">(6)</a> has been added
|
||
|
|
to check the error code parameter for any messages and to display the exception
|
||
|
|
identifier to the user if any errors are found. The incorrectly coded program
|
||
|
|
does no checking for the error code parameter, as shown at <a href="#pgmerr_errorco__SPTRK3A">(5)</a>.</p>
|
||
|
|
<pre> *****************************************************************
|
||
|
|
*
|
||
|
|
*Program Name: PGM2
|
||
|
|
*
|
||
|
|
*Program Language: RPG
|
||
|
|
*
|
||
|
|
*Description: This sample program illustrates the correct
|
||
|
|
* way of using the error code parameter.
|
||
|
|
*
|
||
|
|
*Header Files Included: QUSEC - Error Code Parameter
|
||
|
|
*
|
||
|
|
*APIs Used: QUSCRTUS - Create User Space
|
||
|
|
*
|
||
|
|
*****************************************************************
|
||
|
|
* BRING IN THE ERROR STRUCTURE FROM QSYSINC
|
||
|
|
I/COPY QSYSINC/QRPGSRC,QUSEC
|
||
|
|
**
|
||
|
|
ISPCNAM DS
|
||
|
|
I I 'SPCNAME ' 1 10 SPC
|
||
|
|
I I 'QTEMP ' 11 20 LIB
|
||
|
|
** OTHER ASSORTED VARIABLES
|
||
|
|
I DS
|
||
|
|
I I 2000 B 1 40SIZ
|
||
|
|
I B 5 80START
|
||
|
|
I I X'00' 9 9 INTVAL
|
||
|
|
*
|
||
|
|
C Z-ADD16 QUSBNB <span class="uicontrol" id="pgmerr_errorco__SPTRK1B"><a name="pgmerr_errorco__SPTRK1B"><!-- --></a>(4)</span>
|
||
|
|
*
|
||
|
|
* CREATE THE SPACE TO HOLD THE DATA
|
||
|
|
C CALL 'QUSCRTUS'
|
||
|
|
C PARM SPCNAM
|
||
|
|
C PARM 'EXT_ATTR'EXTATR 10
|
||
|
|
C PARM SIZ
|
||
|
|
C PARM INTVAL
|
||
|
|
C PARM '*ALL 'PUBAUT 10
|
||
|
|
C PARM 'NO TEXT 'TXTDSC 50
|
||
|
|
C PARM '*XXXXXXX'REPLAC 10 <span class="uicontrol" id="pgmerr_errorco__SPTRK2B"><a name="pgmerr_errorco__SPTRK2B"><!-- --></a>(2)</span>
|
||
|
|
C PARM QUSBN
|
||
|
|
**
|
||
|
|
* DISPLAY EXCEPTION IDENTIFIER TO THE USER
|
||
|
|
C QUSBNC IFGT *ZEROS <span class="uicontrol" id="pgmerr_errorco__SPTRK4B"><a name="pgmerr_errorco__SPTRK4B"><!-- --></a>(6)</span>
|
||
|
|
C EXSR DSPERR
|
||
|
|
C END
|
||
|
|
*
|
||
|
|
C SETON LR
|
||
|
|
*
|
||
|
|
C DSPERR BEGSR
|
||
|
|
C DSPLY QUSBND
|
||
|
|
C ENDSR</pre>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="pgmerr.htm" title="Provides information about common programming errors, as well as examples of correct and incorrect coding.">Common API programming errors</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|