Using the error code parameter
The error code parameter provides a way for you to determine whether an API encounters any errors. Here are the program examples that show the incorrect and correct ways of using the error code parameter.
The examples in this topic present a program that is used for creating a user space.
Incorrect program example: Using the error code parameter
The common error shown in this 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 (1) in the incorrect and also at location (2) in the correct coding.
Both the incorrect (3) and correct coding (4) 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.
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 (5).
*****************************************************************
*
*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 (3)
*
* 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 (1)
C PARM QUSBN
** Program does not check the error code parameter (5)
**
C SETON LR
Correct program example: Using the error code parameter
You can add code to help you discover what errors might be in a program. In the following example program, code has been added to monitor error information that is passed back in the error code parameter (QUSBN). The code at (6) 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 (5).
*****************************************************************
*
*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 (4)
*
* 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 (2)
C PARM QUSBN
**
* DISPLAY EXCEPTION IDENTIFIER TO THE USER
C QUSBNC IFGT *ZEROS (6)
C EXSR DSPERR
C END
*
C SETON LR
*
C DSPERR BEGSR
C DSPLY QUSBND
C ENDSR