Investigate the ILE CL compiler's mechanism for receiving program parameters.

There's no doubt that the program-call mechanism in IBM i is fully dynamic. The called program can be determined at run time instead of at compile time. The parameter list passed to the called program can be composed at run time by the calling program. Also, the length of the parameter list for a called program can be changed dynamically. As you might know, an ILE RPG program can retrieve of the length of the parameter list via the RPG %PARMS built-in function (BIF). An ILE C program can also achieve this goal via the first argument of its main function, int argc. So is it possible for an ILE CL program to know the number of parameters passed to it? This article will lead you to answer, all the way down to the RISC instruction level.

Two fields in the program header of an MI program object determine the Number of parameters attribute of the program: PEP MIN PARMS and PEP MAX PARMS, meaning the minimum and maximum number of parameters that can be passed to the program entry procedure (PEP) of program. Upon a program-call (due to a Call External (CALLX), a Transfer Control (XCTL), or a Call Program with Variable Length Argument List (CALLPGMV) MI instruction), if the length of the parameter list passed to the called program is out of the range from PEP MIN PARMS to PEP MAX PARMS of the called program, a hex 0802 (Argument List Length Violation) exception will be signaled. Different compilers choose different policies in determining the range of the allowable parameter list length. In OMI, the programmer is responsible for specifying the minimum and maximum number of parameters of an OMI program. Additionally, the calling program can set the length of the parameter list to a called program via the Set Argument List Length (SETALLEN) OMI instruction, and the called program can retrieve the number of parameters passed to it via the Store Parameter List Length (STPLLEN) OMI instruction. Experiments show that for an OPM RPG or an OPM COBOL program, the minimum number of parameters is set to zero, and the maximum number of parameters is set to the length of the program-defined parameter list. For an ILE program, the length of the parameter list is determined by the entry point procedure of the PEP module of the program. For example, the parameter list length of an ILE COBOL module ranges from zero to the number of parameters of the program-defined parameter list, and that of an ILE CL module ranges from zero to 255. Therefore, a calling program is able to call an ILE CL program (or more exactly, an ILE program the PEP module of which is an ILE CL module) and pass up to 255 parameters even though the called program does not expect any parameter. This makes it more important for an ILE CL program to know the exact number of parameters passed to it.

The OPM Parameter Count (_OPM_PARM_CNT) System Built-In

According to the documentation of the_OPM_PARM_CNT system built-in in the IBM i Information Center, the parameter count in the non-bound program parameter list received by the program entry procedure is returned by _OPM_PARM_CNT. So can we retrieve the parameter list length via this system built-in?

However, the same documentation shows that a user program written in any ILE High-Level Language(s) (HLL) cannot utilize the _OPM_PARM_CNT system built-in: This function can only be used by procedures defined to be a program entry procedure. Otherwise, an instruction stream not valid (hex 2A1B) exception will be signaled during module creation. As you might know, ILE compilers generate an entry point procedure into each compiled module object. (A DSPMOD DETAIL(*PROCLIST) command will show you that.) Only the entry point procedure of a module can act as the PEP of an ILE program; therefore, a user procedure in a compiled ILE program never has the chance to become the PEP of the program.

The NPM Procedure Parameter List Address (_NPMPARMLISTADDR) System Built-In

The documentation of the_NPMPARMLISTADDR system built-in in the IBM i Information Center described this system built-in as follows:

The address of the New Program Model parameter list received by the current invocation is returned. ... Arguments is a variable length field (at offset hex 20) used to pass argument values to the current invocation.

Can we use the _NPMPARMLISTADDR system built-in in the main procedure of an ILE CL program to retrieve the number of parameters passed? The following is a tiny CL program, parm05.clle, that displays the first 96 bytes of the arguments field in the parameter area returned by _NPMPARMLISTADDR.

Note that the program-defined parameter list of PARM05 takes three parameters. Note also that the &CNT and &PRMCNT variables and the SNDPGMMSG MSGID(ART0101) MSGF(ARTMSG) MSGDTA(&PRMCNT) command are for the experiment at the end of this article.

