7.9.2 CALL Comments / Warnings

Calling a Process or Function

• The use of parameters when calling another process or function is strongly not recommended. Use the exchange list instead.

• When calling another LANSA process the parameters must exactly match those required by the process, in number passed, and type (i.e: numeric or alpha).

• The parameters passed to the called process or function can be a field name, an alphanumeric literal, a numeric literal, a system variable or a process parameter.

• Note that when numeric parameters are defined for a process they are always packed decimal. Thus any numeric parameters passed to LANSA processes should also be packed decimal with the same length and number of decimal positions. Failure to observe this rule may result in unpredictable results.

• Using multiple data structures that have fields with the same name in the same function, may cause unpredictable results.

• In the current release of LANSA parameters passed to another process or function are NOT RETURNED from the process or function. However, information can be passed to and returned from a called function by using the EXCHANGE command just before the CALL command. Refer to the EXCHANGE command for more details of how this is done.

• Each physical file referred to by the data structures named in the PASS_DS parameter must be made operational or the results will be unpredictable.

• When a compiled RDML function (e.g.: FUNCA) is running and executes a CALL command like this:

CALL PROCESS(TEST) FUNCTION(FUNCB)

to invoke another RDML function called FUNCB, what actually happens is this:

                      ____________

                     |            | 

                     |  Function  |

                     |   FUNCA    |

                     |____________| 

                           |

                         calls

                           |

                      _____|______

                     |            | 

                     |  Process   |

                     |"Controller"|

                     |   TEST     |

                     |____________|

                           |

                         calls

                           |

                      _____|______

                     |            | 

                     |  Function  |

                     |   FUNCB    |

                     |____________|

• This CALL operation can be made significantly quicker by doing the following, especially if the process controller TEST is running in interpretive mode rather than compiled mode:

1.  Include the command FUNCTION OPTIONS(*DIRECT) into FUNCB (note that is FUNCB) then recompile it. This simply specifies that FUNCB is eligible for direct mode invocation and it will not affect FUNCB in any way.

2.  Change the call command in FUNCA to be like this:

CALL PROCESS(*DIRECT) FUNCTION(FUNCB)

     then recompile FUNCA. This indicates that function FUNCB should be called in direct mode, rather than via its process controller named TEST.

     After these changes, the CALL will work like this:

                        ____________

                       |            |  

                       |  Function  |

                       |   FUNCA    |

                       |____________|

                             |

                           calls

                             |

                        _____|______

                       |            |

                       |  Function  |

                       |   FUNCB    |

                       |____________|

 

 

• Use this option (i.e: FUNCTION OPTIONS(*DIRECT)) in any function that is intended to be used as a "subroutine", rather than a main controlling function directly accessible from a process menu. All calls to the function should use the CALL PROCESS(*DIRECT) option.

• This performance benefit is also available when FUNCB is used as a prompter function (i.e: it services F4=Prompt key requests). When associating FUNCB with a field in the data dictionary, simply indicate its process name as *DIRECT, rather than by specifying its actual process name (TEST).

• There is no harm in specifying FUNCTION OPTIONS(*DIRECT) in all functions. Functions using this option are equivalent to functions that do not use this option, and no restrictions on accessing such functions from process menus exist.

• In a function that does not use FUNCTION OPTIONS(*DIRECT) the associated RPG program, display file object and multilingual extension program have names F@innnnn, @innnnn and F@innnnnML respectively, where "innnnn" is an internal function identifier assigned by LANSA. This caters for duplicate function names.

• In a function that does use FUNCTION OPTIONS(*DIRECT), the resulting object names are @fffffff, @fffffff and @fffffffML, where fffffff is the name of the function (from 1 to 7 characters long). This is why function names must be unique when using FUNCTION OPTIONS(*DIRECT).

• Some restrictions do exist when using the *DIRECT facility:

• All exchange of information between FUNCA and FUNCB must be via the exchange list. Parameters are not supported and cannot be used. This is checked by the full function checker.

• The function name FUNCB must be unique within the partition. This is also checked by the full function checker.

• FUNCB cannot use any "sideways" control commands like TRANSFER because in this structure it does not have its process controller (TEST) available to handle the request for it. It should always be terminated by a CANCEL/MENU function key or command, an EXIT function key or command, or by a RETURN command.

• FUNCB should not be part of an action bar process. This type of call, into an action bar function, would be quite strange and is unlikely to be encountered. Whenever an action bar function calls another program, the called program should only communicate with the user via POP_UPs, not via full panel DISPLAY or REQUEST commands that may upset the action bar display and processing.

• FUNCB acts like a logical "subroutine" of FUNCA.

• FUNCB should have a specific OPTIONS(*HEAVYUSAGE) or (*LIGHTUSAGE) directive. If this is not specified they will adopt the usage option of the function that called them, rather than adopting the usage option of its parent process TEST.

• The introduction of the CALL PROCESS(*DIRECT) option has now made high volume calls possible, this was previously not recommended IN LANSA. When implementing high volume calls to other functions the size of the exchange list should be considered. In these circumstances a large number of fields on the exchange list may cause a performance overhead.
  
  Investigate the option of passing data structures (CALL....PASS_DS(#dddddd)) between functions instead of using the exchange option.

Calling a User Program

• The parameters passed to the called program or process can be a field name, an alphanumeric literal, a numeric literal, a system variable or a process parameter.

• If special value *LIBL was nominated as the library containing the program then the program should be in one of the libraries in the user's library list at the time the function is executed.

• When a parameter is alphanumeric it is always passed to the user program with the length defined in the data dictionary or defined by the DEFINE command.

• When a parameter is numeric it is passed in a packed decimal field of length determined by the NUM_LEN parameter. If the default of *ALL15 is specified then all numeric parameters will be passed in a packed decimal 15 digit field. The number of decimals passed will match the respective definition of the field for fields and system variables. For numeric literals the number of decimals will match the number specified in the literal (i.e. 12.34 will be passed as packed (15,2); 132 will be passed as packed (15,0)).

• If *DEFINED is specified then all numeric parameters will be passed in a packed decimal field with length and number of decimals as defined in the data dictionary or defined by the DEFINE command.

• The parameters returned by the user program will only be mapped back into the function if the parameter is a field. This prevents the user program from modifying the contents of system variables, alphanumeric literals, numeric literals or process parameters.