224 lines
12 KiB
HTML
224 lines
12 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 null pointers with OPM APIs" />
|
|
<meta name="abstract" content="Many programmers, especially those with a C programming background, view ignored parameters and NULL parameters as being the same. This expectation can lead to unexpected results when OPM-based APIs are used." />
|
|
<meta name="description" content="Many programmers, especially those with a C programming background, view ignored parameters and NULL parameters as being the same. This expectation can lead to unexpected results when OPM-based APIs are used." />
|
|
<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_null" />
|
|
<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 null pointers with OPM APIs</title>
|
|
</head>
|
|
<body id="pgmerr_null"><a name="pgmerr_null"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">Use null pointers with OPM APIs</h1>
|
|
<div><p>Many programmers, especially those with a C programming background,
|
|
view ignored parameters and NULL parameters as being the same. This expectation
|
|
can lead to unexpected results when OPM-based APIs are used.</p>
|
|
<div class="section"><div class="note"><span class="notetitle">Note:</span> Using NULL with ignored parameters is primarily a consideration
|
|
with OPM-based APIs. ILE-based APIs allow you to pass NULL parameters to indicate
|
|
omitted parameter values.</div>
|
|
<p>Even though the value assigned to a parameter
|
|
is not used, the parameter itself must be addressable. When you use NULL for
|
|
a parameter value, the system conceptually passes an address that can be equated
|
|
with 0, where 0 indicates that the parameter cannot be addressed. This lack
|
|
of addressability often results in a function check (MCH3601). Additionally,
|
|
other error messages may also occur.</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_null__null_incorrect"><a name="pgmerr_null__null_incorrect"><!-- --></a><h4 class="sectiontitle">Example of incorrect coding: Use null
|
|
pointers with OPM APIs</h4><p>The following program has two parameter values
|
|
coded as NULL. They are the ignored parameters of the member and record format
|
|
used in the List Database Relations (QDBLDBR) API, which is shown at <a href="#pgmerr_null__SPTRK12A">(1)</a>. The correct coding is shown at <a href="#pgmerr_null__SPTRK13B">(2)</a>.</p>
|
|
<p>When the program is called,
|
|
a machine function check of MCH3601 is reported because the address of the
|
|
required parameters member and record format are specified as NULL.</p>
|
|
<pre>/**************************************************************/
|
|
/* */
|
|
/*Program Name: PGM1 */
|
|
/* */
|
|
/*Program Language: ILE C */
|
|
/* */
|
|
/*Description: This sample program illustrates the incorrect */
|
|
/* use of ignored and null parameters. */
|
|
/* */
|
|
/*Header Files Included: <stdio.h> */
|
|
/* <qusec.h> */
|
|
/* <qusgen.h> */
|
|
/* <qdbldbr.h> */
|
|
/* <quscrtus.h> */
|
|
/* <qusptrus.h> */
|
|
/* <qliept.h> */
|
|
/* */
|
|
/*APIs Used: QUSCRTUS - Create User Space */
|
|
/* QDBLDBR - List Database Relations */
|
|
/* QUSPTRUS - Retrieve Pointer to User Space */
|
|
/**************************************************************/
|
|
#include <stdio.h>
|
|
#include <qusec.h>
|
|
#include <qusgen.h>
|
|
#include <qdbldbr.h>
|
|
#include <quscrtus.h>
|
|
#include <qusptrus.h>
|
|
#include <qliept.h>
|
|
main()
|
|
{
|
|
|
|
/***********************************************************/
|
|
/* initialize program data elements */
|
|
/***********************************************************/
|
|
|
|
char initial_value = 0x00;
|
|
char text_description[50] =
|
|
"test of QDBLDBR API ";
|
|
char qualified_usrspc_name[20] = "GETLDBR QTEMP ";
|
|
Qus_EC_t error_code;
|
|
Qus_Generic_Header_0100_t *header_ptr;
|
|
error_code.Bytes_Provided = 0;
|
|
/***********************************************************/
|
|
/* Create the user space to hold API results */
|
|
/***********************************************************/
|
|
|
|
QUSCRTUS(qualified_usrspc_name, "SPACE ", 1,
|
|
&initial_value, "*ALL ", text_description,
|
|
"*YES ", &error_code, "*USER ");
|
|
/***********************************************************/
|
|
/* Get list of file dependencies in current library */
|
|
/* */
|
|
/* Note that in this API call NULL pointers are being */
|
|
/* used for the "ignored" parameters Member and */
|
|
/* Record_Format. This convention is not valid as the */
|
|
/* parameters must address a valid storage address. */
|
|
/* The value */
|
|
/* assigned to a storage location is not important, the */
|
|
/* passing of a valid storage location is. */
|
|
/* */
|
|
/* The next statement will cause a MCH3601 */
|
|
/***********************************************************/
|
|
|
|
QDBLDBR(qualified_usrspc_name, "DBRL0100", "*ALL *CURLIB ",
|
|
NULL, NULL, &error_code); <span class="uicontrol" id="pgmerr_null__SPTRK12A"><a name="pgmerr_null__SPTRK12A"><!-- --></a>(1)</span>
|
|
|
|
|
|
/***********************************************************/
|
|
/* Get pointer to user space which contains dependencies */
|
|
/***********************************************************/
|
|
|
|
QUSPTRUS(qualified_usrspc_name, &header_ptr, &error_code);
|
|
|
|
/***********************************************************/
|
|
/* and display number of entries generated */
|
|
/***********************************************************/
|
|
|
|
printf("The number of entries returned is %d\n",
|
|
header_ptr->Number_List_Entries);
|
|
}</pre>
|
|
</div>
|
|
<div class="section" id="pgmerr_null__null_correct"><a name="pgmerr_null__null_correct"><!-- --></a><h4 class="sectiontitle">Example: Use null pointers with OPM APIs
|
|
of correct coding</h4><p>The following program specifies that blanks be
|
|
used as the values for both the member and record format parameters. This
|
|
coding is shown at <a href="#pgmerr_null__SPTRK13B">(2)</a> in the example
|
|
program. By using blanks, the storage or address location of those parameters
|
|
is identified and passed when needed.</p>
|
|
<pre>/**************************************************************/
|
|
/* */
|
|
/*Program Name: PGM2 */
|
|
/* */
|
|
/*Program Language: ILE C */
|
|
/* */
|
|
/*Description: This sample program illustrates the correct */
|
|
/* use of ignored and null parameters. */
|
|
/* */
|
|
/*Header Files Included: <stdio.h> */
|
|
/* <qusec.h> */
|
|
/* <qusgen.h> */
|
|
/* <qdbldbr.h> */
|
|
/* <quscrtus.h> */
|
|
/* <qusptrus.h> */
|
|
/* <qliept.h> */
|
|
/* */
|
|
/*APIs Used: QUSCRTUS - Create User Space */
|
|
/* QDBLDBR - List Database Relations */
|
|
/* QUSPTRUS - Retrieve Pointer to User Space */
|
|
/**************************************************************/
|
|
#include <stdio.h>
|
|
#include <qusec.h>
|
|
#include <qusgen.h>
|
|
#include <qdbldbr.h>
|
|
#include <quscrtus.h>
|
|
#include <qusptrus.h>
|
|
#include <qliept.h>
|
|
main()
|
|
{
|
|
|
|
/***********************************************************/
|
|
/* initialize program data elements */
|
|
/***********************************************************/
|
|
|
|
char initial_value = 0x00;
|
|
char text_description[50] =
|
|
"test of QDBLDBR API ";
|
|
char qualified_usrspc_name[20] = "GETLDBR QTEMP ";
|
|
Qus_EC_t error_code;
|
|
Qus_Generic_Header_0100_t *header_ptr;
|
|
error_code.Bytes_Provided = 0;
|
|
|
|
/***********************************************************/
|
|
/* Create the user space to hold API results */
|
|
/***********************************************************/
|
|
|
|
QUSCRTUS(qualified_usrspc_name, "SPACE ", 1,
|
|
&initial_value, "*ALL ", text_description,
|
|
"*YES ", &error_code, "*USER ");
|
|
|
|
/***********************************************************/
|
|
/* Get list of file dependencies in current library */
|
|
/* */
|
|
/* Note that in this API call, blank characters are being */
|
|
/* used for the "ignored" parameters Member and */
|
|
/* Record_Format. While the value is ignored, a valid */
|
|
/* parameter storage location must still be passed */
|
|
/***********************************************************/
|
|
|
|
QDBLDBR(qualified_usrspc_name, "DBRL0100", "*ALL *CURLIB ",
|
|
" ", " ", &error_code); <span class="uicontrol" id="pgmerr_null__SPTRK13B"><a name="pgmerr_null__SPTRK13B"><!-- --></a>(2)</span>
|
|
|
|
|
|
/***********************************************************/
|
|
/* Get pointer to user space which contains dependencies */
|
|
/***********************************************************/
|
|
|
|
QUSPTRUS(qualified_usrspc_name, &header_ptr, &error_code);
|
|
|
|
/***********************************************************/
|
|
/* and display number of entries generated */
|
|
/***********************************************************/
|
|
|
|
printf("The number of entries returned is %d\n",
|
|
header_ptr->Number_List_Entries);
|
|
}</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> |