Prepare a message file that is needed by PARM05 like this:

Call program PARM05 with three parameters. The content of the arguments field returned by _NPMPARMLISTADDR might look like the following:

The content of the arguments field contains three space pointers addressing the parameters passed to PARM05. It shows that _NPMPARMLISTADDR is able to return all the program-defined parameters.

Call program PARM05 again with five parameters. The content of the arguments field might look like the following:

The fourth and fifth parameters passed to PARM05 are not returned by _NPMPARMLISTADDR. Does this mean that the _NPMPARMLISTADDR system built-in cannot be used to retrieve the parameters passed to the main procedure of an ILE CL program? Or the main procedure (user procedure) of an ILE CL program does not receive the full parameter list passed by the calling program? This question will be answered later in this article by investigating the actual PEP of an ILE CL program, _CL_PEP.

Finally, call program PARM05 with two parameters. The content of the arguments field might look like the following:

The content of the arguments field contains two space pointers addressing the parameters passed to PARM05, followed by 16-byte hex 00. The following information is supplied in the Passing parameters section of the CL Programming book, which is available in the IBM i Information Center:

When calling an ILE program or procedure, the operating system does not check the number of parameters that are passed on the call. In addition, the space where the operating system stores the parameters is not reinitialized between program or procedure calls. Calling a program or procedure that expects n parameters with n-1 parameters makes the system use whatever is in the parameter space to access the nth parameter. The results of this action are very unpredictable. This also applies to programs or procedures written in other ILE languages that call CL programs or procedures or are called by CL programs or procedures.

According to this documentation, the 16 bytes at offset hex 20 in the content of the arguments field should be the third space pointer (X'8000000000000000FC19EC7E44001688') shown in the previous call to PARM05 instead of 16-byte hex 00. Obviously, the result of our experiment doesn't coincide with the above-shown documentation. This will be explained later via our investigation into the _CL_PEP procedure.

Investigate the _CL_PEP Procedure

_CL_PEP is the entry point procedure generated by the ILE CL compiler for each CL module. When a CL module is chosen as the PEP module of an ILE program (due to a CRTPGM command or a CRTBNDCL command), the _CL_PEP procedure of the CL module becomes the program entry procedure (PEP) of the program. The following is the PowerPC instruction stream of the _CL_PEP procedure (at VRM540) of the above-mentioned ILE CL program PARM05. The _CL_PEP operates on the parameter list passed to the program and then passes control to the user procedure PARM05. The operations on the parameter area are explained by pseudocode and comments.

Notes

[1] From Chapter 33: Analysis of SCV 7, Program Call of Leif Svalgaard's e-book AS/400 Machine Level Programming, we know that the address of the parameter area to a called program during a program call is passed via General Purpose Register (GPR) 3 (r3). Later, you'll find out that r3 is also used to pass the address of the parameter area during a procedure call. Here, the content of r3 is copied to r30.

[2] Load the number of parameters passed into r27 from the address of the parameter area (now stored in r30) at offset 4. By debugging an OMI program, you learn that during a program call the number of parameters and each individual parameter are stored in the parameter area for the called program as the following:

• A BIN(4) field at offset 4 is the number of parameters passed.
• 8-byte Single-Level Store (SLS) addresses of all parameters are stored in the parameter area sequentially starting from offset 8. By convention, parameters for a program call are passed by references, which means each 8-byte address in the parameter area addresses a space pointer to the corresponding parameter.

[3] Start of the parameter-handling loop.

[4] num_parms_defined is the number of the parameters in the parameter list defined by the program. In this example, the value of num_parms_defined is 3. As shown by the program logic, parameters whose index numbers are greater than the length of the program-defined parameter list are simply ignored by _CL_PEP. Therefore the _NPMPARMLISTADDR system built-in issued in the main procedure of an ILE CL program cannot retrieve any parameters other than the program-defined parameters.

