How to Generically Read All Records in Any File Sequentially in an Advantage CA-Ramis RPI Application

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

RPI is the common name for the Advantage CA-Ramis Procedural Language Interface. RPI provides access to Advantage CA-Ramis database files from user programs written in one of several standard procedural languages. These include COBOL, PL/I, FORTRAN, Assembler, and any other procedural language that uses the standard IBM subroutine linkage convention.

Navigating Advantage CA-Ramis database files from an RPI application can be both interesting and challenging. This article will provide a generic technique to answer one of the more basic questions:

How do I use RPI to sequentially retrieve all of the records in an Advantage CA-Ramis hierarchical database file until logical end-of-file is reached?

Here's how...

  1. Open the file:

    CALL 'RAMIS' USING pcb, OPEM

This is a generic open which will activate all accessible fields down to the lowest accessible level.

  1. In a loop, retrieve each record until logical end-of-chain (RPI STATUS code NN):

    CALL 'RAMIS' USING pcb, NEXR, ZERO, data-record, CBOT

This is a generic Next command to retrieve the record (NEXR), allowing movement on all levels from level 1 (the parent level on which movement is not allowed is specified as zero (ZERO)) down to the allowable move level specified as the bottom level (CBOT).

  1. Close the file when done:

    CALL 'RAMIS' USING pcb, END

This technique will work for any file. Only the pcb content to identify the specifics for the accessed file and the data-record area that defines the retrieved file record needs to be supplied by the application.

Here's how the code might look in a Cobol program that is reading the sample file SALES.

       IDENTIFICATION DIVISION.                            
       PROGRAM-ID. RPIREAD.                                
       ENVIRONMENT DIVISION.                               
       CONFIGURATION SECTION.                              
       SOURCE-COMPUTER. IBM-370.                           
       OBJECT-COMPUTER. IBM-370.                           
       DATA DIVISION.                                      
       WORKING-STORAGE SECTION.        
       01  PCB.                        
           02  FILENAME        PIC X(12) VALUE 'SALES'. 
           02  DATABASE.                       
               03  BASE-NAME   PIC X(08) VALUE 'RAMDATA'. 
               03  BASE-TYPE   PIC X(08) VALUE 'DATA'. 
               03  BASE-MODE   PIC X(04) VALUE SPACES. 
           02  COUNT1          PIC S9(5) COMP.  
           02  PPASSWORD       PIC X(08) VALUE '  '. 
           02  SSTATUS         PIC X(04) VALUE SPACES. 
               88 GOOD-STATUS  VALUE SPACES.
               88 END-OF-CHAIN VALUE 'NN  '.  
           02  REASON          PIC X(04) VALUE SPACES. 
           02  COUNT2          PIC S9(5) COMP.  
           02  COUNT3          PIC S9(5) COMP.   
           02  SYSTEM-AREA1    PIC X(20).      
           02  ECHO-FLAG       PIC S9(5) COMP VALUE +0. 
           02  SYSTEM-AREA2    PIC X(12).                  
           02  NUM-FIELDS      PIC S9(5) COMP.             
       01  DATA-REC.                                       
           02  YEAR            PIC X(04).                  
           02  MONTH           PIC S9(5) COMP.             
           02  CUSTNUM         PIC X(05).                   
           02  FILLER          PIC X(03).                   
           02  CUSTOMER        PIC X(25).                   
           02  FILLER          PIC X(03).                   
           02  INDUS-CODE      PIC X(02).                   
           02  FILLER          PIC X(02).                   
           02  INVOICE         PIC X(06).                   
           02  FILLER          PIC X(02).                   
           02  PRODNUM         PIC X(07).                   
           02  FILLER          PIC X(01).                   
           02  UNITS           PIC S9(7) COMP.              
           02  PRODNAME        PIC X(20).                   
           02  PRICE           COMP-2.                      
           02  UCOST           COMP-2.                      
       01  RPI-COMMANDS.                                    
           02  OPEM            PIC X(04) VALUE 'OPEM'.      
           02  NEXR            PIC X(04) VALUE 'NEXR'.      
           02  TTOP            PIC X(04) VALUE 'TOP '.
           02  CBOT            PIC X(04) VALUE 'CBOT'.
           02  EEND            PIC X(04) VALUE 'END '.       
       01  CONSTANTS.                                      
           02  NZERO           PIC S9(5) COMP VALUE +0.     
       01  REC-NUM  PIC S9(9) COMP.                         
       PROCEDURE DIVISION.                                  
           MOVE +1 TO ECHO-FLAG.                            
           CALL 'RAMIS' USING PCB, OPEM. 
           IF NOT GOOD-STATUS PERFORM RPI-ERROR-EXIT.   
           PERFORM READ-SEQ                             
               UNTIL NOT GOOD-STATUS.                   
           IF END-OF-CHAIN PERFORM REPORT-RESULTS       
               ELSE PERFORM RPI-ERROR-EXIT.               
       READ-SEQ.                               
           CALL 'RAMIS' USING PCB, NEXR, NZERO, DATA-REC, CBOT.
           IF GOOD-STATUS                 
              ADD +1 TO REC-NUM.
       REPORT-RESULTS.                               
           DISPLAY 'TOTAL READ = ' REC-NUM.          
           PERFORM CLOSE-FILE.                       
       RPI-ERROR-EXIT.                               
           DISPLAY 'STATUS/REASON CODE RETURNED = '  
                   SSTATUS, '/', REASON.             
           PERFORM CLOSE-FILE.                       
       CLOSE-FILE.                                   
           CALL 'RAMIS' USING PCB, EEND.  
           STOP RUN. 

Here is the sample SALES file description as displayed by the Advantage CA-Ramis RAMINDEX utility.

 DESCRIPTION OF CA-RAMIS FILE: SALES                   PAGE     1
                                                                
                                    L E V E L  SEGMENT          
 LIST   FIELDNAME     SYNONYM       NAME TYPE  FACTOR   FORMAT  
 ----   ---------     -------       ---------  -------  ------  
     1  YEAR          Y             1    S        4     A   4   
     2  MONTH         M             2    S       12     I   2   
     3  CUSTNUM       CN            3    S        5     A   5   
     4  CUSTOMER      CNAME         4    V        1     A   25  
     5  INDUS-CODE    IC            4    V        1     A   2   
     6  INVOICE       I             5             2     A   6   
     7  PRODNUM       PN            6             2     A   7   
     8  UNITS         U             6             2     I   7   
     9  PRODNAME      PNAME         7    V        1     A   20  
    10  LISTPRICE     LIST          7    V        1     D   8.2 
    11  UCOST         UC            7    V        1     D   7.2  

Notice that the SALES file has 7 levels. Thus, the current bottom (CBOT) will be set to 7 by RPI.

You can confirm the results (the total number of records retrieved) given by this RPI technique by doing the following TABLE in Advantage CA-Ramis against the SALES file, counting a field on the 7th (lowest) level:

           TABLE FILE SALES COUNT PRODNAME NO PRINT END 

Read More About It

For more information on accessing Advantage CA-Ramis databases from your procedural language program using RPI, please refer to the Advantage CA-Ramis Procedural Language Interface (RPI) manual. See Appendix B. Status and Reason Code Descriptions for the RPI return codes. For the full set of Advantage CA-Ramis documentation and additional information, visit the Product Home Page of supportconnect.ca.com at http://supportconnectw.ca.com/public/app_dev/ca_ramis/ramis_supp.asp.

Contribute Your Ideas

If you have a tried and true technique or experience that you would like to share with the Advantage CA-Ramis community as a published article, please contact Computer Associates Support.