Invoking the call stub generator from an Ant task

You can run the COBOL call stub generator from an Ant task.

Before you begin

Create a Rational® Application Developer project for the code that is generated by the COBOL call stub generator.

Create a call stub generator configuration file. Ensure that the settings for the EclipseHome, WorkSpace, and EclipseProjectName required properties are correct.

Check the PROCEDURE statement for the COBOL source file.

About this task

To run the COBOL call stub generator from an Ant task, you must create a <csg> task that specifies values for required attributes that identify the call stub generator configuration file and the COBOL source files that are used as source for the call stub generator. You also can specify values for optional attributes in the task. Table 1 describes supported <csg>, <cobolModule>, and <dataElement> attributes and nested elements that you can use in the <csg> task.

In some of the <csg> attributes and nested elements, you can specify internal call stub generator properties as substitution variables. For example, for the <callStubPackage> element, you can specify the COBOL PROGRAM-ID:
<callStubPackage>com.ibm.cobol.$_ProgramId_$</callStubPackage>
At run time, the $_ProgramId_$ variable is substituted with the COBOL PROGRAM-ID. If several COBOL files are specified by the input <fileset> or <filelist>, then $_ProgramId_$ is substituted with the PROGRAM-ID of each COBOL file as the call stub generator iterates over the input file list.
Table 1. <csg> attributes and elements to run the COBOL call stub generator. You must specify values for the required attributes and elements in the <csg> task. Many of the optional attributes and elements have a default value. The table first describes <csg> attributes and nested elements, then <cobolModule> attributes and a nested element, and finally <dataElement> attributes.
Name Default value Required or Optional Description
<csg> attributes and nested elements
configFile   Required Specifies the fully qualified path to the call stub generator configuration file.
workSpace   Optional Specifies the fully qualified path to the root directory of the Rational Application Developer or Eclipse workspace to be used to create the Java data binding class.

Any value that is specified for workSpace overrides the WorkSpace value in the call stub generator configuration file, which is identified by the configFile value.

eclipseProjectName   Optional Specifies the name of the project in the Rational Application Developer or Eclipse workspace that provides the home for the generated Java class.

The project must exist before running the call stub generator.

Any value that is specified for eclipseProjectName overrides the EclipseProjectName value in the call stub generator configuration file, which is identified by the configFile value.

antBuildFile ${workSpace}/${eclipseProjectName}/src/GenAllBindings.xml Optional Specifies the output location for the data binder Ant build file that is generated by the <csg> task.
<fileset>, <filelist>   Required Specifies one or more COBOL source files that provide input to the call stub generator. You can specify multiple <fileset> and <filelist> types. <fileset> and <filelist> types that are specified outside of a <cobolModule> element use the COBOL PROGRAM-ID as the COBOL module name.
<cobolModule>   Optional Specifies the name of the COBOL module or DLL file that is associated with all the <fileset> and <filelist> files that are nested within the <cobolModule> element. You can specify multiple <cobolModule> elements.
<callStubPackage>   Required Specifies the package name and the file path of generated file to use for the generated call stub.

For this element, you can specify an internal call stub generator property for the substitution variables $_ProgramId_$, the COBOL PROGRAM-ID, or $_CobolModule_$, the COBOL module.

For example: <callStubPackage>com.ibm.cobol.$_ProgramId_$</callStubPackage>

At run time, the $_ProgramId_$ variable is substituted with the COBOL PROGRAM-ID.

<callStubClass> COBOL program PROGRAM-ID Optional Specifies the class name to use for the generated call stub.

For this element, you can specify an internal call stub generator property for the substitution variables $_ProgramId_$, the COBOL PROGRAM-ID, or $_CobolModule_$, the COBOL module.

<build> Unknown Build Optional Specifies a user-assigned build identifier.
<mockPackage>   Optional Specifies the name of the package for the mock class.
<mockClass>   Optional Specifies the name of the class to use for the mock test harness.
<dataElementsPackage> {callStubPackage}.parameters Optional Specifies the package name to use for the data binding classes of one or more COBOL parameters and the return value.

For this element, you can specify an internal call stub generator property for the substitution variables $_DataElementName_$, the COBOL parameter name, $_ProgramId_$, the COBOL PROGRAM-ID, or $_CobolModule_$, the COBOL module.

<dataElementsClass> Parameter name Optional Specifies the class name to use for the data binding classes of one or more COBOL parameters and the return value.

For this element, you can specify an internal call stub generator property for the substitution variables $_DataElementName_$, the COBOL parameter name, $_ProgramId_$, the COBOL PROGRAM-ID, or $_CobolModule_$, the COBOL module.

For example, to prepend the PROGRAM-ID onto the class names for the COBOL parameters and return value: <dataElementsClass>$_ProgramId_$_$_DataElementName_$</dataElementsClass>

At run time, the $_ProgramId_$ variable is substituted with the COBOL PROGRAM-ID and the $_DataElementName_$ variable is substituted with the name of the COBOL parameter or return value. If the COBOL program has several parameters, then $_DataElementName_$ is substituted with the name of each COBOL parameter as the call stub generator iterates over them.

