Programming

With
CA/DATACOM
DB

Federated Systems Group

February 13, 1995

FSG
I. STRUCTURE

Federated Systems Group (FSG) uses CA’s DATACOM/DB Data Base Management System.
The actual data is stored in data files, but are accessed through the use of index files. The index
file cross-reference the various keys of a record to the location of the actual record. This
technique allows examination of any item in the index without the actual record being read.

In order to appreciate the difference in structure between a CA Data Base system and a non-data
base system, a comparative diagram is shown in Figure 1. The left side shows an information
base that does not use a data base, with a conventional structure consisting of files, which in turn
consist of records, and they in turn are made up of fields. If records in a file are to be accessed
randomly, the file uses an index pointing to the desired record.

NON DATA BASE CA DATA BASE

Information Base Information Base

Data Base

Data Area
Index
Index
File Table (File)

Record

Record
Element

Field Field

Figure 1
Comparison of non data base and CA DB structures

Federated Systems Group 2 February 13, 1995

Training & Development
On the other hand, the CA data base system is made up of the following components, listed in
ascending order in hierarchy:

1. Field
One or more contiguous bytes that define a specific unit of data.

2. Element
A logical grouping of data consisting of one or more contiguous fields. An element may
span an entire record, or part of a record. A record may contain multiple elements, with
the possibility of including the same fields in more than one element. Thus if a record
consists of 3 fields, namely A, B, and C, then the first element may consist of fields A
and B, while the second may consist of fields B and C.

An element is identified by a 5 character name. By FSG standards, the first 3 characters

are the table name, and the last 2 are digits (e.g., DUN01). Often, at FSG, the record is
broken down into 2 elements, (e.g., DUN00 and DUN01), the first containing an “audit
area” identifying who made the last change to the record and when, and the second
containing the data for that record.

It is important to realize that when data is read from or written to a data base file, one
uses a record key, but accesses elements rather that records. Thus an element can be
thought of as the smallest logical unit of data a program may want to request. For
instance, in the above case where the record consists of elements DUN00 and DUN01,
the request is made to read either or both elements. Data fields that will frequently be
requested together should be defined as one element.

Element 2
Element 1

0411 Brown John F. 2150 Oak Dallas TX 75238

Figure 2
One or more contiguous fields

3. Record
A logical set of one or more fields.

4. Table (previously referred to as file)

A collection of records with similar field layouts, each record being accessed by one or
more keys. Each table is identified by a 3 character name (e.g., DUN), which has to be
unique within the data base, and is as a rule the same as that of its parent area. Within a
data base there may be up to 999 tables.
5. Data Area

Federated Systems Group 3 February 13, 1995

Training & Development
 A data set where the physical data for all of the tables in an area reside. Each data base
has at least one data area. This is the physical DASD area, (i.e., data set definition,
containing one or more logical tables.) An area is identified by a 3 character name (e.g.,
DUN), which has to be unique within the data base. Although technically there may be
multiple tables within an area, the standard practice is to use only one table per area, each
table using the same name as its parent area.

6. Data Base
A collection of one or more areas. Within an information base there may be up to 999
data bases, each identified by a 3 digit number, referred to as the DB ID number. Each
data abase is serviced by an index file, referred to as the IXX file, which keeps track of
the records in each file in the data base. In this respect, it differs from a conventional
information base where each file is serviced by its own separate index.

7. Information Base
This is the total collection of data bases. Each division serviced by FSG has two
information bases, one for production and the other for test. The characteristics of each
data base within an information base are maintained in a control file referred to as the
CXX file. The data base administration group at FSG is responsible for maintaining this
file by means of the CA Data Dictionary.

Federated Systems Group 4 February 13, 1995

Training & Development
II. TERMINOLOGY

In addition to the terms used so far in describing the structure of the CA data base, the following
are selected as being specially pertinent tot he programming staff:

1. Control File
Also called the CXX File, this data set contains directory and profile information for the
entire information base. The types of data contained are definitions of data bases, areas,
tables, records, elements, and keys. It also contains record counts and data set
positioning pointers.