[5] As you might know, r31 always addresses the upper limit of the automatic storage frame (ASF) of the current invocation. The ADDI 24,31,-176 instruction locates the address of the space pointer to the first program-defined parameter in the ASF of _CL_PEP.

[6] Here, parm_ptr_addr means the address of the space pointer to the current parameter in the ASF of _CL_PEP. parm_ptr_addr is computed by adding (index - 1) * 16 to the address of the space pointer to the first program-defined parameter. 16 is the size of an MI pointer.

[7] addr is set to the 8-byte SLS address at offset (8 * index) from the beginning of the parameter area.

[8] The space pointer addressing the index parameter is copied from address addr to the ASF location where the space pointer to the index program-defined parameter is stored.

[9] For each parameter that is not passed by the caller program, the space pointer addressing the corresponding parameter is set to 16-byte hex 00. Therefore, in the main procedure of an ILE CL program, you can test whether a specific parameter is passed by testing the address of the parameter via any method that can be used to test for a null pointer—for example, the Compare Pointer Type (CMPPTRT) MI instruction with the comparison value set to hex 00.

[10] Before _CL_PEP passes the control to the user procedure PARM05, the space pointers to the program-defined parameters recorded by _CL_PEP are copied to the parameter area for procedure PARM05, which can be retrieved via the _NPMPARMLISTADDR system built-in in procedure PARM05. In this example, (r31 - 0x60) is the address of the parameter area for procedure PARM05. PARM05 takes three program-defined parameters. The corresponding space pointers are copied from (r31 - 0xB0) to location (r31 - 0x60 + 0x20).

[11] r3 is set to the address of the parameter area (r31 - 0x60) for procedure PARM05.

[12] Finally, call procedure PARM05.

The Final Experiment: Display the Number of Parameters Passed to an ILE CL Program

From the previous analysis of the _CL_PEP procedure of an ILE CL program, we know that the compiler-generated procedure knows the number of parameters passed to the program very well; it just doesn't pass this information to the user procedure of the CL program. In the following experiment, let's make a tiny modification to the RISC instruction stream of the user procedure of ILE CL program PARM05 to retrieve the number of parameters passed to the program, which was omitted by the _CL_PEP procedure.

Observe the RISC instructions generated for _CL_PEP again. You'll find that the content of r30 (which is set to the value of r3 at the beginning of _CL_PEP) remains unchanged until procedure PARM05 is invoked. Therefore, we may have the chance to obtain the address of the parameter area of the program stored in r30. Look at the start of the RISC instructions of the PARM05 procedure:

Change the two PowerPC instructions at offset hex 40:

Now, call the modified PARM05 program with different numbers of parameters to test the modification. For example, CALL PARM05 (A B C D E), the output might look like the following:

Yes, we've managed to get the number of parameters passed to our ILE CL program! However, it is only an experiment rather than a practical solution. What we actually need is a built-in support for retrieving the length of the parameter list passed to a CL PEP. What about a %PARMS built-in in future improvements to CL? Maybe, and you've already seen how easy it is to implement such a built-in for CL.

Junlei Li is a programmer from Tianjin, China, with 10 years of experience in software design and programming. Junlei Li began programming under i5/OS (formerly known as AS/400, iSeries) in late 2005. He is familiar with most programming languages available on i5/OS—from special-purpose languages such as OPM/ILE RPG to CL to general-purpose languages such as C, C++, Java; from strong-typed languages to script languages such as QShell and REXX. One of his favorite programming languages on i5/OS is machine interface (MI) instructions, through which one can discover some of the internal behaviors of i5/OS and some of the highlights of i5/OS in terms of operating system design.

 

Junlei Li's Web site is http://i5toolkit.sourceforge.net/, where his open-source project i5/OS Programmer's Toolkit (https://sourceforge.net/projects/i5toolkit/) is documented.

Also Read

TechTip: Printing from a CL Program (the PRTLN Command)

TechTip: Date Arithmetic in CL Programs

TechTip: Entering Quotes in CL Variables — A Better Way?