The VC_USING Command

In Writing Virtual Field Derivation Code it was mentioned that all file fields (both real and virtual) are renamed by LANSA within an I/O module.

This is done for 2 reasons:

1.A field name might be the same in another file (i.e. validation file, batch control file, etc). If the field was not renamed the possibility of "over-writing" the field would arise.

2.The field name in the file might be more than 6 characters long. Although LANSA supports 10 character field names RPG does not. They must be renamed.

Thus you are unable to reference real or virtual fields in your code by their actual names. However, this problem is overcome by the VC_USING (virtual code using fields) command which can be inserted into the RPG code sections as comments.

The VC_USING command tells LANSA what file fields (real or virtual) are used in the following section of code, and optionally what "name" is being used to represent the field in the following code. Thus LANSA can scan the source lines and replace any occurrences of the field name with its "rename" name when generating the I/O module.

The syntax diagram for the VC_USING command looks like this:

                                                         Required 

VC_USING ----- FIELDS ------- field name ---- *SAME -------------| 

                           |                  name used   |     

                           |                              |     

                            --------- 100 maximum --------     

                                                                  

FIELDS

Specifies a list of 1 to 100 fields that are defined in the file definition and optionally the name used in the user RPG code to represent the field.

Some points to note about using VC_USING commands are:

• If the maximum of 100 fields is exceeded the virtual fields are not calculated (derived). There is no runtime error.

• They can be inserted into any I/O module code section except "Compile time array data".

• The command and its parameters should only ever be coded between columns 8 -> 80 of the source program line. LANSA ignores columns 1 -> 7 of the line when processing a VC_USING command and its parameters.

• Where a command and its parameters will not fit on one line use a "+" sign as the last character on the line and continue the command in column 8 (or beyond) on the next line. This method is identical to that used when continuing IBM i operating system commands over multiple lines. Note that the "-" sign continuation character supported by the IBM i is NOT supported by LANSA in this context.

• The VC_USING command causes the RPG code that you write to be translated for compilation purposes.

Following further on in this section are detailed examples of how this is done and the effect that it has on your RPG virtual derivation code (as it is actually compiled).

One of the most common problems that occurs when using virtual code is that VC_USING command uses simple scanning to find and replace fields in the RPG code.

This can cause problems when different field names are generically identical, or when they are imbedded within one another.

For example:

C*

C* VC_USING FIELDS(COMP COMPNO)

C*

C                     Z-ADDCOMP      FIELD1

C                     Z-ADDCOMPNO    FIELD2

which would be translated at compile time to:

* FIELD REPLACEMENT VALUES USED FOR THIS SECTION OF USER CODE

*

*  Field name as     Field name as in   Internal field name

*in file definition  user RPG code       used as replacment

*------------------  ----------------   ------------------

*     COMP               COMP               @F0001

*     COMPNO             COMPNO             @F0002

*

C                   Z-ADD@F0001    FIELD1

C                   Z-ADD@F0001    FIELD2

which is incorrect because the names COMP and COMPNO have generically identical portions (i.e. "COMP"). The scanning logic always looks for "COMP" first, so it has replaced it in both lines of code.

The simplest solution is to make the scanning logic look for "COMPNO" first:

C*

C* VC_USING FIELDS(COMPNO COMP)

C*

C                     Z-ADDCOMP      FIELD1

C                     Z-ADDCOMPNO    FIELD2

which would be translated correctly at compile time to:

** FIELD REPLACEMENT VALUES USED FOR THIS SECTION OF USER CODE

*

*  Field name as     Field name as in   Internal field name

*in file definition  user RPG code       used as replacment

*------------------  ----------------   ------------------

*     COMPNO             COMPNO             @F0002

*     COMP               COMP               @F0001

*

C                     Z-ADD@F0001    FIELD1

C                     Z-ADD@F0002    FIELD2

But the best solution is to remove the generic similarities altogether like this:

C*

C* VC_USING FIELDS((COMP XXXX) (COMPNO YYYYYY))

C*

C                     Z-ADDXXXX      FIELD1

C                     Z-ADDYYYYYY    FIELD2

This variation of the command tells LANSA that field COMP is being used, but it has been referenced (and should be scanned for) as XXXX, and that field COMPNO is being used, but it is referenced (and should be scanned for) as YYYYYY.

It would produce a correct result like this:

  *

  * FIELD REPLACEMENT VALUES USED FOR THIS SECTION OF USER CODE

  *

  *  Field name as     Field name as in   Internal field name

  * n file definition  user RPG code      used as replacement

  * -----------------  ----------------   ------------------

  *     COMP               XXXX               @F0001

  *     COMPNO             YYYYYY             @F0002

  *

    C                     Z-ADD@F0001    FIELD1

    C                     Z-ADD@F0002    FIELD2

Another common variation of this problem is the imbedding of field names within one another. This example shows some other situations that would cause this problem and require corrective action:

    C*

    C* VC_USING FIELDS(COMPNO FXCO CO)

    C*

    C                     Z-ADDCOMPNO    FIELD1

    C                     Z-ADDCO        WORKCO

    C                     Z-ADDFXCO      WFXCO1

which would be incorrectly translated like this:

  *  Field name as     Field name as in   Internal field name

  *in file definition  user RPG code       used as replacement

  *------------------  ----------------   ------------------

  *     COMPNO             COMPNO             @F0001

  *     FXCO               FXCO               @F0002

  *     CO                 CO                 @F0003

  *

    C                     Z-ADD@F0001    FIELD1

    C                     Z-ADD@F0003    WORK@F0003

    C                     Z-ADD@F0002    W@F0002