Programming

With
CA/DATACOM
DB
Federated Systems Group
February 13, 1995

FSG

I.

STRUCTURE

Federated Systems Group (FSG) uses CAs 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
Information

CA DATA BASE
Base

Information Base

Data Base
Data Area
Index
File

Index
Table (File)

Record
Record
Element

Field

Figure 1
Comparison of non data base and CA DB structures

Field

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.
Data Area

5.

Federated Systems Group

Training & Development

February 13, 1995

4
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.

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 multiuser 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 online 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

Training & Development

February 13, 1995

6
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.

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 URTs 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
-REP ALL
TITLE USER REQUIREMENTS URTAMC00
URTABLE=LOAD,
OPEN=DB,
LOADNAM=URDAMC00,
BACKSPT=YES
DBUREND
SYSTEM=OS,
USRINFO-URDAMC00
END

-SEL URT00023, 0023

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

above relates to below:

URD Would be Loaded at Execution Time

above relates to below:

URD Would be Loaded at Execution Time

-SEL URDAMC00, MC00

-REP ALL
TITLE USER REQUIREMENTS URDAMC00
DBURSTR
ABEND=NO,
MULTUSE-YES
DBURTBL
ACCESS-RAN,
DBID=050,
TBLNAM=AMC,
UPDATE=NO
DBUREND
SYSTEM=OS,
USRINFO=URDAMC00
END

-SEL URD00023, 0023

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

Federated Systems Group

Training & Development

February 13, 1995

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.

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

Training & Development

February 13, 1995