When defining receiver variables, the most common error is to create them too small for the amount of data that they are to receive. Both of these example programs are coded in RPG and, when run, list all active jobs on the system.
The following example program may fail because the receiver variable has been defined as 50 bytes, as shown at (1), but 60 bytes are being requested to be passed back from the API, as shown at (2) in the incorrect program and at (3) in the correct program. The correct coding is shown at (4).
When this happens, other variables are overwritten with unintended data. This causes the other variables to be incorrect. For example, the first 10 characters of QUSBN may be written over with these extra characters. On the call to the next API, the error code parameter may appear to contain meaningless characters that would cause the next call to an API to fail.
***************************************************************** * *Program Name: PGM1 * *Program Language: RPG * *Description: This sample program illustrates the incorrect * way of defining receiver variables. * *Header Files Included: QUSEC - Error Code Parameter * QUSLJOB - List Job API * QUSGEN - User Space Format for Generic Header * *APIs Used: QUSCRTUS - Create User Space * QUSLJOB - List Job * QUSRTVUS - Retrieve User Space * QUSDLTUS - Delete User Space ***************************************************************** * THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL * THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM. * BRING IN THE GENERIC USER SPACE HEADER FROM QSYSINC I/COPY QSYSINC/QRPGSRC,QUSGEN * * BRING IN THE ERROR STRUCTURE FROM QSYSINC I/COPY QSYSINC/QRPGSRC,QUSEC * ** JOBL0100 FORMAT RETURNED FROM QUSLJOB API I/COPY QSYSINC/QRPGSRC,QUSLJOB * ** JOB NAME STRUCTURE FOR CALLING QUSLJOB IJOBNAM DS I I '*ALL ' 1 10 JOB I I '*ALL ' 11 20 USER I I '*ALL' 21 26 JOBNUM 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 B 9 120LENDTA I I X'00' 13 13 INTVAL * * SET UP TO ACCEPT EXCEPTIONS C Z-ADD*ZEROS QUSBNB * * 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 'TEXT DSC'TXTDSC 50 C PARM '*YES 'REPLAC 10 C PARM QUSBN * * CALL THE API TO LIST THE ACTIVE JOBS C CALL 'QUSLJOB' C PARM SPCNAM C PARM 'JOBL0100'FORMAT 8 C PARM JOBNAM C PARM '*ACTIVE 'STAT 10 C PARM QUSBN * * RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE C Z-ADD1 START C Z-ADD140 LENDTA C CALL 'QUSRTVUS' C PARM SPCNAM C PARM START C PARM LENDTA C PARM QUSBP C PARM QUSBN * * RETRIEVE THE LIST ENTRIES C QUSBPQ ADD 1 START * C Z-ADD60 LENDTA (2) * C Z-ADD1 X 90 C X DOWLEQUSBPS C CALL 'QUSRTVUS' C PARM SPCNAM C PARM START C PARM LENDTA C PARM RECVR 50 (1) C PARM QUSBN * C MOVEL RECVR QUSDD * C ADD QUSBPT START C ADD 1 X C END * DELETE THE SPACE THAT HELD THE DATA C CALL 'QUSDLTUS' C PARM SPCNAM C PARM QUSBN * C SETON LR
The following example program defines a larger receiver variable: 60 bytes. This is shown at position (4). This increase in the receiver variable allows up to 60 bytes of data to be received.
***************************************************************** * *Program Name: PGM2 * *Program Language: RPG * *Description: This sample program illustrates the correct * way of defining receiver variables. * *Header Files Included: QUSEC - Error Code Parameter * QUSLJOB - List Job API * QUSGEN - User Space Format for Generic Header * *APIs Used: QUSCRTUS - Create User Space * QUSLJOB - List Job * QUSRTVUS - Retrieve User Space * QUSDLTUS - Delete User Space ***************************************************************** * * BRING IN THE ERROR STRUCTURE FROM QSYSINC I/COPY QSYSINC/QRPGSRC,QUSEC * BRING IN THE GENERIC USER SPACE HEADER FROM QSYSINC I/COPY QSYSINC/QRPGSRC,QUSGEN * ** JOBL0100 FORMAT RETURNED FROM QUSLJOB API I/COPY QSYSINC/QRPGSRC,QUSLJOB * ** JOB NAME STRUCTURE FOR CALLING QUSLJOB IJOBNAM DS I I '*ALL ' 1 10 JOB I I '*ALL ' 11 20 USER I I '*ALL' 21 26 JOBNUM 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 B 9 120LENDTA I I X'00' 13 13 INTVAL * * SET UP TO ACCEPT EXCEPTIONS C Z-ADD*ZEROS QUSBNB * * 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 'TEXT DSC'TXTDSC 50 C PARM '*YES 'REPLAC 10 C PARM QUSBN * * CALL THE API TO LIST THE ACTIVE JOBS C CALL 'QUSLJOB' C PARM SPCNAM C PARM 'JOBL0100'FORMAT 8 C PARM JOBNAM C PARM '*ACTIVE 'STAT 10 C PARM QUSBN * * RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE C Z-ADD1 START C Z-ADD140 LENDTA C CALL 'QUSRTVUS' C PARM SPCNAM C PARM START C PARM LENDTA C PARM QUSBP C PARM QUSBN * * RETRIEVE LIST ENTRIES C QUSBPQ ADD 1 START * C Z-ADD60 LENDTA (3) * C Z-ADD1 X 90 C X DOWLEQUSBPS C CALL 'QUSRTVUS' C PARM SPCNAM C PARM START C PARM LENDTA C PARM RECVR 60 (4) C PARM QUSBN * C MOVELRECVR QUSDD C ADD QUSBPT START C ADD 1 X C END * DELETE THE SPACE THAT HELD THE DATA C CALL 'QUSDLTUS' C PARM SPCNAM C PARM QUSBN * C SETON LR *