Natural Tip of Week of March 24, 2008

Subject: Natural subprograms
Title: Optional attribute for passed parameters

An optional parameter is a field defined with the keyword OPTIONAL in the DEFINE DATA PARAMETER.

Here is an example of the Natural code:

DEFINE DATA PARAMETER
1 #P1 (A10)
1 #P2 (A10) OPTIONAL
1 #P3 (A10)
1 #P4 (A10) OPTIONAL
1 #P5 (A10) OPTIONAL
END-DEFINE...

Invoking Object:
CALLNAT 'MY-SUB' #A #B #C #D #E 
or
CALLNAT 'MY-SUB' #A 1X #C 2X
or
CALLNAT 'MY-SUB' #A 1X #C
or
CALLNAT 'MY-SUB' #A #B #C 1X #E

The nX notation informs natural whaich positional parameter is to be skipped. This means that the address for that parmater is not passed to the invoked subprogram. This can only be mapped to a variable with the attribute OPTIONAL. However, you MUST write your subprogram with the foreknowledge that someone may invoke you and NOT pass the address of the variable. If one writes

CALLNAT 'MYSUBPGM' #ARG1 #ARG2 #ARG3

and this is matched against

PARAMETER
1 #ARG1 (A5)
2 #ARG2 (A5)
3 #ARG3 (N10)
4 #NEW-OPTION (A10) OPTIONAL ....

You cannot (or I should say SHOULD not) write

IF #NEW-OPTION ...

If you do and the original program does the CALLNAT like above, then you will be referencing a variable with no address since it was not included in the parameter list and a Natural error occurs. The subprogram should then never reference such a variable directly, but instead should use the SPECIFIED Option in Logical Condition instead. With the new SPECIFIED option , you are able to check whether or not a parameter has received a value from the invoking object.

Example:
    IF #PASSED-FIELD1 SPECIFIED   
    THEN ... ELSE ...
    IF #PASSED=FIELD2 NOT SPECIFIED
    THEN ... ELSE ...

For a field not defined as OPTIONAL the SPECIFIED condition is "TRUE".

I currrently try to keep ALL optional variables at the end, especially when extending an existing subprogram where every referenc does not need change. However the flexibility of the syntax does not force this as any requirement. Now there is a case I can fabricate that shows when this may not be important.

Suppose like the old days you created a super module that can do a variety of activities based on input, for example a core date routine. Maybe you want one of several calculations it can provide. Let's say it has 10 inputs and 5 outputs and when a particular 2 are provided a specific output should get generated. Then if they are all optional (which is possible) then you would need to code

CALLNAT 'DATERTNE' #A #B 8X #OUT1  or
CALLNAT 'DATERTNE' 2X #A #B 7X #OUT2

And the routine is smartly written to know which pair force a computation for which output which it can do with IF SPECIFIED. Here is to what I am refering:

PARAMETER
01 #F1
01 #F2
01 #F3 ... OPTIONAL
01 #F4 ... OPTIONAL

In combination with CALLNAT 'module' #A #B 1X #D

You could write:

IF #F3 SPECIFIED
   #F3 := #F1 + #F2
ELSE
   IF #F4 SPECIFED
      #F4 := #F1 * #F2
   END-IF
END-IF

There are a few important errors which a user of the OPTIONAL attribute should be aware.

- Natural System Message NAT0648 -
Ex *** Explanation ***
    The parameter supplied in a CALLNAT statement is not compatible
    with the corresponding parameter definition in the subprogram.
    Reason codes:
    04 : The CALLNAT parameter is specified as an empty parameter ("nX"),
         but the definition in the subprogram is not "OPTIONAL".
    08 : Mandatory parameter in the subprogram is missing in
         the CALLNAT statement.
    12 : Parameters do not match in format.
    16 : Parameters do not match in length.
    20 : Parameters do not match in array definitions.
 Ac *** Recommended Action ***
    Supply compatible parameter specifications.

NAT1322 Parameter 2 missing (invoked at line …).
E 0220   CALLNAT ‘ABCD' PERSONNEL-ID 2X #COUNTRY
In this situation the OPTIONAL clause had been coded but the second field, NAME in this example, was not used within a SPECIFIED condition clause.

NAT0648 Parameter 3 inconsistently specified. Reason code 16.
E 0220   CALLNAT 'PAGE11N' PERSONNEL-ID NAME #LANGUAGE(*) #COUNTRY
Unless the BY VALUE clause is used, arrays must match by format, length and dimension.