ILE COBOL Programmer's Guide

COBOL and PCML

A COBOL program can be called from a Java application using a Program Call Markup Language (PCML) source file that describes the input and output parameters for the COBOL program. The Java application can use PCML by constructing a ProgramCallDocument object with a reference to the PCML source file. See Programming->Java->IBM Toolbox for Java->Program Call Markup Language in the iSeries 400 Information Center at http://www.ibm.com/eserver/iseries/infocenter for more information on how to use PCML with Java. PCML handles the data type conversions between the COBOL format and the Java format.

The ILE COBOL compiler will generate PCML source for your COBOL program when you specify the PGMINFO(*PCML) compiler parameter along with the INFOSTMF compiler parameter to specify the name of an IFS output file to receive the generated PCML. PCML is generated based on the contents of the Procedure Division USING and GIVING/RETURNING phrases and the contents of the LINKAGE section in your COBOL program. Table 13 shows the support in PCML for the COBOL datatypes:

Table 13. COBOL Datatypes and Corresponding PCML Support

COBOL Data Type COBOL Format Supported in PCML PCML Data Type Length Precision Count
Character X(n) Yes character n

A(n) Yes character n

X(n) OCCURS DEPENDING ON M Yes structure

m
A(n) OCCURS DEPENDING ON m Yes structure

m
Numeric 9(n) DISPLAY Yes zoned decimal n 0
S9(n-p)V9(p) DISPLAY Yes zoned decimal n p
9(n-p)V9(p)
PACKED-DECIMAL
see note 3
Yes packed decimal n p
S9(n-p)V9(p)
PACKED-DECIMAL
see note 3
Yes packed decimal n p
9(4) BINARY
see notes 1, 2
Yes integer 2 16
S9(4) BINARY
see notes 1, 2
Yes integer 2 15
9(9) BINARY
see notes 1, 2
Yes integer 4 32
S9(9) BINARY
see notes 1, 2
Yes integer 4 31
S9(18) BINARY
see notes 1, 2
Yes integer 8 63
9(18) BINARY
see notes 1, 2
not supported



USAGE COMP-1 Yes float 4

USAGE COMP-2 Yes float 8

UCS2 N(n)
see note 4
Yes UCS-2/graphics n

N(n) OCCURS
DEPENDING ON m
see note 4
Yes structure

m
Graphic G(n) Yes UCS-2/graphics n

G(n) OCCURS DEPENDING ON M Yes structure

m
Index USAGE INDEX Yes integer 4 31
Boolean 1 not supported



Date FORMAT DATE not supported



Time FORMAT TIME not supported



Timestamp FORMAT TIMESTAMP not supported



Pointer USAGE POINTER not supported



Procedure Pointer PROCEDURE POINTER not supported



Notes:

  1. To reduce truncation, specify NOSTDTRUNC on the PROCESS statement. NOSTDTRUNC should always be specified when passing BINARY data items.

  2. BINARY, COMP-4, and COMPUTATIONAL-4 are equivalent and map to the same PCML.

  3. PACKED-DECIMAL, COMP-3, COMPUTATIONAL-3, COMP, and COMPUTATIONAL are equivalent and map to the same PCML (unless COMPASBIN PROCESS option is specified, see PROCESS Statement Options for more information).

  4. PIC N is a national (UCS2) item if USAGE NATIONAL is specified or if USAGE is not specified and the NATIONAL compiler option is specified, otherwise USAGE DISPLAY-1 (DBCS) is implied.

PCML will be generated for all parameters specifed in the PROCEDURE DIVISION header USING phrase. PCML will be generated for a parameter specified in the GIVING/RETURNING phrase for this header. An error will be issued if the GIVING/RETURNING item is not a 4 byte binary integer. Items specified in the USING phrase that are defined as "inputoutput" in the generated PCML can be used to return information to the calling program. For the calling program (eg JAVA program) to see the contents of the RETURN-CODE special register, the RETURN-CODE special register must be specified on the USING phrase of the PROCEDURE DIVISION header. The object data item for an OCCURS DEPENDING ON (ODO) must be defined in the linkage section and be specified as a parameter in the PROCEDURE DIVISION header USING phrase for PCML to be correctly generated for the ODO subject data item.

A PCML comment will be generated for renamed/redefined items.

