Invoking the call stub generator from an Ant task

Invoking the call stub generator from an Ant task

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

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.

To run the COBOL call stub generator from an Ant task, create a <csg> task that specifies values for required attributes that identify the call stub generator configuration file and the COBOL source files 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 we can use in the <csg> task.
In some of the <csg> attributes and nested elements, we can specify internal call stub generator properties as substitution variables. For example, for the <callStubPackage> element, we 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.

call stub generator. Specify values for the required attributes and elements in the <csg> task. Many of the optional attributes and elements have a default
Name Default value Required or Optional Description
<csg> attributes and nested elements
configFile
Required Fully qualified path to the call stub generator configuration file.
workSpace
Optional 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 specified for workSpace overrides the WorkSpace value in the call stub generator configuration file, which is identified by the configFile value.
eclipseProjectName
Optional 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 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. We can specify multiple <fileset> and <filelist> types. <fileset> and <filelist> types specified outside of a <cobolModule> element use the COBOL PROGRAM-ID as the COBOL module name.
<cobolModule>
Optional 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. We can specify multiple <cobolModule> elements.
<callStubPackage>
Required Package name and the file path of generated file to use for the generated call stub.
For this element, we 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 Class name to use for the generated call stub.
For this element, we 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 User-assigned build identifier.
<mockPackage>
Optional Name of the package for the mock class.
<mockClass>
Optional Name of the class to use for the mock test harness.
<dataElementsPackage> {callStubPackage}.parameters Optional Package name to use for the data binding classes of one or more COBOL parameters and the return value.
For this element, we 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 Class name to use for the data binding classes of one or more COBOL parameters and the return value.
For this element, we 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. We can specify multiple <dataElement> elements.
<cobolModule> attributes and nested element
libname COBOL program PROGRAM-ID Optional Name of the COBOL module or DLL file containing 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 defined by libname.
<dataElement> attributes
name
Required Name of the COBOL PROCEDURE parameter.
programId
Required Specifies the PROGRAM-ID of the COBOL program containing the parameter.
packageName ${callStubPackage}.parameters Optional Package name to use for the data binding class for this COBOL parameter or return value.
For this attribute, we 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 Class name to use for the data binding class for this specific COBOL parameter or return value.
For this attribute, we 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.
Define an Ant <csg> task to run the call stub generator.
The call stub generator provides a sample Ant build file, CSG.xml, we can modify and use. See the topic about the call stub generator CSG.xml file.
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:

<taskdef resource="com/ibm/ws/batch/cobol/ant/callstub/antlib.xml"
         classpath="${csgDir}/lib/COBOLCallStubGenerator.jar"/>
 <csg configFile="${csgDir}/csg.properties" antBuildFile="${antBuildFile}" >
   
<fileset file="${cobolSource}" />
 
  <callStubPackage>${callStubPackage}</callStubPackage>
   </csg>
 
<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: 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.

Related tasks

Generating COBOL call stubs
Create a call stub generator configuration file
Invoking the call stub generator from a graphical interface

Call stub generator CSG.xml file
Call stub generator CSGBatch.xml file

Name	Default value	Required or Optional	Description
<csg> attributes and nested elements
configFile		Required	Fully qualified path to the call stub generator configuration file.
workSpace		Optional	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 specified for workSpace overrides the WorkSpace value in the call stub generator configuration file, which is identified by the configFile value.
eclipseProjectName		Optional	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 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. We can specify multiple <fileset> and <filelist> types. <fileset> and <filelist> types specified outside of a <cobolModule> element use the COBOL PROGRAM-ID as the COBOL module name.
<cobolModule>		Optional	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. We can specify multiple <cobolModule> elements.
<callStubPackage>		Required	Package name and the file path of generated file to use for the generated call stub. For this element, we 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	Class name to use for the generated call stub. For this element, we 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	User-assigned build identifier.
<mockPackage>		Optional	Name of the package for the mock class.
<mockClass>		Optional	Name of the class to use for the mock test harness.
<dataElementsPackage>	{callStubPackage}.parameters	Optional	Package name to use for the data binding classes of one or more COBOL parameters and the return value. For this element, we 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	Class name to use for the data binding classes of one or more COBOL parameters and the return value. For this element, we 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. We can specify multiple <dataElement> elements.
<cobolModule> attributes and nested element
libname	COBOL program PROGRAM-ID	Optional	Name of the COBOL module or DLL file containing 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 defined by libname.
<dataElement> attributes
name		Required	Name of the COBOL PROCEDURE parameter.
programId		Required	Specifies the PROGRAM-ID of the COBOL program containing the parameter.
packageName	${callStubPackage}.parameters	Optional	Package name to use for the data binding class for this COBOL parameter or return value. For this attribute, we 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	Class name to use for the data binding class for this specific COBOL parameter or return value. For this attribute, we 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.