ILSMARTLINKAGE

Exposes the linkage section and entry points in procedural COBOL programs to .NET COBOL code, by creating types.
Restriction: This directive is supported for .NET COBOL, but not native COBOL.

Syntax:

>>-.---.-.-------ILSMARTLINKAGE---.-------------.--.--------><
   +-/-+ |                        +-"namespace"-+  |
         +-----NOILSMARTLINKAGE--------------------+

Parameters:

namespace
The namespace in which each generated class is grouped

Properties:

Default: ILSMARTLINKAGE
Phase: Syntax check
$SET: Initial
IDE Equivalent: Check Expose group linkage items to managed code on the COBOL tab in the project's properties.

Comments:

This directive exposes linkage items to managed (.NET or Java) code. For each 01 level item (group or elementary), whose type is not a standard managed type (see Type Compatibility of .NET and JVM COBOL with Other Languages), and which is passed by reference either to the main program, or to a subsidiary entry point denoted by the ENTRY statement, an additional class is generated. The name of this class is the same as that of the 01 level linkage item.

The 01 level item itself, and all subsidiary items in the case of a group, are exposed as properties of this class, where the property is of a standard managed type. COBOL group items are exposed as string properties. If the group contains non-DISPLAY data (e.g. numeric COMP items), it will not be possible to use the property associated with the group to populate these non-DISPLAY items. In this case, these non-DISPLAY items must be populated using the individual properties associated with these non-DISPLAY items. Use of the ILSMARTRESTRICT directive suppresses generation of properties for group items, meaning that properties are only generated for elementary items.

Property names are derived from the data item name by removing hyphens and folding the letter following the hyphen to upper case. For example a data item author-name generates a property called AuthorName. You can also use the ILCUTPREFIX directive to remove initial portions of the name.

If the original, untransformed, COBOL names are duplicates (and can be made unique in COBOL by the use of qualification), then the property name generated is prefixed with a minimal set of qualifying names to make the resulting name unique, for example, in the case of:

01 link-rec.
   03 a1.
      05 b pic x.
   03 b1.
      05 b pic x.

The property names generated for the two elementary items b are a1_b' and a2_b.

However, if the original COBOL names differed, but only by the presence or absence of a'-' character, or by the presence of a prefix removed by the ILCUTPREFIX directive, then an error message is displayed during compilation (COBCH0842). If you receive such a message, modify the item names to ensure that they will be unique following transformation. For instance the following record layout will result in an error:

01 link-rec.
   03 a-b pic x.
   03 ab  pic x.

If a namespace is specified, all classes generated as a result of this directive are grouped under that namespace.

When a COBOL program is compiled to managed code, a method is generated for the main procedure division entry point, plus further methods for each subsidiary entry point denoted by the ENTRY statement. With ILSMARTLINKAGE, additional methods are generated for each entry point, in which the parameter types are instances of the ILSMARTLINKAGE types generated for the respective linkage records. These additional methods may then be called by, for example, a Java program, which has constructed instances of the ILSMARTLINKAGE types, and populated them by means of their properties.

The ILSMARTLINKAGE types, in addition to these properties, have another property called .Reference, which may be used to obtain a COBOL reference to the linkage data. This can be used when explicitly calling the call method in the run-time's RunUnit class - for example

myRunUnit.Call("myprogram", myByRefParam.Reference);

Example:

The following COBOL program is compiled with ILSMARTLINKAGE, ILCUTPREFIX(lnk-b-), ILCUTPREFIX(lnk-), and ILSMARTTRIM:

       program-id. BookLegacy.
						 ...
       linkage section.
       01 lnk-function            pic x.
       01 lnk-b-details.
          03 lnk-b-text-details.
             05 lnk-b-title       pic x(50).
             05 lnk-b-type        pic x(20).
             05 lnk-b-author      pic x(50).
          03 lnk-b-stockno        pic x(4).
          03 lnk-b-retail         pic 99v99.
          03 lnk-b-onhand         pic 9(5).
          03 lnk-b-sold           pic 9(5) comp-3.
       procedure division using by value lnk-function
                                by reference lnk-b-details.

In C#, you can access the data in BookLegacy program in .NET COBOL as follows:

    BookLegacy myBook = new BookLegacy(); 
         //creates an object corresponding to the BookLegacy program
    Details myDetails = new Details(); 
         //creates an instance corresponding to the group lnk-b-details 
    . . .          
       myDetails.Stockno = "6666";
       myDetails.Title = ".NET COBOL";
       myDetails.Author = "Mike Focus";
       myDetails.Type = "Reference";
       myDetails.Retail = 15.50M;
       myDetails.Onhand = 20;
       myDetails.Sold = 5;
       myBook.BookLegacy("2", myDetails);
         // calls the BookLegacy method with myDetails, 
         // which corresponds to the group item lnk-b-details

See the C# WinBook demonstration in the Visual COBOL samples for more.