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.
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.
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 (1). The correct coding is shown at (2).
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()
{
/***********************************************************/
/* 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); (1)
/***********************************************************/
/* 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);
}
The following program specifies that blanks be used as the values for both the member and record format parameters. This coding is shown at (2) in the example program. By using blanks, the storage or address location of those parameters is identified and passed when needed.
/**************************************************************/
/* */
/*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); (2)
/***********************************************************/
/* 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);
}