<dataElement>   Optional Specifies a package and class name for a COBOL parameter or return value. The parameter is identified using the name and programId attributes. The package and class names are specified using the packageName and className attributes. You can specify multiple <dataElement> elements.
<cobolModule> attributes and nested element
libname COBOL program PROGRAM-ID Optional Specifies the name of the COBOL module or DLL file that contains one or more COBOL programs.
<fileset>, <filelist>   Required Specifies one or more COBOL source files that provide input to the call stub generator. Each COBOL file is associated with the COBOL module that is defined by libname.
<dataElement> attributes
name   Required Specifies the name of the COBOL PROCEDURE parameter.
programId   Required Specifies the PROGRAM-ID of the COBOL program that contains the parameter.
packageName ${callStubPackage}.parameters Optional Specifies the package name to use for the data binding class for this COBOL parameter or return value.

For this attribute, you can specify an internal call stub generator property for the substitution variables $_DataElementName_$, the COBOL parameter name, $_ProgramId_$, the COBOL PROGRAM-ID, or $_CobolModule_$, the COBOL module.

className Parameter name Optional Specifies the class name to use for the data binding class for this specific COBOL parameter or return value.

For this attribute, you can specify an internal call stub generator property for the substitution variables $_DataElementName_$, the COBOL parameter name, $_ProgramId_$, the COBOL PROGRAM-ID, or $_CobolModule_$, the COBOL module.

Procedure

  1. Define an Ant <csg> task to run the call stub generator.

    The call stub generator provides a sample Ant build file, CSG.xml, that you can modify and use. See the topic about the call stub generator CSG.xml file.

  2. Use an Ant build file to run the call stub generator.

    The Ant build file starts the data binder and generates the data binding classes for one or more COBOL parameters and a return value. The data binder Ant build file is run on the last line using the <ant> task.

    The following code runs the call stub generator using the <csg> task:

    <!-- Declare the <csg> task -->
    <taskdef resource="com/ibm/ws/batch/cobol/ant/callstub/antlib.xml"
             classpath="${csgDir}/lib/COBOLCallStubGenerator.jar"/>
    
    <csg configFile="${csgDir}/csg.properties" antBuildFile="${antBuildFile}" >
    
      <!-- Input can be a <fileset> or <filelist>. In this example, it is a single file fileset. -->
    <fileset file="${cobolSource}" />
    
    <!-- Specify the package for the generated Java call stub class. 
         The parameter classes are generated under ${callStubPackage}.parameters. -->
      <callStubPackage>${callStubPackage}</callStubPackage>
      
    </csg>
    
    <!-- Run the data binder Ant build file that is generated by the <csg> task. -->
    <ant antfile="${antBuildFile}" />

    In this example, a <fileset> type is used to specify a single input COBOL source file. COBOL source files used as input to <csg> are specified using one or more <fileset> or <filelist> types. The nested <callStubPackage> element is required. It specifies the package to use for the Java call stub. The data binding classes are generated by default under the ${callStubPackage}.parameters package.

    The following example provides a full description of the <csg> task:

    <taskdef resource="com/ibm/ws/batch/cobol/ant/callstub/antlib.xml"
             classpath="${csgDir}/lib/COBOLCallStubGenerator.jar"/> 
    
    <csg configFile="#REQUIRED"
         workSpace="#OPTIONAL:overrides value in configFile"
         eclipseProjectName="#OPTIONAL:overrides value in configFile"
         antBuildFile="#OPTIONAL:default=${workSpace}/${eclipseProjectName}/src/GenAllBindings.xml" >
    
      <fileset />
    <filelist />
    
    <cobolModule #OPTIONAL libname="#OPTIONAL:default=${ProgramId}">
      <fileset />
      <filelist />
    </cobolModule>
    
      <callStubPackage>#REQUIRED</callStubPackage>
    <callStubClass>#OPTIONAL:default=${ProgramId}</callStubClass>
    
    <build>#OPTIONAL:default=”Unknown Build”</build>
    <mockPackage>#OPTIONAL</mockPackage>
    <mockClass>#OPTIONAL</mockClass>
    
      <dataElementsPackage>#OPTIONAL:default=${callStubPackage}.parameters</dataElementsPackage>
      <dataElementsClass>#OPTIONAL:default=${dataElementName}</dataElementsClass>
    
      <dataElement #OPTIONAL
                   name="#REQUIRED" 
                   programId="#REQUIRED" 
                   packageName="#OPTIONAL:default=${callStubPackage}.parameters" 
                   className="#OPTIONAL:default=${dataElementName}" />
    </csg>
    Best practice Best practice: The <csg> task and the data binder Ant build file have runtime dependencies on some Eclipse classes, including the Java EE Connector (J2C) tools. Run the <csg> task within Rational Application Developer as an Ant build to obtain all the prerequisites. You also can use CSG.xml to run the call stub generator within Rational Application Developer. See the topic about invoking the call stub generator using the graphical interfacebprac

Results

The command runs the call stub generator. If the command is successful, the call stub generator creates a Java call stub to run a COBOL program.

What to do next

Use the generated Java call stub to run a COBOL program.

Task topic    

Terms and conditions for information centers | Feedback

Last updated: April 17, 2014 10:32 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-express-iseries&topic=tgrid_cobol_csg_ant
File name: tgrid_cobol_csg_ant.html