2. Key
One or more fields within a record used to provide quick access to data records. The key
may consist of up to 180 non-contiguous fields. There are two classes of keys, namely
master keys and secondary keys. A table can have only one master key, and up to 98
secondary keys, with the added limitation that the total number of keys for a data base
cannot exceed 999. A key is identified by a 5 character name. At FSG the first 3
characters are the table name and the next 2 are “Kn” where “n” is a number from 1 to 9
(e.g., DUNK1). The native sequence key is the key (either master or secondary) which
determines the sequence of a data base file unloaded through the DB utility program
(DBUTLTY). As a general rule, it is the same as the master key. The key value is the
actual contents of the key at the time of file access.

3. Index
This data set contains the pointers to the physical data records in a data base. Each data
base has one index containing all the keys for all the records for all the tables in it. For
example, if a data base has 2 tables (e.g., DUN and DVN), the first with 2 keys and the
second with 3 keys, the first containing 1000 records and the second 2000 records, then
the total number of entries in the index area is: (2 X 1000) + (3 X 2000) = 8000.

Before reading a record, a binary search of the index file is performed in order to
determine if the record exists, and if so to establish its address in the data area.

4. Multi-user (see illustration next page)

One of the environments under which CA DB can run, which allows several independent
tasks to access the same tables. Thus under this environment CICS, CA DC, as well as
several batch programs can access the same tables simultaneously. The reverse of multi-
user is single-user, which allows only one task to access a table at any time. All CA DB
utilities (e.g., to load and unload files) must run under single-user mode. At that time on-
line access to those tables are terminated the files closed. Under multi-user, CA DB files
accessed through batch programs do not need DD statements in the JCL. However, in
this case, care must be taken to ensure that the job is run on the right CPU to access the
desired information base. At FSG all processing is performed under multi-user.

Federated Systems Group 5 February 13, 1995

Training & Development
 Multi-user, cont.
Single-User

-One copy of DATACOM/DB per region

USER

DATACOM/DB

Multi-User

One copy available to multiple users

USER USER USER

MULTI-USER FACILITY

DATACOM/DB

Figure 3
Single-User/Multi-User

5. Primary Exclusive Control

A task gains primary exclusive control over a record by acquiring the record for update
or delete. Once the update, delete or release occurs, primary exclusive control is
dropped. Task termination will also drop exclusive control. Also a read for update next
command (e.g., RDUNX, GETIT), implies a drop of exclusive control.

6. Request Area
This is the area in the WORKING-STORAGE area of the program where the
programmer enters the information needed by CA DB to perform its function. The type
of information generally needed to answer the following questions:

· What command to perform?

· What table to read?
· Which key to use?
· What is the key value?

DB returns the condition of this activity throughout he return code, also located in the
request area. (Refer to section III, for more on Request Area.)

7. Return Code
The return code is a 2 character alphanumeric field located in the request area, showing
the status of the last DB request. The meaning of the various return codes may be
viewed on-line through ROSCOE PF1 menu, option DB, or the rpf “DB xx” where
xx=return code.

Federated Systems Group 6 February 13, 1995

Training & Development
8. User Requirement Table (URT)
The URT defines what DB resources are necessary for a program to perform its task. It
contains the name of each table accessed by the program, indicating whether the access is
random or sequential (or both), and whether the file is to be updated or not. Each batch
DB program is required to have a URT. CICS on-line programs do not specify them
because they are defined when CICS is brought up. A URT may either be complied with
the program, or loaded dynamically with the program through a “stub”. At FSG the
second method is used in order to prevent the need for recompiling a program when the
table is changed. Both stubs and the URT’s are maintained on division Librarians
identified by names start with URT and URD, respectively, (e.g., URTPOPB1 and
URDPOPB1.) Refer to FSG Standards manual, chapter 2, for naming standard.

Program Linked With URT Program Linked With URT

-SEL URTAMC00,MC00 -SEL URT00023, 0023

-REP ALL -REP ALL
TITLE “USER REQUIREMENTS URTAMC00” TITLE “USER REQUIREMENTS URT00023”
URTABLE=LOAD, DBURINF
OPEN=DB, URTABLE=LOAD,
LOADNAM=URDAMC00, OPEN=DB
BACKSPT=YES LOADNAM=URD00023,
DBUREND BACKSPT=NO
SYSTEM=OS, DBUREND
USRINFO-URDAMC00 SYSTEM=OS,
END USRINFO=URD00023
END

