Using Null Pointers with OPM APIs
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.
Note: 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.
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 con-
ceptually 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 func-
tion check (MCH3601). Additionally, other error messages may also occur.
Using Null Pointers with OPM APIs—Example of Incorrect Coding
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 .12/ on page 9-19. The correct
coding is shown at .13/ on page 9-21.
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.
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ \/
/\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()
{
9-18 System API Programming V4R1