Example:

The following is an example COBOL source program and corresponding PCML generated for this program:

Figure 60. PCML Source Program


 
 5722WDS V5R3M0  030905 LN  IBM ILE COBOL           TESTLIB/MYPCML         ISERIES1   03/09/15 12:09:25        Page      2
                                     S o u r c e
STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN  S COPYNAME  CHG DATE
     1     000100 IDENTIFICATION DIVISION.
     2     000200 PROGRAM-ID.     MYPGM4. 
           000300
     3     000400 DATA DIVISION.
     4     000500 WORKING-STORAGE SECTION.
     5     000600 01 RETN-VAL PIC S9(8) USAGE COMP-4. 
           000700
     6     000800 LINKAGE SECTION.
     7     000900 01 PARM-LIST. 
     8     001000    05 EMPL OCCURS 5 TIMES. 
     9     001100      10 NAMES      PIC A(20). 
    10     001200      10 ADDRESSES  PIC X(60). 
    11     001300      10 PHN-NUM    PIC 9(11) DISPLAY. 
    12     001400    05 NUM-1A     PIC S9(5)V9(3)  PACKED-DECIMAL. 
    13     001500    05 NUM-2A     PIC 9(5)V9(3)   COMP. 
    14     001600    05 TAB-NUM-3A PIC S9(5)V9(3)  COMP OCCURS 10 TIMES. 
    15     001700    05 NUM-4A     PIC 9(5)V9(3)   COMP-3. 
    16     001800    05 NUM-5A     PIC S9(5)V9(3)  COMP-3. 
    17     001900    05 NUM-6A     PIC 9(4)        BINARY. 
    18     002000    05 NUM-7A                     COMP-1. 
    19     002100    05 NUM-8A                     COMP-2. 
    20     002200    05 INTLNAME   PIC N(10)       NATIONAL. 
           002300
           002400***************************************************************
           002500* Test PCML for arrays of basic supported types.
           002600***************************************************************
    21     002700 PROCEDURE DIVISION USING BY REFERENCE PARM-LIST 
           002800     GIVING    RETN-VAL. 
           002900 MAIN-LINE.
    22     003000     MOVE 1 TO RETN-VAL. 
    23     003100     DISPLAY "THIS PGM TO BE CALLED BY A JAVA PGM". 
    24     003200     STOP RUN.
                           * * * * *   E N D   O F   S O U R C E   * * * * *
 
 
 

The following is an example of PCML that is generated when the program is compiled with options PGMINFO(*PCML) and INFOSTMF('/dirname/mypgm4.pcml') specified on the CRTBNDCBL command:

<pcml version="4.0">
 
   <!-- COBOL program: MYPCML  -->
   <!-- created: 02/03/21 12:09:25 -->
   <!-- source: TESTLIB/QCBLLESRC(MYPCML) -->
   <programname="MYPCML" path="/QSYS.LIB/TESTLIB.LIB/MYPCML.PGM" returnvalue="integer">
 
      <struct name="PARM-LIST" usage="inputoutput">
 
         <struct name="EMPL" usage="inherit" count="5">
 
            <data name="NAMES" type="char" length="20" usage="inherit">
            <data name="ADDRESSES" type="char" length="60" usage="inherit">
            <data name="PHN-NUM" type="zoned" length="11" precision="0" usage="inherit">
         </struct>
         <data name="NUM-1A" type="packed" length="8" precision="3" usage="inherit">
         <data name="NUM-2A" type="packed" length="8" precision="3" usage="inherit">
         <data name="TAB-NUM-3A" type="packed" length="8" precision="3" count="10"
usage="inherit">
         <data name="NUM-4A" type="packed" length="8" precision="3" usage="inherit">
         <data name="NUM-5A" type="packed" length="8" precision="3" usage="inherit">
         <data name="NUM-6A" type="int" length="2" precision="16" usage="inherit">
         <data name="NUM-7A" type="float" length="4" usage="inherit">
         <data name="NUM-8A" type="float" length="8" usage="inherit">
         <data name="INTLNAME" type="char" length="10" chartype="twobyte" ccsid="13488" usage="inherit">
      </struct>
      <data name="RETN-VAL" type="int" length="4" precision="32" passby="value"
usage="output">
   </program></pcml>


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]