How to call IDMSUTIO from a Cobol Program

Document ID : KB000019285
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

This document describes how IDMSUTIO can be called from within a Cobol Program, in order to process SYSIPT, SYSPCH and SYSLST files.

Solution:

CA IDMS provides a utility program called IDMSUTIO. IDMSUTIO is installed into the CAGJLOAD library.
It can be used by a batch IDMS program to access input file SYSIPT and output files SYSPCH, and SYSLST as described below.

  1. Parameters to be used in the Call:

    CALL 'IDMSUTIO' USING parm1, parm2, parm3 [,parm4]
    where
    Parm1 --> 4 character function code.
    Parm2 --> Field to return a four byte status code.
    Parm3 --> Function dependant. File name for I/O functions.
    Parm4 --> Function dependant. Data buffer for I/O functions.

    Parm1 : Function Code :
    'OPNI' : Open Input
    'OPNO' : Open Output
    'CLOS' : Close
    'GETN' : Get a record
    'WRIT' : write a record

    Parm2 : Status code, returned from IDMSUTIO
    'IOER' : "ERROR" STATUS
    'END.' : "END OF FILE" STATUS
    'OPEN' : "ALREADY OPEN" STATUS
    'FNOP' : "NOT OPEN" STATUS
    'FNTF' : "FILE NOT FOUND" STATUS
    'FUNC' : "INVALID FUNCTION" STATUS
    'NOCV' : "No Mini-CV" STATUS
    '****' : "OK" STATUS

    Parm3 : File name for I/O functions.
    'FIPT' : SYSIPT
    'FLST' : SYSLST
    'FPCH' : SYSPCH

    Parm4 : Data buffer for I/O functions.
    Must be 80 bytes for SYSIPT, SYSPCH,
    Must be 133 bytes for SYSLST
    Note : First byte must be a valid ASA Control Character for SYSLST

  2. Calling, Compiler and link edit options

The user program can be setup in different ways:

  1. "full static" setup
    --------------------------
    a) Program * must * use a static CALL format : CALL 'IDMSUTIO' USING ....
    b) Compiler * must * use the NODYNAM option
    c) Link edit * must * include IDMSUTIO and IDMS

  2. "partial or full dynamic" setup
    ------------------------------------------
    If any of the options listed in point 1 is not full filled, i.e
    a) Program uses a dynamic CALL format :
    WORKING-STORAGE SECTION.
    01 UTIO-MOD PIC X(8) VALUE 'IDMSUTIO'.
    PROCEDURE DIVISION.
    CALL UTIO-MOD USING .....
    - and/or -
    b) Compiler uses DYNAM option
    - and/or -
    c) Link edit does not include IDMSUTIO

    a "prelink" of IDMSUTIO with IDMS is required
    Link edit parameters :
    INCLUDE IDMSLOAD(IDMSUTIO)
    INCLUDE IDMSLOAD(IDMS)
    ENTRY IDMSUTIO
    SETOPT PARM(REUS=NONE)
    NAME IDMSUTIO(R)

    Link the resulting load module into a library other than the CAGJLOAD library.
    This load library should be in the run-time STEPLIB for the batch program in a library
    ahead of the CAGJLOAD library.
    In this case, IDMSUTIO must not be linked with the user program.
    Failing to do so will result in a "NOCV" status at runtime.

  3. Example of a Cobol program containing IDMSUTIO calls:

    See attached BATUTIO2.txt file

  4. Runtime example:
    4.1 JCL

    //PGM EXEC PGM=BATUTIO2
    //STEPLIB DD DISP=SHR,DSN=MEN.EUIDMS.SYSTEM67.V18.USER.LOADLIB
    // DD DISP=SHR,DSN=MEN.EUIDMS.SYSTEM67.V18.DBA.LOADLIB
    // DD DISP=SHR,DSN=MEN.EUIDMS.SYSTEM67.V182.CUSTOM.LOADLIB
    // DD DISP=SHR,DSN=MEN.EUIDMS.SYSTEM67.V182.CAGJLOAD
    //SYSCTL DD DISP=SHR,DSN=MEN.EUIDMS.SYSTEM67.SYSCTL
    // INCLUDE MEMBER=BATCH
    //SYSLST DD SYSOUT=*
    //SYSPCH DD SYSOUT=*
    //SYSOUT DD SYSOUT=*
    //SYSIDMS DD *
    ECHO=ON
    DMCL=CV67DMCL
    --LOCAL=ON
    DBNAME=EMPDEMO1
    //SYSIPT DD *
    >>> Hello World -1- !!! <<<
    >>> Hello World -2- !!! <<<
    >>> Hello World -3- !!! <<<
    /*
    //

    Note : In this case, IDMSUTIO was prelinked in MEN.EUIDMS.SYSTEM67.V18.USER.LOADLIB

    4.2 Results
    4.2.1 SYSOUT output:

    Starting BATUTIO2...
    BIND RUNUNIT done ....
    READY Retrieval done....
    Prepare Open SYSIPT via UTIO.
    Return from IDMSUTIO with status : ****
    Prepare read SYSIPT via UTIO
    Return from IDMSUTIO with status : ****
    Data from SYSIPT : >>> Hello World -1- !!! <<<
    Prepare read SYSIPT via UTIO
    Return from IDMSUTIO with status : ****
    Data from SYSIPT : >>> Hello World -2- !!! <<<
    Prepare read SYSIPT via UTIO
    Return from IDMSUTIO with status : ****
    Data from SYSIPT : >>> Hello World -3- !!! <<<
    Prepare read SYSIPT via UTIO
    Return from IDMSUTIO with status : END.
    Prepare Close SYSIPT via UTIO
    Return from IDMSUTIO with status : ****
    Prepare Open SYSPCH via UTIO.
    Return from IDMSUTIO with status : ****
    Prepare Open SYSLST via UTIO.
    Return from IDMSUTIO with status : ****
    Record : 0023XXXXXX 12 EAST SPEEN STREETNATICK D302364 617889713401019556712197805040000000019540407
    Prepare write SYSPCH via UTIO
    Return from IDMSUTIO with status : ****
    Prepare write SYSLST via UTIO
    Return from IDMSUTIO with status : ****
    Record : 0472ROBBY WILDER 4567 E. GROWTH ST SOUTHBORO MA03145 617431770901038779010197907160000000019550304
    Prepare write SYSPCH via UTIO
    Return from IDMSUTIO with status : ****
    Prepare write SYSLST via UTIO
    Return from IDMSUTIO with status : ****
    Prepare Close SYSPCH via UTIO
    Return from IDMSUTIO with status : ****
    Prepare Close SYSLST via UTIO
    Return from IDMSUTIO with status : ****
    End of program BAUTIO....

    4.2.2 SYSPCH output:

    0023XXXXXX 12 EAST SPEEN STREETNATICK D302364 61788
    0472ROBBY WILDER 4567 E. GROWTH ST SOUTHBORO MA03145 61743

    4.2.3 SYSLST output:

    0023XXXXXX 12 EAST SPEEN STREETNATICK D302364 617889713401019556712197805040000000019540407
    0472ROBBY WILDER 4567 E. GROWTH ST SOUTHBORO MA03145 617431770901038779010197907160000000019550304
File Attachments:
TEC604445.zip