You are currently on IBM Systems Media’s archival website. Click here to view our new website.


The Mystery of the Command Line Parameters

This month we decided to look at "one of those questions." This particular question crops up repeatedly in online support forums, and probably with monotonous regularity on IBM's support line. One of the reasons it arises so frequently is that it can materialize itself in many ways. For example, one person might ask: "Why do I get decimal data errors when I call my program from the command line? It works perfectly when I call it from another program!" While another might pose this question: "Why are there garbage characters at the end of the parameters that I entered on the call?" It's hardly surprising, therefore, that even the most carefully worded Google search may fail to reveal an answer.

Why such variety? Because the underlying issue relates to the way parameters are passed on any call that's handled by the command line processor. Among others, this includes:

  • A simple CALL from the 5250 command line
  • A CALL embedded in a SBMJOB command
  • CALLs executed through QCMDEXC or the C 'system' function

Let's begin by posing a simple question. If I enter the following CALL statement on the command line, how should I code the *Entry PLIST (or Procedure Interface) in program TEST in order to handle the parameters correctly?

CALL PGM(TEST) PARM('abcd' 1.2)

If you answered by saying that the first parameter should be defined as being a character field of at least four characters in length, and the second as a 15,5 packed decimal field -- then our congratulations, you've passed the first test. If this wasn't your answer, read on and all will be explained. Even if you got the right answer, you may still want to read on because there's at least one more twist in this tale.

So why is this the right answer? To understand this, you first have to remind yourself of the mechanics of a program call. When we call a program and pass it a parameter, we're actually giving it a pointer to the first byte of the parameter data. We aren't actually passing the data itself. When we call one program from another, the calling program defines the type and size of the data being passed, and as long as the two programs agree with each other as to the definition of the parameters, there should be no problem -- at least with the parameter passing. (Note: If you want to get deeper into the topic of parameter passing, check out our article "RPG IV Prototypes") However, when passing a parameter from the command line, the command processor has no such knowledge, and since the system provides no way of interrogating the called program so that its parameter requirements can be determined, it has no choice but to make assumptions about the characteristics of the parameter(s). So exactly what assumptions will the command processor make? It depends on the parameters you entered on the command. The base assumptions are that:

  • If the parameter is a character string then it's either 32 characters in length or the length of the actual string passed, whichever is greater. You can see from this that the answer of four characters given earlier is technically incorrect, but it wouldn't cause any problems since our program would simply see the first four characters. Of course if we entered a 10-character parameter, only the first four would be "seen" by the called program.
  • If the parameter is numeric, the processor automatically assumes that it's a packed field with a length of 15 digits and five decimal places. It will stick rigidly to this definition even if your input parameter defines more than five decimal places. Any decimal places in excess of five are simply discarded without warning. If, however, you attempt to enter more than 10 integer positions, you'll receive the error message "Numeric value for parameter PARM is not valid."

Having established what it assumes are the required type and length of the parameter(s), the processor then allocates temporary storage for them and copies the data from the command into it. It's a pointer to this temporary storage that's ultimately passed to your program.

As noted above, numeric fields passed from the command line are always treated as 15,5 packed -- no exceptions. As annoying as that may be, it's at least a simple rule that we can deal with. However, now that you understand the basic principles involved, you can hopefully see that the assumptions made for character fields can cause a few other problems.

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters