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?
- 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.
- 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).
- 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.
02 FILENAME PIC X(12) VALUE 'SALES'.
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.
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.
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 '.
02 NZERO PIC S9(5) COMP VALUE +0.
01 REC-NUM PIC S9(9) COMP.
MOVE +1 TO ECHO-FLAG.
CALL 'RAMIS' USING PCB, OPEM.
IF NOT GOOD-STATUS PERFORM RPI-ERROR-EXIT.
UNTIL NOT GOOD-STATUS.
IF END-OF-CHAIN PERFORM REPORT-RESULTS
ELSE PERFORM RPI-ERROR-EXIT.
CALL 'RAMIS' USING PCB, NEXR, NZERO, DATA-REC, CBOT.
ADD +1 TO REC-NUM.
DISPLAY 'TOTAL READ = ' REC-NUM.
DISPLAY 'STATUS/REASON CODE RETURNED = '
SSTATUS, '/', REASON.
CALL 'RAMIS' USING PCB, EEND.
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.