above relates to below: above relates to below:

URD Would be Loaded at Execution Time URD Would be Loaded at Execution Time

-SEL URDAMC00, MC00 -SEL URD00023, 0023

-REP ALL -REP ALL
TITLE “USER REQUIREMENTS URDAMC00” TITLE “USER REQUIREMENTS URD00023”
DBURSTR DBURSTR
ABEND=NO, ABEND=NO
MULTUSE-YES MULTUSE=YES
DBURTBL DBURTBL
ACCESS-RAN, ACCESS=RAN,
DBID=050, DBID=203,
TBLNAM=AMC, TBLNAM=RUN,
UPDATE=NO UPDATE=NO
DBUREND DBURTBL
SYSTEM=OS, ACCESS=RANSEQ,
USRINFO=URDAMC00 DBID=132,
END SEQBUFS=2,
TBLNAM=PCM,
UPDATE=NO
DBUREND
SYSTEM=OS
USRINFO=URD00023
END

Federated Systems Group 7 February 13, 1995

Training & Development
III. CODING REQUIREMENTS

The COBOL command used for accessing a DB file is:

CALL ‘DBNTRY’ USING parameter - 1

parameter - 2
parameter - 3
parameter - 4

Parameter - 1 is a 32-byte user information block. The first 8 bytes contains the
program name and is included as part of the logged records. At this time the remaining
area is not used.

Parameter - 2 is the request area, which is a 76 byte area immediately followed by a key
value area (1 to 180 bytes depending upon the key definition). This area contains the
command to be processed, the table name, the key name, the return code and key value.

Parameter - 3 is the work area, where the elements are read into and written from. This
area must be compatible in length and arrangement with the elements requested. For
example, if elements DUN00 and DUN01 are to be read, this area must contain all the
fields in DUN00, immediately followed by those in DUN01.

Parameter - 4 is the element list area. It contains the list of elements to be processed.
There may be up to 16 elements selected at a time. Each entry in the list is a 5 byte
element name followed by a space. The last entry is left blank to indicate the end of the
list.

The only change in a COBOL CICS program is to replace CICS input/output commands with
the one above, making sure that the 4 areas needed for the parameters are properly defined in
WORKING-STORAGE. On the other hand, batch programs have a number of differences, as
discussed on the next page.

Federated Systems Group 8 February 13, 1995

Training & Development
COBOL Batch: Database vs. Non-Database:

1. Environment Division
No SELECT statements for DB files in the INPUT-OUTPUT SECTION. However, all
non-DB files should still have SELECT statements.

2. Data Division
No FD statements for DB FILES in the FILE SECTION. Non-DB files still need FD
statements.

The WORKING-STORAGE SECTION should have the following areas defined:

a. User information block. This can be copied from Librarian by coding

è -INC DBUSER
a. Datacom commands. This can be copied from Librarian by coding
è -INC DBCOM
a. DB request area. This can be copied from Librarian by coding
è -INC DREQ xxx
where xxx is the name of the database table being accessed.
a. The element work area, with COBOL definition of each field. This can be copied
from Librarian by coding
è -INC xxxxxxxx
where xxxxxxxx is the member name of the element layout. More than one -INC
may be needed to cover all the elements.
a. The element list area. The Librarian module used for the DB request area also
includes this list, therefore no additional coding is required.

3. Procedure Division
a. Since the application program is run as a subroutine to the data base, the first
statement in the PROCEDURE DIVISION should be
è ENTRY ‘DBMSCBL’.
a. If program parameters are defined in the EXEC statement of the JCL, code:
ENTRY ‘DBMSCBL’ USING parm-area instead of PROCEDURE
DIVISION USING parm-area.
b. Do not OPEN or CLOSE DB files. This is handled automatically by DB.
c. Use GOBACK instead of STOP RUN.
d. Replace all input/output statements (i.e., READ and WRITE) by
CALL ‘DBNTRY’ as described above.

Federated Systems Group 9 February 13, 1995

Training & Development