How to call IDMSUTIO from a Cobol Program

Products

• IDMS
• IDMS - Database
• IDMS - ADS

Issue/Introduction

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

Environment

Release: IDADSO00100-18.5-ADS-for CA-IDMS
Component: