%PASSED and %OMITTED Built-in Functions

In this example, the DoSomething subprocedure accepts 3 parameters.  The first one, Param1, has options(*omit) defined – which means that when you call the procedure, you can either pass a value, or you can pass the *OMIT special value.  For example:

DoSomething(MyVar);

Or

DoSomething(*OMIT);

This is very helpful when a subprocedure has a “default” value.  You can pass *OMIT, and the code inside of the procedure can use a default value if it determines that *OMIT was provided.  But there are some key things that you should consider when using Param1:

• If you call the subprocedure from RPG and use the prototype, you must always pass something for this parameter (even if it’s the special value *OMIT).
• When you add a new parameter to an existing subprocedure, if *OMIT is used, you must update all of the existing callers to pass *OMIT.
• Any callers that don’t use the prototype (such as those written in other languages like CL, Cobol or SQL) will not be forced by their compiler to provide *OMIT or a value, and unpredictable results can occur checking %addr(Param1) if nothing was passed.

The third parameter, Param3, uses the alternative of *NOPASS, which means it’s possible to call the procedure without passing this parameter at all.  For example, you can call it like this:

DoSomething(Var1: Var2: Var3);

-or-

DoSomething(Var1: Var2);

Since you can choose to leave the third parameter unpassed, it is important that the code only use this parameter if it was provided.  Prior to the %PASSED BIF, the way you’d check that is by checking %PARMS to see how many parameters were passed, and if there’s at least 3 (in this example) then you know Param3 was provided. 

• Unlike *OMIT, if this parameter was added to an existing subprocedure, the existing callers do not need to be updated at all.
• Since the parameter is new, the existing callers will already be passing fewer parameters, so the check of %PARMS will still work without changes.
• Callers that do not use the prototype (such as those in other languages) will also work correctly provided that they at least provide the parameter count, so in that respect, it is less error-prone than using *OMIT.
• Callers that don’t use the prototype may still provide *OMIT, but the subprocedure isn’t expecting this. This error is predictable, since the address of the parameter will be null, you will get a null pointer error.
• The procedure must be very careful to never use this parameter (this includes passing it forward to any other procedures or programs) or unpredictable results will occur.
• If a 4^th parameter is added to the subprocedure, it must also be *NOPASS, and there’s no way to pass the 4^th parameter without also passing the 3^rd.

Due to these disadvantages, many programmers choose the “best of both worlds” by allowing both *OMIT and *NOPASS like Param2 does.  It can be called like this:

DoSomething(Var1);

-or-

DoSomething(Var1: *OMIT);

-or-

DoSomething(Var1: Var2);

-or-

DoSomething(Var1: *OMIT: Var3);

This is easily the most flexible option.  But doing it this way, you must be careful to check both %PARMS and the %ADDR of the parameter.  If you don’t (or don’t check them correctly) unpredictable results will occur.

The %PASSED Built-in Function

The new %PASSED built-in function aims to simplify parameter handling by automatically checking both the number of parameters passed and whether a parameter was omitted for you automatically. This simplifies coding by making sure it is passed correctly.  Using the new %PASSED BIF, we can code our subprocedure as follows: