A recursive program is one that can call itself either directly or indirectly through a program it has called. Some programming languages, like CL, allow programs to be recursive. However, RPG doesn't allow a program to be recursive. If you try to call an RPG program that's already running within the job's call stack, the system sends error message RPG8888 (program called itself recursively). With RPG III, there is not even a conventional way-e.g., a *PSSR subroutine, an error indicator on the CALL statement, or the Monitor Message (MONMSG) command-to check the recursion level of a program so you can prevent these ugly error messages from occurring.
The Check Stack (CHKSTK) utility will allow your program to either check to see if a recursive call error will occur when it calls another program, or it will actually allow your program to be called recursively. This utility can also be used when your program needs the name of the application program that called it.
There are other ways to simulate recursive calls if you know that this is a requirement ahead of time and design your applications with this in mind. For example, you could use group jobs if you don't require a lot of parameter passing. You could also have a CL program that does all the calls; the RPG program (or programs) simply returns information to the CL driver so it knows what procedure to do next. However, these types of techniques are sometimes unacceptable. That's when you can employ this utility to couple programs and allow them to be called recursively.
The easiest way to explain how to use this utility is to present an example. Since the most powerful way to use the utility is to allow programs to be called recursively, the example application I'll present requires recursive calls. Let's say you have two payroll inquiry programs that are used to view the employees and departments of your company. The first program, which we'll call EMPINQ, is used to display a list of employees. The second program, DEPTINQ, is used to display a list of departments an employee is eligible to work in. Each of these programs calls the other to allow the user to continue drilling down into different views of employees and departments.
When the initial employee is selected in EMPINQ, the employee number is passed into DEPTINQ, and a list of all departments that employee can work in is displayed. When a department is selected in DEPTINQ, that department number is passed into EMPINQ, and the names of all employees who belong to that department are displayed, and so on. To use the CHKSTK utility to accomplish this, you would insert code before the CALL statements to call CHKSTK first. CHKSTK would return an object name that the CALL statement should use. Figures 1 and 2 show sample code fragments from the EMPINQ and DEPTINQ programs that would allow these programs to call each other recursively.
The CHKSTK program has two parameters. The first is a program name, and the second is a code that tells the utility what action to perform. When no program name is passed in, the utility will retrieve the name of the program that called your program (i.e., the program running one level higher in the call stack). When a program name is passed in and the action code is an N, the utility will simply tell you if the specified program is already running in the current job call stack by returning a Y or an N through the second parameter. If the action code is a C and the specified program is active in the stack, CHKSTK will duplicate the specified program into QTEMP using a unique name, return the unique name to your program through the first parameter, and place a Y in the second parameter.
Instead of using a constant or a literal in your CALL statement, you would then use the variable that contains the unique program name returned to your program by CHKSTK. If the action code is a D, the utility will attempt to delete the specified program from QTEMP. The delete option should be used to clean up QTEMP whenever the program is finished with these objects. Typically, this would be done when the user is leaving the program that triggered the object to be created.
The code for the CHKSTK utility is presented in 3. The first thing the utility must do when creating a unique object (option C) is determine if the specified program is in the job's call stack. It does this by sending a program message to that program and monitoring for messages CPF2469 and CPF2479. If an error occurs on SNDPGMMSG, the specified program is not running and a recursive call error will not occur if you call it. Therefore, the actual program name you passed into CHKSTK will be passed back out to you, and the second parameter will return an N. However, if the error does not occur, the program is running and you would get a "Recursive call" error by calling it.
The code for the CHKSTK utility is presented in Figure 3. The first thing the utility must do when creating a unique object (option C) is determine if the specified program is in the job's call stack. It does this by sending a program message to that program and monitoring for messages CPF2469 and CPF2479. If an error occurs on SNDPGMMSG, the specified program is not running and a recursive call error will not occur if you call it. Therefore, the actual program name you passed into CHKSTK will be passed back out to you, and the second parameter will return an N. However, if the error does not occur, the program is running and you would get a "Recursive call" error by calling it.
CHKSTK will then proceed to create a unique object in QTEMP. It does this by using a data area named $RCSVCALL in the job's QTEMP library to keep track of a sequential 4-digit number that will be used as part of the object name. If the data area doesn't already exist in QTEMP, it will be created. The value is retrieved from the data area into a CL variable named &LEV and is incremented by one. The data area is changed so that it now contains the new value. The CL variable &UNIQUE is set to UNQ plus the sequential number.
The first unique object name created by this utility would be UNQ0001, the second would be UNQ0002, and so on. The next step is to use the Retrieve Object Description (RTVOBJD) command to find out what library the specified program is in. At this point, the utility has come up with a unique object name, and it knows where to find the production object. It then creates a duplicate object in the job's QTEMP library and changes the first parameter to &UNIQUE to return the unique object name back to your program so it knows what to call. When CHKSTK is used to delete the QTEMP objects, the first parameter should be the name of the object in QTEMP that needs to be deleted.
I recommend that this utility be used only if there are no other ways to perform a recursive call. If you're using CHKSTK to be able to call a maintenance program recursively, remember that there is no way to know what the real production object name is when a duplicate object is created in QTEMP.
The program-generated object names and duplicate objects will not remain on the system. This could present a problem if you try to use this technique with a program that updates a file and you expect to be able to trace this activity later in your system's journals. The journals will show the QTEMP object name instead of the production library object name.
You would probably want to change the code so it will create a name similar to the original object name. This may help you identify the real production program name when looking through journal entries. You could also have the utility generate an audit log identifying the user, job name, job number, object being duplicated, and the unique object name in order to allow you to match journal entries up to the audit log.
If you're implementing CHKSTK in an end-user application, be sure that the users who will be using it have authority to create objects. If they do not have the required authority, they will get an error on the Create Duplicate Object (CRTDUPOBJ) command in the CHKSTK program.
While this technique adds some additional overhead to your applications, it's nice to know that there is a way to do a recursive call when you really need it. For example, if a program your users run from a menu option is also accessible via the attention key or a message queue break handling program, then you will find this utility very useful. You can use CHKSTK to allow your program to run as a menu option and again as an attention program.
Todd Fisher is a senior software developer/analyst for Information Management Solutions in Chattanooga, TN.
The Check Stack Utility
Figure 1: Partial Code for the EMPINQ Example Program
* . * . * . * Check stack for program DEPTINQ before calling it... C CALL 'CHKSTK' C PARM 'DEPTINQ' @PGM 10 C PARM 'C' @ACT 1 * * Call DEPTINQ function using unique object name... C CALL @PGM C PARM DEPT * . * . * .
The Check Stack Utility
Figure 2: Partial Code for the DEPTINQ Example Program
* . * . * . * Check stack for program EMPINQ before calling it... C CALL 'CHKSTK' C PARM 'EMPINQ' @PGM 10 C PARM 'C' @ACT 1 * * Call EMPINQ function using unique object... C CALL @PGM C PARM EMP# * . * . * .
The Check Stack Utility
Figure 3: The CHKSTK Utility
/*==================================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/CHKSTK) SRCFILE(XXX/QCLSRC) */ /* */ /*==================================================================*/ /* Input Parameters: &PGM (10 CHAR) = Program Parameter */ /* -Pass BLANKS to retrieve your program's */ /* caller */ /* -Pass a PROGRAM NAME to check the job's */ /* call stack to see if the specified */ /* program is already active. */ /* */ /* &ACT (1 CHAR) = Action To Take */ /* -Pass a "C" if you want this program to */ /* create a unique object in QTEMP and */ /* return the object name to your program */ /* through the &PGM parameter. This will */ /* allow your program to call the unique */ /* object to allow a recursive call. */ /* -Pass "D" to delete the unique object that */ /* was previously created in QTEMP. */ /*------------------------------------------------------------------*/ /* Output Parameters: &PGM (10 CHAR) = Program Parameter */ /* -If BLANKS were passed, this will contain */ /* the name of your program's caller */ /* -If "C" was passed in the &ACT parameter, */ /* this parameter will contain the program */ /* name that your program should call in */ /* order to allow a recursive call. */ /* &ACT (1 CHAR) = Active? */ /* -"Y" the pgm is in the job's call stack */ /* -"N" the pgm isn't in the call stack */ /*==================================================================*/ PGM PARM(&PGM &ACT) DCL VAR(&PGM) TYPE(*CHAR) LEN(10) DCL VAR(&PGMLIB) TYPE(*CHAR) LEN(10) DCL VAR(&UNIQUE) TYPE(*CHAR) LEN(10) DCL VAR(&ACT) TYPE(*CHAR) LEN(1) DCL VAR(&OPTN) TYPE(*CHAR) LEN(1) DCL VAR(&KEY) TYPE(*CHAR) LEN(4) DCL VAR(&LEVEL) TYPE(*CHAR) LEN(4) DCL VAR(&LEV) TYPE(*DEC) LEN(4 0) DCL VAR(&CALLER) TYPE(*CHAR) LEN(10) DCL VAR(&SENDER) TYPE(*CHAR) LEN(80) DCL VAR(&MSGKEY) TYPE(*CHAR) LEN(4) DCL VAR(&MSGDTA) TYPE(*CHAR) LEN(132) DCL VAR(&MSGF) TYPE(*CHAR) LEN(10) DCL VAR(&MSGFLIB) TYPE(*CHAR) LEN(10) DCL VAR(&MSGID) TYPE(*CHAR) LEN(7) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ERROR)) /* If a Program Name was passed see if it's active */ /* in the job's Call Stack... */ IF COND(&PGM *NE ' ') THEN(DO) CHGVAR VAR(&OPTN) VALUE(&ACT) CHGVAR VAR(&ACT) VALUE('N') /* Delete Unique Object in QTEMP... */ IF COND(&OPTN *EQ 'D') THEN(DO) DLTPGM PGM(QTEMP/&PGM) MONMSG MSGID(CPF0000) GOTO CMDLBL(EXIT) ENDDO /* Send a program message to the specified program. */ /* If the SNDPGMMSG command fails, the program is */ /* not active to receive the message... */ SNDPGMMSG MSG('Check Job Stack for program' *BCAT &PGM + *TCAT '...') TOPGMQ(*SAME (&PGM)) + MSGTYPE(*INFO) KEYVAR(&KEY) MONMSG MSGID(CPF2479 CPF2469) EXEC(GOTO CMDLBL(EXIT)) /* If we made it this far, the program is active... */ CHGVAR VAR(&ACT) VALUE('Y') /* Remove the message that was just sent... */ RMVMSG PGMQ(*SAME (&PGM)) MSGKEY(&KEY) MONMSG MSGID(CPF0000) /* Create Unique Object in QTEMP using a unique */ /* naming scheme... */ IF COND(&OPTN *EQ 'C' *AND &ACT *EQ 'Y') THEN(DO) CHKOBJ OBJ(QTEMP/$RCSVCALL) OBJTYPE(*DTAARA) MONMSG MSGID(CPF0000) EXEC(CRTDTAARA + DTAARA(QTEMP/$RCSVCALL) TYPE(*DEC) LEN(4) + VALUE(0000) TEXT('Allow Recursive Calls...')) RTVDTAARA DTAARA(QTEMP/$RCSVCALL *ALL) RTNVAR(&LEV) CHGVAR VAR(&LEV) VALUE(&LEV + 1) CHGVAR VAR(&LEVEL) VALUE(&LEV) CHGDTAARA DTAARA(QTEMP/$RCSVCALL *ALL) VALUE(&LEV) CHGVAR VAR(&UNIQUE) VALUE('UNQ' *TCAT &LEVEL) RTVOBJD OBJ(&PGM) OBJTYPE(*PGM) RTNLIB(&PGMLIB) CRTDUPOBJ OBJ(&PGM) FROMLIB(&PGMLIB) OBJTYPE(*PGM) + TOLIB(QTEMP) NEWOBJ(&UNIQUE) CHGVAR VAR(&PGM) VALUE(&UNIQUE) ENDDO GOTO CMDLBL(EXIT) ENDDO /* If a program name was not passed, find out the */ /* program that called the caller and return it */ /* as a return parameter... */ IF COND(&PGM *EQ ' ') THEN(DO) /* Send the previous program a message, then receive */ /* it in order to obtain the program name in the */ /* SENDER parameter... */ SNDPGMMSG MSG('Get The Previous Program Name (The + Caller)...') RCVMSG PGMQ(*PRV) MSGTYPE(*LAST) SENDER(&SENDER) CHGVAR VAR(&CALLER) VALUE(%SST(&SENDER 56 10)) SNDPGMMSG MSG('Get The Program Name That Called The + Caller...') TOPGMQ(*PRV (&CALLER)) + MSGTYPE(*INFO) KEYVAR(&MSGKEY) RCVMSG PGMQ(*PRV (&CALLER)) MSGKEY(&MSGKEY) + RMV(*YES) SENDER(&SENDER) CHGVAR VAR(&PGM) VALUE(%SST(&SENDER 56 10)) GOTO CMDLBL(EXIT) ENDDO ERROR: RCVMSG MSGTYPE(*EXCP) MSGDTA(&MSGDTA) MSGID(&MSGID) + MSGF(&MSGF) MSGFLIB(&MSGFLIB) SNDPGMMSG MSGID(&MSGID) MSGF(&MSGFLIB/&MSGF) + MSGDTA(&MSGDTA) MSGTYPE(*ESCAPE) RETURN EXIT: RMVMSG CLEAR(*ALL) ENDPGM
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online