Sometimes an API may issue one or more messages that state that the API failed, and the messages may direct you to see the previously listed messages in the job log. If your application program needs to determine the cause of the error message, you can use the Receive Message (RCVMSG) command or the Receive Message APIs to receive the messages that explain the reason for the error.
In some cases, you can write an application program to use the diagnostic message to identify and correct the parameter values that caused the error.
To receive error messages from the job log using a CL program, specify the following:
/* */
/*********************************************************************/
/* */
/* PROGRAM: CLRCVMSG */
/* */
/* LANGUAGE: CL */
/* */
/* DESCRIPTION: THIS PROGRAM DEMONSTRATES HOW TO RECEIVE */
/* DIAGNOSTIC MESSAGES FROM THE JOB LOG */
/* */
/* APIs USED: QUSCRTUS */
/* */
/*********************************************************************/
/* */
CLRCVMSG: PGM
DCL VAR(&MSGDATA) TYPE(*CHAR) LEN(80)
DCL VAR(&MSGID) TYPE(*CHAR) LEN(7)
DCL VAR(&MSGLEN) TYPE(*DEC) LEN(5 0)
MONMSG MSGID(CPF3C01) EXEC(GOTO CMDLBL(GETDIAGS))
CALL PGM(QUSCRTUS) PARM('!BADNAME !BADLIB ' +
'!BADEXATTR' -1 '@' '*BADAUTH ' 'Text +
Description')
/* IF WE MAKE IT HERE, THE SPACE WAS CREATED OK */
GOTO CMDLBL(ALLDONE)
/* IF THIS PART OF THE PROGRAM RECEIVES CONTROL, A CPF3C01 */
/* WAS RECEIVED INDICATING THAT THE SPACE WAS NOT CREATED. */
/* THERE WILL BE ONE OR MORE DIAGNOSTICS THAT WE WILL RECEIVE */
/* TO DETERMINE WHAT WENT WRONG. FOR THIS EXAMPLE WE WILL */
/* JUST USE SNDPGMMSG TO SEND THE ID'S OF THE MESSAGES */
/* RECEIVED. */
GETDIAGS: RCVMSG PGMQ(*SAME) MSGQ(*PGMQ) MSGTYPE(*DIAG) +
WAIT(3) RMV(*NO) MSGDTA(&MSGDATA) +
MSGDTALEN(&MSGLEN) MSGID(&MSGID)
IF COND(&MSGID = ' ') THEN(GOTO +
CMDLBL(ALLDONE))
ELSE CMD(DO)
SNDPGMMSG MSG(&MSGID)
GOTO CMDLBL(GETDIAGS)
ENDDO
ALLDONE: ENDPGM
As an alternative to using the job log, the following RPG program uses the error code structure to receive error messages:
H****************************************************************
H* *
H* MODULE: ERRCODE *
H* *
H* LANGUAGE: RPG *
H* *
H* FUNCTION: THIS APPLICATION DEMONSTRATES THE USE OF THE *
H* ERROR CODE PARAMETER. *
H* *
H* APIs USED: QHFRTVAT, QHFCRTDR *
H* *
H****************************************************************
H****************************************************************
H* *
H* THIS PROGRAM DOES SOME SIMPLE VERIFICATION ON AN HFS *
H* DIRECTORY. THE QHFRTVAT API IS USED TO VERIFY THEEXISTENCE *
H* OF THE SPECIFIED DIRECTORY. IF THE DIRECTORY DOES NOT EXIST,*
H* AN ATTEMPT IS MADE TO CREATE THE DIRECTORY. *
H* *
H* THERE ARE THREE PARAMETERS TO THIS PROGRAM *
H* *
H* 1 INPUT PATHNM - NAME OF DIRECTORY *
H* 2 INPUT PATHLN - LENGTH OF PATHNM PARAMETER *
H* 3 OUTPUT SUCCES - INDICATES SUCCESS OR FAILURE *
H* '0' SUCCESS *
H* '1' FAILURE *
H****************************************************************
ISUCCES DS
I B 1 40RETCOD
IPLENG DS
I B 1 40PATHLN
IBINS DS
I B 1 40RETDTA
I B 5 80ATTRLN
IERROR DS
I B 1 40BYTPRV
I B 5 80BYTAVA
I 9 15 ERRID
I 16 16 ERR###
I 17 272 INSDTA
C *ENTRY PLIST
C PARM PATHNM 80
C PARM PLENG
C PARM SUCCES
C*
C* INITIALIZE BYTES PROVIDED AND THE ATTRIBUTE LENGTH VARIABLE
C*
C Z-ADD272 BYTPRV
C Z-ADD0 ATTRLN
C*
C* RETRIEVE DIRECTORY ENTRY ATTRIBUTES
C*
C CALL 'QHFRTVAT'
C PARM PATHNM
C PARM PATHLN
C PARM ATTR 1
C PARM ATTRLN
C PARM ATTR
C PARM ATTRLN
C PARM RETDTA
C PARM ERROR
C*
C* CHECK FOR DIRECTORY NOT FOUND OR FILE NOT FOUND ERRORS.
C* IF WE RECEIVE ONE OF THESE THIS IS THE INDICATION THAT
C* WE CAN TRY TO CREATE THE DIRECTORY.
C*
C BYTAVA IFEQ *ZERO
C Z-ADD0 RETCOD
C ELSE
C 'CPF1F02' IFEQ ERRID
C 'CPF1F22' OREQ ERRID
C**************************************************************
C* THERE IS NO NEED TO REINITIALIZE THE ERROR CODE PARAMETER.
C* ONLY BYTES PROVIDED IS INPUT TO THE API; IT WILL RESET THE
C* ERROR CODE PARAMETER FOR US. AFTER THE CALL TO QHFCRTDR,
C* BYTES AVAILABLE WILL EITHER BE 0 IF SUCCESSFUL OR NONZERO
C* IF THE CREATE FAILS. WE DO NOT HAVE TO WORRY ABOUT THE
C* PREVIOUS ERROR CODE BEING left IN THE ERROR CODE PARAMETER.
C**************************************************************
C CALL 'QHFCRTDR'
C PARM PATHNM
C PARM 20 PATHLN
C PARM ATTR 1
C PARM 0 ATTRLN
C PARM ERROR
C BYTAVA IFEQ *ZERO
C Z-ADD0 RETCOD
C ELSE
C Z-ADD1 RETCOD
C END
C*
C ELSE
C Z-ADD1 RETCOD
C END
C END
C*
C* PROGRAM END
C*
C SETON LR