Function Routing in detail

Date:Archived
Product/Release:LANSA for Windows and LANSA for the AS/400
Abstract:This tip provides a more detailed view of Function Routing in LANSA and how to use it.
Submitted By:LANSA Technical Support

Function Routing is supported in LANSA release 7.0. The concept is very simple - at run time one RDML function, for example function A, is automatically replaced by another function, for example function A1. This automatic replacement of function A by function A1 is determined by the Function Routing Table.

The automatic routing facility has been provided for software vendors who ship applications to customers and then proceed to customize or tailor parts of the application to exactly match customer requirements.

For example, with a basic function A and a customized version A1, all calls of function A to function A1 can be automatically rerouted by altering the Function Routing Table.

The biggest advantage to using this approach is that the original function stays intact and the customized versions can be modified to match unique customer requirements.

What is the Function Routing Table?

The Function Routing Table is a very simple source file called X_FUNRTR (AS/400) or X_FUNRTR.DAT (PC). It specifies how functions should be automatically routed.

Source lines in this file can be input via the standard editors (SEU on the AS/400, E.EXE or EPM.EXE on the PC) and has the following format:

fffffff,ttttttt

where 'fffffff' specifies the 'from' function name and 'ttttttt' specifies the 'to' function name.

For example , the entries:

A,A1
B678V40,B678V42

specify that calls to function A should be routed to call function A1 and function B678V40 to B678V42.

Of course, it is assumed that the functions A/A1 and B678V40/B678V42 have identical entry characteristics (such as number of parameters, type of parameters, etc.).

How is a Function Routing Table created?

On the AS/400

  1. Use the AS/400 command CRTSRCPF to create a standard AS/400 source file named X_FUNRTR in the associated partition's module library. Cause a single member called X_FUNRTR to be added to the file.
  2. Use the OS/400 command CHGOBJOWN (Change Object Owner) to change the owner of the source file just created to be the LANSA System owner (usually QOTHPRDOWN).

On the PC

  1. The table will be automatically created when it is edited. There is no need to independently create it.

Editing a Function Routing Table

On the AS/400

  1. Use the OS/400 command STRSEU to edit the source file X_FUNRTR (member X_FUNRTR) in the associated partition module library.

On the PC

  1. Use the standard source file editor (E or EPM) to edit the file X_FUNRTR.DAT in the source directory of the associated partition. For example: C:\X_LANSA\X_ppp\SOURCE\X_FUNRTR.DAT - where ppp is the partition identifier.

Some rules

  1. Function Routing Tables must reside in the partition's module library (AS/400 applications) or source directory (PC applications). If the routing table is not placed into the correct library/directory, then its existence will not be recognized.
  2. Function routings are partition based and only apply to the partition that is associated with the routing table.
  3. Only a single function routing can be specified per line, in the form fffffff,ttttttt in a Function Routing Table.The 'from' function name must begin in column 1. It must be immediately followed by a single comma which in turn must be followed by the 'to' function name. No other information can be included in the routing entry line. Entries that do not follow these formatting rules will be ignored and no exception issued.
  4. The from and to function names must be specified in UPPERCASE characters .
  5. Up to 4500 entries can be specified in the Function Routing Table (comment lines are not included). Entries beyond 4500 are ignored and no warning or error message is issued. The limit of 4500 is due to the 64K memory limit for Windows 3.1 applications.
  6. The use of reserved names such as EXIT, EOJ, RETRN, ERROR, HELP, SELECT, Cn, Fn or Pn, where 'n' is in the range 1 to 999999, and the function names such as 'to' and 'from' is not allowed.
  7. Comment lines can be included in a Function Routing Table. This is achieved by placing the character '*' in column1.

    Example:
    * Route all standard reports to tailored versions
    GLR01,GLR0101
    GLR02,GLR0201
    GLR03,GLR0301
    * End of Routing Table
     
  8. The Function Routing Table is loaded into memory when the AS/400 LANSA command, or the PC X_RUN command, is invoked. This is done to optimize access to the routing table. It also means that any changes will only take effect when the LANSA or X_RUN command is re-invoked.
  9. The Function Routing Table is looked up just once for a 'from' function to find a function. Once a function has been located, it is not looked up again, thus you cannot form routing chains.

    Example:
    A,A1
    A1,A2

    will route a direct reference of A to A1 and a direct reference of A1 to A2. It will not reference of A to A2.

Verifying the contents of a Routing Table

While all these rules may seem complex, a facility is provided that allows the verification of the contents of an FRT (Function Routing Table) after it has been updated.

On the AS/400

Use the command LANSA REQUEST(VERIFYFRT) PARTITION(ppp). This command will produce a spool file (QSYSPRT) that details the verification of the updated Routing Table.

On the PC

Use the command X_RUN PROC=*VERIFYFRT PART=DEM USER=etc. This program will produce a display that details the verification of your updated FRT.

All messages should be reviewed in the spoolfile/displayed, and if required, take corrective action before running the verification process again.

What type of functions can be (re)routed?

Only the following types of functions, under the following rules, circumstances and guidelines can be automatically re(routed) via the Function Routing Table:

  • Functions invoked from an SAA/CUA style menu:
    providing that the 'to' function belongs to the same process as the 'from' function. Only the 'from' function should appear on the menu, the 'to' function should have 'NO' for the option 'Display on menu'.
  • Functions invoked from an ACT/BAR style menu:
    providing that the 'to' function belongs to the same process as the 'from' function. Only the 'from' function should appear in the action bar. Normally, the 'to' function is not attached to the action bar itself, but it effectively 'adopts' the action bar and pull down option codes as the 'from' function.
  • Functions invoked by a CALL(process) FUNCTION(function):
    providing that the 'to' function belongs to the same process as the 'from' function.
  • Functions invoked by a CALL(*DIRECT) FUNCTION(function):
    in all circumstances. This includes RDML functions called from client based LANSA/Server and LANSA for Windows applications.
  • Batch functions invoked by SUBMIT:
    providing that the 'to' function belongs to the same process as the 'from' function.
  • Functions invoked by the F4=Prompt key:
    in all circumstances
  • System variable functions:
    in all circumstances
  • Data dictionary validation functions:
    in all circumstances
  • Trigger functions:
    in all circumstances

How is the Function Routing Table used?

When a LANSA application is started via the LANSA command (on the AS/400) or the X_RUN command (on the PC) a check is made for the existence of the file X_FUNRTR in the library or directory associated to the selected partition.

If a version of the file is found, its entries are loaded into memory and sorted to optimize search time. Finally a system wide flag is set to indicate that function routing is in effect. The setting of this flag is important since each function call in LANSA is sensitive to this flag. Only when the flag is set are the entries searched so that no significant performance impact occurs if function routing is not being used (apart from checking the flag). However, when function routing is used, a performance impact results because the function name has to be looked up in the routing entries.