Writing Virtual Field Derivation Code

Before attempting to write any virtual field derivation code several things should be understood:

• The code written is not a complete program. It will be automatically included at pre-defined points into the RPG file I/O module generated by LANSA when the file definition is made operational.

• The code written must adhere to certain restrictions if it is to work correctly.

When virtual field derivation code is to be input it must be input into one (or more) of the following "sections" of the file I/O module:

I/O Module Code Section Allowable RPG Type File specifications "F" specs Array specifications "E" specs External record format or field renames "I" specs Data structure specifications "I" specs Calculations after input from file "C" specs Calculations before output to file "C" specs Internal subroutines "C" specs Output specifications "O" specs Compile time array data N/Applicable

In addition, certain restrictions and considerations must be followed to ensure that the virtual field derivation code will compile and work correctly:

• Work field naming: where "work" fields (as opposed to real or virtual fields in the file definition) are used in the code they should be named in such a way as to not interfere with field names generated by LANSA in the I/O module or RDML function.
  
  Generally LANSA field names contain an "@" or a "$" symbol to make them different. Do not use work field names that contain an "@" or a "$" symbol.
  
  It is strongly recommended that a naming standard/convention for work fields used in virtual field derivation code be established so that their names never conflict with LANSA fields or other user defined fields.

• File field names and locations: all fields defined in the file definition (real and virtual) are renamed by LANSA within the I/O module. As such they cannot be referenced by their actual names unless a VC_USING command has been included into the code section.
  
  In addition, all fields in the file definition are placed into a data structure by LANSA. As such it is not possible for your code to group file fields into a data structure. This is not a problem as alternative code can always be used to achieve the same effect.
  
  Finally the "rename" name assigned to a file field and its location within the data structure is unpredictable and may change from compile to compile. As such, code written should never rely on a field having the same rename value or location in the data structure.

• LANSA fields: I/O modules contain many fields (other than file fields) that have been generated by LANSA. These fields should never be referred to or modified in user written code.
  
  This is for two reasons. The first is that modification of the variables may cause LANSA to fail in some way. The second is that they may change type or length, or disappear altogether in subsequent LANSA releases.

• Re-entrant code and robust logic: LANSA I/O modules are re-entrant programs (i.e. they do not set on LR) and do not use the RPG cycle. As such all code written should be capable of being used in a re-entrant mode and be as robust as possible.

• Indicator use: Avoid the use of indicators whenever possible other than in "short scope" situations (i.e. within the same coding section). Never use an indicator to pass information between coding sections as LANSA may change its value between them. No restrictions about which indicators can be used exist.

• Testing: Like all logic, virtual field code included in an I/O module should be tested. Often substantial testing can be performed by using the file maintenance utility. Refer to the File Maintenance Facility for more details.

• Performance: Remember that nothing is for free. If the virtual field derivation code uses up a lot of computer resource your applications will suffer accordingly.

• Responsibility: Remember that when virtual field derivation code is written its effect upon the functioning of an I/O module, an RDML function, and the LANSA product as a whole is entirely your responsibility.
  
  Although your product vendor will assist you with virtual field derivation code, they are not responsible for its function nor liable in any way to correct any problems it causes.

• Using virtual field derivation code with *DBOPTIMISE: A facility called *DBOPTIMIZE (or *DBOPTIMISE) exists that allows a compiled RDML function to directly include all required I/O code.
  
  This I/O code is used to perform database access directly, rather than by placing calls to I/O modules, to improve performance in some situations.
  
  The *DBOPTIMISE facility is described in detail in an appendix at the end of this guide. Please read this appendix before attempting to use this facility.
  
  This direct inclusion of I/O code into the RDML function can cause problems when coding virtual field derivation code.
  
  Consider the following situation: two files, A and B, both have common date conversion requirements, so the associated virtual field derivation code is copied from one to the other.
  
  The copied code includes a data structure ("I" Specs) and a subroutine ("C" specs).
  
  When I/O modules for these files are created, this all works okay, because the data structure and subroutine are isolated in two different I/O modules.
  
  However, if an RDML function, using *DBOPTIMISE, and accessing files A and B is compiled, it will fail. This is because the data structure and the subroutine would be included into the RDML function twice (once for each file).
  
  Fortunately, a command called VC_COPY can be used to indicate that a code block should only be copied into the RDML function if it has not already been copied. Refer to The VC_COPY Command for more information about this command.