
	Version 2.3.1.18	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— SAP R/3 Gateway Documentation —

COBOL IDoc Client

This section describes all of the development steps required to create a COBOL IDoc client. This client creates messages for the IDoc inbound pipeline. The same interface is provided for Natural.

To setup the Development

The development page (http://YourGateway:8080/sapr3idocxmlgateway/transformer/IDocType_ToFile or menu item Development) provides an IDL text editor and the associated batch commands to develop a COBOL PMQ Client. To setup this page, use the setup IDoc XML Gateway wizard on http://YourGateway:8080/sapr3gateway/manager/setupWizardIDocXMLGW#12 and perform step 12 Create COBOL IDoc PMQ Development Environment.

To create a COBOL IDoc Client

Create the IDoc type information for your client on http://YourGateway:8080/sapr3idocxmlgateway/transformer/IDocType_ToFile or use the menu items Go , IDoc XML Gateway and Development.

Use the Minimum IDL link to open the IDL for a COBOL IDoc client in a new browser window.

The IDoc type DEBCOR01 returns the following IDL:

Program 'DEBCOR01':'DEBCOR01' Is
  Define Data Parameter
    1 EDI_DC40 IN /* IDoc control record
      2 MESTYP  (A30)   /* Message type
      2 SNDPRT  (A2)    /* Partner type of sender
      2 SNDPRN  (A10)   /* Partner number of sender
    1 E1KNA1C IN   /*   (Must=X, OccMin=1, OccMax=9999, GMust=, GOccMin=0, GOccMax=0) Core master customer master basic data (KNA1)
      2 MSGFN (A3)        /* Function
      2 KUNNR (A10)        /* Customer number
      2 ANRED (A15)        /* Title
      2 KTOKD (A4)        /* Customer Account Group
      2 LOEVM (A1)        /* Central Deletion Flag for Master Record
      2 NAME1 (A35)        /* Name 1
      2 NAME2 (A35)        /* Name 2
      2 ORT01 (A35)        /* City
      2 ORT02 (A35)        /* District
      2 PFACH (A10)        /* P.O. Box
      2 PSTL2 (A10)        /* P.O. Box postal code
      2 PSTLZ (A10)        /* Postal Code
      2 SORTL (A10)        /* Sort field
      2 STRAS (A30)        /* House number and street
      2 LAND1 (A3)        /* Country key
      2 SPRAS (A1)        /* Language key
      2 SPRAS_ISO (A2)        /* Language according to ISO 639
  End-Define

Mark and copy the contents of the browser window to your clipboard.
Start the developer editor for COBOL PMQ client on the development page http://YourGateway:8080/sapr3gateway/manager/dev. This development environment is created by the Setup Wizard IDoc XML Gateway (http://YourGateway:8080/sapr3gateway/manager/setupWizardIDocXMLGW).
Paste the clipboard contents to the end of the edit IDL.
Change the 8-character short name of the program statement. In the DEBCOR01 example, you can change it to DEBCOR. The starting test program will have the name DEBCORP.
Click the Save button.
Click Generate Source. Return code 0 indicates a successful generation process.

Use COBOL Source to browse the generated files. All subprograms of the PMQ interface have the prefix PMQ and for all IDoc types the same. The other file names depend on the name of the IDoc type. Following files are generated, for example with DEBCOR as IDoc type:

File	Description
PMQBCKT	Disable the document delivery. Backout an allocated Unit of Work.
PMQCMMT	Commits and closes the created document as Unit of Work.
PMQINFO	Returns status and error information of current allocated Unit of Work.
PMQINIT	Initializes the PMW environment and set the connection parameter.
PMQOPEN	Starts a new document stream as Unit of Work.
PMQCOPY	Copy code for general PMQ parameter and status interface..
DEBCORP	Example program to deliver a complete debitor (DEBCOR) as document.
DEBCOR	Writes IDoc header information of DEBCOR in to the opened document stream.
E1KNA1C	Writes IDoc business data of a debitor in to the opened document stream.
DEBCORC	Copy code of DEBCOR business IDoc interface.

Transport the generated source code files to your COBOL development environment. When you press the Generate Source button, an FTP batch comand file (ftp.bat for Windows) or a shell script (ftp.sh for UNIX) is generated. This command script transports the generated source code files with FTP to your target file system. By default, the execution of this script is uncommended. To apply the transport, you need the parameter IP/DNS name of target host, FTP user ID, password and target directory (optional). As well, you can change the target COBOL enviromnent BATCH or CICS.

To set the parameter, go Configuration, Development and select COBOL IDoc PMQ Client. The Make startup script link starts an editor. The default script for Windows:
```
@echo off

rem Set target Cobol environment
set TARGET=BATCH
rem set TARGET=CICS

%EXXDIR%/bin/erxidl -DTARGET=%TARGET% -t CobolPMQClient.tpl %IDL%
%EXXDIR%/bin/erxidl -DSHELL=BAT       -t ftp.tpl            %IDL%

rem Upload Cobol source
rem ftp.bat host userid password directory
```
The default script for UNIX:
```
#!/bin/sh

PATH=/bin:/usr/bin:$PATH
export PATH

# Set Environment for SAG-Environment
echo Call $SAGENV
. $SAGENV

# Set target Cobol environment
TARGET=BATCH
# TARGET=CICS

$EXXDIR/$EXXVERS/bin/erxidl -DTARGET=$TARGET -t CobolPMQClient.tpl $IDL
$EXXDIR/$EXXVERS/bin/erxidl -DSHELL=SH       -t ftp.tpl            $IDL

# Upload Cobol source
# ./ftp.sh host userid password directory
```
Compile the uploaded sources in your COBOL development environment. The first time, you must compile the subprogram with prefix PMQ. The next time, only the new programs and subprograms of the IDoc type are required for compilation.

Start the program to edit the example with the same IDoc type name. In this example: DEBCORP. See inbound configuration of partner profile for more parameter values.

       ID DIVISION.
       PROGRAM-ID.   DEBCORP.

      *----------------------------------------------------------------*
      * Copyright (c) 2004 by SAG Systemhaus GmbH. All rights reserved.
      * SAP R/3 Gateway
      * Version: 2.3.1
      * This program use the defined interface to create
      * a Unit of Work as document.
      *----------------------------------------------------------------*
       ENVIRONMENT DIVISION.

       CONFIGURATION SECTION.
       SPECIAL-NAMES.
           CONSOLE IS MY-TERMINAL.

       DATA DIVISION.

      * --- WORKING ----------------------------------------------------
       WORKING-STORAGE SECTION.

      * PMQ STANDARD INTERFACE
       01  PMQ-SERVICE.
           02  PMQ-BROKER-ID             PIC X(32).
           02  PMQ-SERVER-CLASS          PIC X(32).
           02  PMQ-SERVER-NAME           PIC X(32).
           02  PMQ-SERVICE-NAME          PIC X(32).
           02  PMQ-USERID                PIC X(32).
           02  PMQ-PASSWORD              PIC X(32).
           02  PMQ-TOKEN                 PIC X(32).
       01  PMQ-RETURN.
           02  PMQ-OK                    PIC X(1).
           02  PMQ-MESSAGE               PIC X(40).
           02  PMQ-CODE                  PIC X(8).
           02  PMQ-CONV-ID               PIC X(16).
           02  PMQ-UOW-ID                PIC X(16).


      * DOCUMENT INTERFACE
       01 EDI-DC40.
           10 MESTYP-1   PIC X(30).
           10 SNDPRT-2   PIC X(2).
           10 SNDPRN-3   PIC X(10).
       01 E1KNA1C.
           10 MSGFN-4   PIC X(3).
           10 KUNNR-5   PIC X(10).
           10 ANRED-6   PIC X(15).
           10 KTOKD-7   PIC X(4).
           10 LOEVM-8   PIC X(1).
           10 NAME1-9   PIC X(35).
           10 NAME2-10   PIC X(35).
           10 ORT01-11   PIC X(35).
           10 ORT02-12   PIC X(35).
           10 PFACH-13   PIC X(10).
           10 PSTL2-14   PIC X(10).
           10 PSTLZ-15   PIC X(10).
           10 SORTL-16   PIC X(10).
           10 STRAS-17   PIC X(30).
           10 LAND1-18   PIC X(3).
           10 SPRAS-19   PIC X(1).
           10 SPRAS-ISO-20   PIC X(2).

       PROCEDURE DIVISION.

      * INIT PMQ INFO AND CONNECTION PARAMETER
           INITIALIZE PMQ-SERVICE, PMQ-RETURN.

      * INIT DOCUMENT INTERFACE
           INITIALIZE EDI-DC40.
           INITIALIZE E1KNA1C.

      * DO NEXT INIT CALL ONCE IN THE SESSION
           CALL 'PMQINIT' USING PMQ-SERVICE, PMQ-RETURN.

      * DO NEXT OPEN CALL FOR EACH UNIT OF WORK
           CALL 'PMQOPEN' USING PMQ-SERVICE, PMQ-RETURN.
...

Set all fields with the values that are necessary for your client

...
      * SET VALUES

      *  USING GROUP EDI-DC40
           MOVE 'DEBCOR' TO MESTYP-1.
           MOVE 'LS' TO SNDPRT-2.
           MOVE 'SRG' TO SNDPRN-3.

      *  USING GROUP E1KNA1C
           MOVE '005' TO MSGFN-4.
...

Make no changes to document sending and error handling:

      * WRITE 'EDI-DC40' GROUP INTO THE STREAM
           CALL 'DEBCOR' USING EDI-DC40.

      * WRITE 'E1KNA1C' GROUP INTO THE STREAM
           CALL 'E1KNA1C' USING E1KNA1C.

      * COMMIT AND CLOSE STREAM
           CALL 'PMQCMMT'.

      * ASK FOR STREAM INFORMATION
           CALL 'PMQINFO' USING PMQ-SERVICE, PMQ-RETURN.

      * CHECK UOW
           DISPLAY 'Send document to Broker: ' PMQ-BROKER-ID.
           IF PMQ-OK = 1
             DISPLAY 'CONV-ID:' PMQ-CONV-ID
             DISPLAY 'UOW-ID :' PMQ-UOW-ID
           ELSE
             DISPLAY 'CODE   :' PMQ-CODE
             DISPLAY 'MESSAGE:' PMQ-MESSAGE
           END-IF.

       MAIN-EXIT.
           STOP RUN.

       END PROGRAM DEBCORP.

Set the connection parameter BROKER-ID to the inbound pipeline in the generated subprogram PMQINIT.

...
       INIT-USER-DEFINED-PMQ-PARAM.

      * SET QUEUE CONNECTION PARAMETER
           MOVE 'localhost'         TO PMQ-BROKER-ID.
           MOVE 'INBOUND-IDOC-XML'  TO PMQ-SERVER-NAME.
           MOVE 'QUEUE'             TO PMQ-SERVER-CLASS.
           MOVE 'TEST'              TO PMQ-SERVICE-NAME.

           MOVE 'PMQ'               TO PMQ-USERID.
           MOVE ' '                 TO PMQ-PASSWORD.
...

To set the connection parameter on generation process, the following parameters can set with -D KEY=VALUE syntax in the make command.

Key Parameter	Value Description	Default Value
SUPPRESS	The value `PMQINIT` suppresses the generation of this subprogram.
BROKER	Sets the value for Broker ID.	localhost
CLASS	Sets the value for class name.	QUEUE
SERVER	Sets the value for server name.	INBOUND-IDOC-XML
SERVICE	Sets the value for service name.	TEST
USERID	Log on with this user ID as client .	PMQ
TOKEN	Log on with this user ID and token as unique client.
PASSWORD	User ID's password with EntireX Security.

To change the make command for setting parameters, go to Configuration, Development, Natural PMQ Client, Make startup script menu item and edit the command line in the text editor.

...bin/erxidl -D BROKER=ETB001 -D FILE=PMQ.txt -t NatPMQClient.tpl $IDL

This example (on UNIX) sets the Broker ID to value ETB001 and overwrites the default.

Run the test program. The test program writes the conversation ID and UOW ID to the output.
Go to the inbound pipeline and display the processing status.
Start the transaction we02 to display the inbound IDoc in the SAP application server. Make sure that the inbound partner profile is configured.

To change the IDoc interface

There are cases in which the IDoc interface may be changed and cases in which it must be changed. Use the following rules during the development steps to optimize the IDoc interface.

The 8-character program name is used to generate the test program (postfix P), the copy code (postfix C), and the subprogram for creating the IDoc control record.
The alias of the 8-character program name is used for the XML main tag, which is the IDoc type name. Do not change this name. Do not change the group of field names.
Fields that are not needed can be deleted in IDL.
Groups that are not needed (=IDoc segment) can be deleted in IDL or the associated subprogram not called in the PMQ interface. Call a subprogram multiple, if this IDoc segment has multiple occurrences.
Do not change the calling sequence of subprograms.
The name of the segment is the sub-program name, if this name is less than or equal to 8 characters. The IDoc type determines whether the segment name is longer than the sub-program name. In this case, the first 6 characters become the IDoc type name and the last 2 are an index.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT