Sending data by using the COBOL API

The Z Common Data Provider COBOL API is a set of COBOL language functions that can be used to send data to the Data Streamer. It uses the EZASOKET library for implementing the socket interface. The EZASOKET library must be available in your host system.

Before you begin

To send data, the API must have the port number on which the Data Streamer listens for incoming data. Ensure that a policy, which defines an application data stream, is defined and used in the Data Streamer procedure.

For more information, see Creating an application data stream definition and Customizing the Data Streamer started task.

About this task

This task illustrates how to use the COBOL API to send data to the Data Streamer. The sample COBOL program HBOCBAPI and the copybooks HBOCMDTA and HBOCSDTA in the hlq.SHBOSAMP library demonstrate the API usage, as described in the following procedure.

The API supports both IPv4 and IPv6 protocols. You can specify which protocol to use by setting the appropriate parameters.

Also, for information about the EZASOKET library, see COBOL call interface sample IPv6 client program.

Procedure

To use the COBOL API to send data to the Data Streamer, complete the following steps:

  1. In your COBOL program, add or update the metadata and sample data as a copybook with the necessary values to stream the user data to the Data Streamer.
    You can refer to the HBOCBAPI program and the HBOCMDTA and HBOCSDTA copybooks from the hlq.SHBOSAMP library.
  2. Define the following input parameters in your COBOL program:
    • The Data Streamer port number
    • Hostname or IP address
    • Identifier (the default value is CDPUSER, if not passed)
    • Sample data length
    • Payload data type = 1 for unsplit data (only unsplit data is supported)
    • IPv4/IPv6 protocol selection flag (19 for IPv6 [default], 2 for IPv4)
    • IPv4 Data streamer address in hexadecimal format (retain the default value for IPv6)
             01  WS-PARM1.
SAMPLE       05  WS-TCPNAME      PIC X(8) VALUE 'TCPIP   '.
             05  WS-ASNAME       PIC X(8) VALUE SPACE.
SAMPLE   01  WS-PARM2            PIC X(4) VALUE X'C8C9'.
SAMPLE   01  WS-AFINET           PIC 9(4) BINARY VALUE 19.
SAMPLE   01  WS-IPADDR4          PIC X(4) VALUE SPACES.
SAMPLE   01  IDENTIFIER          PIC X(8) VALUE 'CDPUSER '.
         01  WS-PARM3            PIC S9(8) BINARY VALUE ZERO.
         01  R-C                 PIC S9(8) BINARY VALUE ZERO.
         01  WS-PARM5            PIC S9(8) BINARY VALUE ZERO.
SAMPLE   01  D-T                 PIC 9(4) BINARY VALUE 1.
         01  META-PTR                   POINTER.
         01  DATA-PTR                   POINTER.
         01  W-LEN                      PIC 9(8)  BINARY.

    IPv4/IPv6 configuration examples:

    For IPv6 (default):

    01  WS-AFINET           PIC 9(4) BINARY VALUE 19.
01  WS-IPADDR4          PIC X(4) VALUE SPACES.

    For IPv4:

    01  WS-AFINET           PIC 9(4) BINARY VALUE 2.
01  WS-IPADDR4          PIC X(4) VALUE X'0A000064'.
*   Example: IP address 10.0.0.100 = X'0A000064'
  3. Define the metadata fields in your copybook. 
    01  META-DATA.                                            
            05 METADATA-VALUES    PIC X(4) VALUE X'00000005'.     
            05 METADATA-K1        PIC X(8) VALUE 'encoding'.      
            05 FILLER             PIC X VALUE SPACE.              
            05 METADTA-V1         PIC X(7) VALUE 'IBM1047'.       
            05 FILLER             PIC X VALUE SPACE.              
            05 METADATA-K2        PIC X(4) VALUE 'path'.          
            05 FILLER             PIC X VALUE SPACE.              
            05 METADTA-V2         PIC X(11) VALUE 'APP/MYDATAP'.  
            05 FILLER             PIC X VALUE SPACE.              
            05 METADATA-K3        PIC X(10) VALUE 'sourcename'.   
            05 FILLER             PIC X VALUE SPACE.              
            05 METADTA-V3         PIC X(07) VALUE 'MYDATAP'.      
            05 FILLER             PIC X VALUE SPACE.              
            05 METADATA-K4        PIC X(10) VALUE 'sourcetype'.   
            05 FILLER             PIC X VALUE SPACE.              
            05 METADTA-V4         PIC X(11) VALUE 'zOS-MYDATAP'.  
            05 FILLER             PIC X VALUE SPACE.              
            05 METADATA-K5        PIC X(8) VALUE 'timezone'.      
            05 FILLER             PIC X VALUE SPACE.              
            05 METADTA-V5         PIC X(5) VALUE '+0000'.         
            05 FILLER             PIC X VALUE SPACE.
  4. Define the user data that you want to stream in your sample data copybook. 
    01  SAMP-DATA.                                          
SAMPLE      05 DATA-LENGTH   PIC 9(4) BINARY VALUE 42.          
SAMPLE      05 S-DATA        PIC X(42) VALUE                    
SAMPLE            '2025-04-11 00:00:00,CDP,DEMO DATA RECORD-2'.
  5. Include the dynamic CALL statements to the COBOL APIs to stream data to the Data Streamer.
    • CALL HBOCBOPN

      Open the socket connection to the Data Streamer.

                200-CALL-HBOCBOPN.
             CALL WS-HBOCBOPN USING WS-PARM1
                                    WS-PARM2
                                    WS-PARM3
                                    WS-AFINET
                                    WS-IPADDR4
                                    WS-SOCKET-DESCRIPTOR.
             MOVE WS-SOCKET-DESCRIPTOR  TO SOCKET-DESCRIPTOR.
             DISPLAY 'HBOCBAPI:RETURN CODE FROM SOCKET OPEN:'WS-PARM3
             MOVE WS-PARM3 TO RETURN-CODE.
          200-EXIT.
              EXIT.
    • CALL HBOCBSND

      Send the unsplit data by using the socket descriptor and the metadata and data pointers returned from HBOCBOPN.

      CALL WS-HBOCBSND  USING SOCKET-DESCRIPTOR
                        META-PTR
                        DATA-PTR
                        IDENTIFIER
                        D-T
                        R-C
                        W-LEN.
    • CALL HBOCBCLS

      Close the socket connection.

                400-CALL-HBOCBCLS.
             CALL WS-HBOCBCLS USING WS-PARM5
                                    WS-AFINET.
             MOVE WS-PARM5 TO RETURN-CODE.
          400-EXIT.
              EXIT.
  6. Compile and link-edit your COBOL program by using the following options.
    • AMODE 31
    • RMODE ANY
    • RENT, REUSE
  7. Include the hlq.SHBOLOAD and EZA.SEZATCP datasets in the STEPLIB concatenation of your JCL. 
    //HBOCBTSB  JOB (USER1,B089),'*TEST RUN    ',  =X,          
//     CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID                    
//*-------------------------------------------------------  
//COBSTEP  EXEC PGM=HBOCBAPI,REGION=200M                    
//STEPLIB  DD DSN=XXXXXXXX.XXXXXXXX.LOADLIB,DISP=SHR        
//         DD DSN=ZATLOCAL.ZCDP510.SHBOLOAD,DISP=SHR        
//         DD DSN=EZA.SEZATCP,DISP=SHR                      
//SYSPRINT DD SYSOUT=A
  8. Run the COBOL program.

What to do next

After you run the COBOL program and successfully complete the job, perform the following tasks:

  1. Verify that the IP Connection is successful. Review the job log output.
  2. Verify that the unsplit data is streamed to the subscriber. Review the Data Streamer job log output for success or error information.
  3. If an error occurs, take the necessary action based on the error message. If you need further assistance, contact the IBM® Software Support.