OpenFrame Base 7 Fix#3 TSAM Guide v2.1.4 en

OpenFrame
TSAM Guide
OpenFrame/Base 7 Fix#3
Copyright © 2018 TmaxSoft Co., Ltd. All Rights Reserved.

Copyright Notice
Copyright © 2018 TmaxSoft Co., Ltd. All Rights Reserved.
Restricted Rights Legend
All TmaxSoft Software (Tmax OpenFrame®) and documents are protected by copyright laws and
international convention. TmaxSoft software and documents are made available under the terms of the
TmaxSoft License Agreement and this document may only be distributed or copied in accordance with
the terms of this agreement. No part of this document may be transmitted, copied, deployed, or reproduced
in any form or by any means, electronic, mechanical, or optical, without the prior written consent of
TmaxSoft Co., Ltd. Nothing in this software document and agreement constitutes a transfer of intellectual
property rights regardless of whether or not such rights are registered) or any rights to TmaxSoft
trademarks, logos, or any other brand features.
This document is for information purposes only.The company assumes no direct or indirect responsibilities
for the contents of this document, and does not guarantee that the information contained in this document
satisfies certain legal or commercial conditions. The information contained in this document is subject
to change without prior notice due to product upgrades or updates. The company assumes no liability
for any errors in this document.
Trademarks
Tmax® and Tmax OpenFrame®are registered trademarks of TmaxSoft Co., Ltd. Other products, titles
or services may be registered trademarks of their respective companies.
Open Source Software Notice
This product includes open source software developed and/or licensed by "OpenSSL", "RSA Data
Security, Inc.", "Apache Foundation", and "Jean-loup Gailly and Mark Adler". Information about the
aforementioned and the related open source software can be found in the
"${INSTALL_PATH}/license/oss_licenses" directory.
Document Information
Document Name: OpenFrame TSAM Guide
Document Created: 2018-10-19
Software Version: OpenFrame/Base 7 Fix#3
Document Version: v2.1.4

Table of Contents
About This Document .................................................................................................. vii
Chapter 1. TSAM Introduction ..................................................................................... 1

1.1. Overview ....................................................................................................... 1
1.2. Data Sets and Access Methods ...................................................................... 1
1.3. TSAM Functions ............................................................................................ 2
1.4. TSAM-Related Modules .................................................................................. 3
Chapter 2. Data Sets ................................................................................................... 5

2.1. Data Set Structures ........................................................................................ 5
2.1.1. ESDS ................................................................................................. 7
2.1.2. KSDS ................................................................................................. 8
2.1.3. RRDS ............................................................................................... 10
2.1.4. VRDS ............................................................................................... 10
2.1.5. Alternate Index .................................................................................. 11
2.2. Managing Data Sets ..................................................................................... 12
2.2.1. baseinit ............................................................................................. 14
2.2.2. voladd .............................................................................................. 15
2.2.3. IDCAMS (JSCVSUT/KQCAMS) .......................................................... 16
2.3. Processing Data Sets ................................................................................... 19
2.3.1. Allocate/Unallocate ............................................................................ 20
2.3.2. Open/Close ....................................................................................... 21
2.3.3. OPEN Mode ...................................................................................... 21
2.3.4. Access Mode .................................................................................... 22
2.3.5. Record Access .................................................................................. 23
2.3.6. Browsing ........................................................................................... 24
2.3.7. Transaction ....................................................................................... 24
Chapter 3. API ........................................................................................................... 25

3.1. Overview ..................................................................................................... 25
3.2. Connection .................................................................................................. 26
3.2.1. tsam_connect() ................................................................................. 26
3.2.2. tsam_disconnect() ............................................................................. 28
3.3. Transaction .................................................................................................. 28
3.3.1. tsam_commit() .................................................................................. 28
3.3.2. tsam_rollback() .................................................................................. 29
3.4. File Management ......................................................................................... 29
3.4.1. tsam_create() .................................................................................... 29
3.4.2. tsam_remove() .................................................................................. 31
3.4.3. tsam_truncate() ................................................................................. 31
3.4.4. tsam_alter() ...................................................................................... 33
3.4.5. tsam_stat() ........................................................................................ 34
OpenFrame iii
3.4.6. tsam_filename() ................................................................................ 35
3.5. File Open/Close ........................................................................................... 36
3.5.1. tsam_open() ...................................................................................... 36
3.5.2. tsam_close() ..................................................................................... 37
3.6. Record Access ............................................................................................. 37
3.6.1. tsam_start() ...................................................................................... 37
3.6.2. tsam_read() ...................................................................................... 39
3.6.3. tsam_unlock() ................................................................................... 41
3.6.4. tsam_write() ...................................................................................... 41
3.6.5. tsam_rewrite() ................................................................................... 42
3.6.6. tsam_delete() .................................................................................... 44
3.7. Browsing ..................................................................................................... 45
3.7.1. tsam_start_br() .................................................................................. 45
3.7.2. tsam_reset_br() ................................................................................. 46
3.7.3. tsam_end_br() ................................................................................... 47
3.7.4. tsam_read_next() .............................................................................. 48
3.7.5. tsam_read_prev() .............................................................................. 50
Chapter 4. Administering TSAM ................................................................................ 51

4.1. Environment Variables .................................................................................. 51
4.2. Management ................................................................................................ 52
4.2.1. TSAM PREFETCH ............................................................................ 52
4.2.2. Data Set-Tablespace Mapping ............................................................ 54
4.3. Initialization .................................................................................................. 56
4.3.1. Creating a Tablespace for Catalog ...................................................... 56
4.3.2. Creating a System Table .................................................................... 56
4.3.3. Adding a Volume ............................................................................... 57
Glossary ...................................................................................................................... 59
Index ........................................................................................................................... 61
iv OpenFrame TSAM Guide

List of Figures
[Figure 2.1] Index Component – Index Set and Sequential Set ........................................ 9
[Figure 2.2] Access Path Concept ................................................................................ 12
[Figure 4.1] Data Sets of Different Online Systems Stored in a Single Tablespace ........... 54
[Figure 4.2] Using TSAM Data Set-Tablespace Mappings .............................................. 55
OpenFrame v
About This Document
Intended Audience
®
This guide is intended for users of the Tmax OpenFrame (hereafter OpenFrame) rehosting
solution, in particular the OpenFrame/Base system.
Required Knowledge
To fully understand this document, you need a basic understanding of OpenFrame data sets.
This guide mentions IDCAMS counterparts, which are Hitachi VOS3 VSAM utility called JSCVSUT
and XSP/MSP VSAM utility called KQCAMS.
About This Document vii

Document Organization
This guide consists of four chapters.
Descriptions of each is as follows:
● Chapter 1: TSAM Introduction
Outlines mainframe data sets and access methods and describes TSAM functions, and
implementation, and related modules.
● Chapter 2: Data Sets
Describes how to configure, manage, and process TSAM data sets.
● Chapter 3: API
Describes TSAM API client libraries that can be used in application programs.
● Chapter 4: Administering TSAM
Describes how to set up, manage, and initialize TSAM.
viii OpenFrame TSAM Guide

Conventions
Convention Meaning
<AaBbCc123> Program source code file name
<Ctrl>+C Hold down the Ctrl key and press the C key
[Button] Name of a GUI button or menu
Bold Emphasis
Italics Reference to another guide
" " (Double quotation Reference to a chapter or section in this or another guide
marks)
'Input' User input on the screen
Hyperlink Email account, website, or a reference to other chapters or sections
> Proceeding order of menu
+---- Files or directories exist in this directory
|---- Files or directories do not exist in this directory
Reference or caution
Note
[Figure 1.1] Figure caption
AaBbCc123 Commands, screen output after executing command, or sample code
{} Required items
[] Optional items
| Selective items
About This Document ix

System Requirements
Requirement
Platform Solaris 11 (SunOS 5.11) or later (32-bit, 64-bit)
Linux x86 2.6 or later (32-bit, 64-bit)
Linux ia64 2.6 or later (32-bit, 64-bit)
Hardware More than 5 GB hard disk space
More than 8 GB RAM
Database Tibero 6 FixSet05
Oracle 11g or 12c
MS SQL 2014
Compiler MF-COBOL or OpenFrame COBOL compiler
OpenFrame PL/I compiler
Note
Contact TmaxSoft Technical Support about IBM or HP-UX platform support.
x OpenFrame TSAM Guide

Related Documents
Guide Description
OpenFrame Outlines basic concepts of OpenFrame and describes all the

OpenFrame guides.
Getting Started
OpenFrame Outlines how to install and set up OpenFrame/Base.
Base Installation Guide
OpenFrame Describes overall features of OpenFrame/Base.
Base Guide
OpenFrame Outlines OpenFrame data sets and describes data set types and
cataloging methods.
Data Set Guide
OpenFrame Describes OpenFrame utilities.
Utility Reference Guide
OpenFrame Describes OpenFrame tools.
Tool Reference Guide
OpenFrame Describes information and steps needed to migrate resources from

mainframe to OpenFrame.
Migration Guide
OpenFrame Describes potential errors and troubleshooting methods.
Error Message
Reference Guide
About This Document xi

References
Product Guide
IBM Mainframe z/OS DFSMS: Using Data Sets
z/OS DFSMS: Managing Catalogs
z/OS DFSMS: Access Method Services for Catalogs
Hitachi Mainframe VOS3 Data Management Description
VOS3 Data Formats
VOS3 VSAM Description
Fujitsu Mainframe OS IV / MSP Data Management Description
OS IV / MSP Data Set Utility User Guide
OS IV / MSP VSAM Description
xii OpenFrame TSAM Guide

Contact Information
Korea
TmaxSoft Co., Ltd.
9th Floor, BS Tower Building, 29,
Hwangsaeul-ro 258 beon-gil, Bundang-gu,
Seongnam-si, Gyeonggi-do, 13595
South Korea
Tel: +82-31-8018-1000
Fax: +82-31-8018-1115
Email: info@tmax.com
Web (Korean): http://www.tmaxsoft.com
TechNet: http://technet.tmaxsoft.com
USA
TmaxSoft Inc.
230 West Monroe Street Suite 1950
Chicago, IL 60606
U.S.A
Tel: +1-312-525-8330
Fax: +1-312-525-8340
Email: info@tmaxsoft.com
Web (English): http://www.tmaxsoft.com/us_en/home
Japan
TmaxSoft Japan Co., Ltd.
5F Sanko Bldg, 3-12-16 Mita, Minato-Ku, Tokyo, 108-0073
Japan
Tel: +81-3-5765-2550
Fax: +81-3-5765-2567
Email: info@tmaxsoft.co.jp
Web (Japanese): http://www.tmaxsoft.co.jp
About This Document xiii

China
Beijing TmaxSoft System Software Co., Ltd.
Room103, No.2 Huizhong Building, Seven Street Shangdi,
Haidian District, Beijing, 100085
P.R.China
Tel: +86-10-6298-8827
Email: info@tmaxsoft.com.cn
Web (Chinese): http://www.tmaxsoft.com/cn_en/home_cn_en
Brazil
Tmax Brasil Sistemas E Serviços Ltda.
Av. Copacabana, 177, sala 32~35 Empresarial 18 do Forte
Alphaville Barueri, Sao Paulo, 06472-001
Brazil
Tel: +55-11-4191-3100
Fax: +55(11) 4191-3705 (extension#112)
Email: info.bra@tmaxsoft.com
Web (Portuguese): http://www.tmaxsoft.com/br_en/home_br_en
Russia
Tmax Rus L.L.C.
Leninsky prospekt, 113/1 (Park Place Moscow),
Office 318e, Moscow, 117198
Russia
Tel: +7(495)970-0135
Email: info.rus@tmaxsoft.com
Web (Russian): http://www.tmaxsoft.com/ru_ru/home_ru_ru
xiv OpenFrame TSAM Guide

Singapore
Tmax Singapore Pte. Ltd.
430 Lorong 6, Toa Payoh #10-02,
OrangeTee Building, 319402
Singapore
Tel: +65-6259-7223
Fax: +65-6258-7112
Email: info.sg@tmaxsoft.com
Web (English): http://www.tmaxsoft.com/sg_en/home_sg_en
United Kingdom
TmaxSoft UK Ltd.
215 Knyvett House, Watermans Business Park,
The Causeway, Staines TW18 3BA
United Kingdom
Tel: +44-1784-895005
Email: info.uk@tmaxsoft.com
Web (English): http://www.tmaxsoft.com/gb_en/home_gb_en
Canada
TmaxSoft Canada, Inc.
2425 Matheson Blvd East, 8th Floor,
Unit 825 Mississauga, ON, L4W 5K4
Canada
Tel: +1-905-361-2888
Email: info.canada@tmaxsoft.com
Web (English): http://www.tmaxsoft.com/ca_en/home_ca_en
About This Document xv

Australia
TmaxSoft Proprietary Limited
L32, 101 Miller Street, North Sydney 2060
Australia
Tel: +61-2-8019-7054
Email: info.aus@tmaxsoft.com
Web (English): http://www.tmaxsoft.com/au_en/home_au_en
India
TmaxSoft Technologies Private Limited
Sobha Alexander Plaza, 3rd Floor,
16/2 Commissariat Road, Bangalore-560025
India
Tel: +91-7619-482-582
Email: info.india@tmaxsoft.com
Web (English): http://www.tmaxsoft.com/in_en/home_in_en
Turkey
TmaxSoft Co., Ltd. Turkey Liaison Office
Windowist Tower. Eski Buyukdere Cad. No:26,
Maslak 34467 Istanbul
Turkey
Tel: +90-212-214-7345
Email: info.tr@tmaxsoft.com
Web (English): http://www.tmaxsoft.com/tr_en/home_tr_en
xvi OpenFrame TSAM Guide

Chapter 1. TSAM Introduction
This chapter outlines mainframe data sets and access methods. It also describes TSAM functions,
implementation, and related modules.
1.1. Overview
As part of OpenFrame/Base (hereafter Base), Tmax VSAM (TSAM) is TmaxSoft's module for
managing and processing data set and is equivalent to VSAM. TSAM is implemented by using
ESQL in OpenFrame (or using unixODBC for Fix#2).
1.2. Data Sets and Access Methods

A data set is a collection of logically linked records. The process used to access records in a
data set is called access method.
Mainframe data sets are largely divided into two types: non-VSAM data sets and VSAM data
sets.
The following are lists of access methods for each data set type.
● Non-VSAM Data Sets
Data Set Structure Access Method
Sequential Data Set BSAM, QSAM
Direct Data Set BDAM
Partitioned Data Set (PDS) BPAM
Indexed Data Set ISAM (BISAM, QISAM)
● VSAM Data Sets
Data Set Structure Access Method
Entry-Sequenced Data Set (ESDS) VSAM
Key-Sequenced Data Set (KSDS) VSAM
Relative Record Data Set (RRDS) VSAM
Linear Data Set (LDS) VSAM/DIV (data-in-virtual)
Chapter 1. TSAM Introduction 1

Note
In Hitachi VOS3 VSAM, an LDS is called flat data set (FDS).
As shown in the tables, an access method used to process a specific type of data set is
determined by its structure though limited number of alternative access methods may be
available. In general, each access method has an interface and one or more utility programs
that first organize data into a particular data set structure and then process the data sets. Access
methods are offered as system library functions and services.
Mainframes provide many access methods for data retrieval, including VSAM. OpenFrame also
supports many access methods including TSAM.
Data Sets Supported by TSAM

TSAM supports the following VSAM data sets except LDS:
● Entry-sequenced data sets (ESDS)
● Key-sequenced data sets (KSDS)
● Relative record data sets (RRDS)
● Variable-length RRDS (VRDS)
1.3. TSAM Functions

TSAM functions are defined as part of the TSAM API. For more information about the functions,
refer to "Chapter 3. API".
The functions can be classified into three types:
● Connection and Data Set Open/Close
These functions are used to prepare control information for an application using TSAM data
sets (CONN and OPEN/CLOSE).
2 OpenFrame TSAM Guide

● Data Set Management
These functions are used to create and delete data sets. They are also used to retrieve the
status information about the data sets and change their attributes (CREATE, REMOVE, STAT,
and ALTER).
● Data Set Record Managing Functions
These functions are used to manage specific data set records (READ, WRITE, REWRITE,
DELETE and BROWSE).
TSAM uses the three types of functions to process data and saves the information for the
following purposes:
● Catalog Information
TSAM maintains information about data sets and disk space.
All TSAM data sets must be defined in a catalog, which stores methods used to process data
sets and information used to define structures. Any TSAM data sets not defined in a catalog
cannot store records. The catalog information itself is a TSAM data set.
● User Data Sets
User data sets are created by users through applications in order to save and process data.
TSAM supports four different types of data set structures (KSDS, ESDS, RRDS, and VRDS)
to manage user data sets. Each data set type has different methods for saving and accessing
records.
1.4. TSAM-Related Modules

The following are TSAM-related modules.
Module Description
ICF OpenFrame integrated catalog facility library.
AMS OpenFrame access method service library.
IDCAMS(JSCVSUT/KQCAMS) Access method service command utility.
Note
IDCAMS is equivalent to Hitachi VOS3 VSAM's JSCVSUT utility and XSP/MSP VSAM's
KQCAMS utility.
Chapter 1. TSAM Introduction 3

Chapter 2. Data Sets
This chapter describes how to configure, manage, and process TSAM data sets.
2.1. Data Set Structures

TSAM stores data records in sequence, based on a unique record key, record number, or record
byte address. It can directly or sequentially process either fixed-length or variable-length records.
TSAM supports the following four data set structures:
Structure Description
Entry-sequenced data set (ESDS) Entry-sequenced data set
Key-sequenced data set (KSDS) Key-sequenced data set
Relative record data set (RRDS) Fixed-length relative record data set. Data set made up
of numbered, fixed-length records.
Variable Length RRDS (VRDS) Variable-length relative record data set (VRDS or VRRDS).
It is made up of numbered, variable-length records.
A data set structure is determined by the characteristics of data set records and the processing
methods used by programs to handle the data set.
Chapter 2. Data Sets 5

The following table compares features of the TSAM data set structures.
ESDS KSDS Fixed Length RRDS Variable Length

RRDS
Stores records in the Stores records in Stores records in the Stores records in
order of input ascending order of the order of the relative the order of the
included keys record number (RRN) relative record
assigned to each record number (RRN)
assigned to each
record
Can store fixed or Can store fixed- or Can store fixed-length Can store
variable length records variable-length records records only variable-length
records only
Direct access using Direct access using the Direct access using the Direct access using
RBA record key and address RRN the RRN
Composed of data Composed of data Composed of data Composed of data

component only component and index component only component and
component index component
Alternate indexes Alternate indexes Alternate indexes not Alternate indexes

allowed allowed allowed not allowed
RBA cannot be changed RBA can be changed RRN cannot be RRN cannot be
changed changed
Adds record at the end Adds record in unused Storage locations for all Adds record in
of data set area or at the end of possible records are unused area or at
data set pre-allocated the end of data set
Once a record is added, When a record is Free space resulting When a record is
it cannot be deleted. deleted or modified, the from a deleted record deleted or modified,
However, a record can excess space becomes can be used to store the excess space
be overwritten by free space and can be other records. becomes free space
another of the same used to add a record or and can be used to
size to update its change a record's add a record or
content. length. change a record's
length.
Able to store records Able to store records Unable to store records Unable to store
larger than the block larger than the block larger than the block records larger than
size size size the block size

2.1.1. ESDS
The ESDS structure is very similar to non-VSAM data sets in that records are sorted according
to order of input. All new records added to a data set are stored at the end of the data set. Once
saved, records in an ESDS cannot be deleted. You can mark the target record with a delete
symbol for logical deletion, but the record is not deleted physically in the data set.
The ESDS structure supports modification of a record as long as there is no change in the record
length. To change the length of a record, you can mark it as deleted and add a new record to
the end of the data set. If changes must be made frequently while an application is running, it
may be better to use another data set type.
TSAM supports the following access methods for ESDS:
● Sequential Access
During sequential access, records are accessed in the same order that they are stored in the
data set. The starting position of each record is generally called record byte address (RBA),
which is determined when a record is created and cannot be changed. During sequential
access, you only need to provide the RBA of the first record in the data set. By default, the
first record of the data set is the starting location for sequential access. For the following
sequential access, the accessed RBA is reported to you.
● Direct Access
To directly access a record in an ESDS, you must specify the RBA of the record. A successful
creation and access of a record returns the RBA of the record. This RBA and alternate key
comprise an alternate index. With the alternate key, you can access a record.
Note
Direct access may not be used in applications which use the RBA values for general tasks.

2.1.2. KSDS
Unlike an ESDS, records in a KSDS are placed in ascending order according to the value of
this key. The KSDS structure can be used to store both fixed-length and variable-length records.
When a new record is added, it is logically inserted into the correct position within the data set
according to its key value.
The key field has the following characteristics:
● The length and the location of the key field is consistent in every record. The key must be
1-256 byte long.
● Records with duplicate key values are not permitted – each must have a unique key.
● Key length and location may not be modified after they have been defined. Even if no record
exists in a data set, key information may not be modified. Modification of key information can
only occur after removal of the data set.
● In the case of spanned records, where the length of a record is larger than a single block size,
the key must be included in the first block where the record is stored.
TSAM provides KSDS structures with the following three types of access methods:
The sequential access method is used in KSDS during the initial loading of a data set, and
can also be used for reading, writing, updating, adding, and deleting records.
To efficiently manage KSDS, VSAM uses the data component that stores data from the data
set, and the index component that allows quick access to the records, according to the key
values. In the sequential access of a KSDS, TSAM only uses the sequence set of the index
component to find the next record's location. You do not have to provide the key value of the
next record to access.
The index component's upper index set does not need to be processed over and over again,
allowing for sequential access to be performed quickly. Using the index component, TSAM
can quickly access data records in either ascending or descending order of key value. Because
of this speed, the sequential access method is very useful for retrieving multiple records at
once.

[Figure 2.1] Index Component – Index Set and Sequential Set
● Direct Access
The direct access method is used for reading, writing, updating, and deleting an existing
record. To directly access a record stored in a data set, you must provide the record's key
value. You can provide either the whole key value or the beginning part of the key. In the
latter case, TSAM returns the first record that matches the given key fragment.
When directly accessing a record, TSAM checks the key provided by the user against the
index component to find the physical location of the requested record. Unlike sequential
access, direct access must process the index component's index set for each and every
access.
● Skip-Sequential Access
This access method combines the advantages of sequential access method and direct access
method. First, an RBA is supplied and the direct access method is used to point to a specific
record. Then, the sequential access method is used to read sequential records. The direct
access method can be used again, even after the sequential access, by supplying a new
RBA.

2.1.3. RRDS
In the fixed-length RRDS structure, new records are stored in preset, fixed-length slots. Each
slot in the data set is given a number, which is used to sort the data set. Multiple fixed-length
slots may exist in a single data block.
The following shows a recommended way to set the data block size. Other methods may cause
unusable space or fragmentation in an RRDS.
Fixed record length x number of records per block + overhead
Because an RRDS stores fixed length records, accessing data record is very efficient – once
you know the record number, you can easily identify its location after a simple calculation.
However, fixed-length records sorted by slot numbers may not be useful for all application
domains. As a result, fixed-length RRDS is used in special cases.
TSAM provides RRDS structures with the following three access methods:
RRDS sequential access is similar to that of ESDS. slots not in use are automatically ignored
by the sequential access.
● Direct Access
In RRDS direct access, the user must provide the RRN of the record to access. TSAM can
easily find the location of the record using the RRN. The RBA of the record cannot be used
in RRDS direct access.
● Skip-Sequential Access
Skip-sequential access is handled internally similarly to the RRDS direct access mentioned
above. The user does not have to provide an RRN while sequentially processing.
2.1.4. VRDS
VRDS is a RRDS-type data set that can store variable-length records. A VRDS functions in the
same way as an RRDS - access methods and user parameters for specifying a record remain
the same in both structures.
For internal structure of VSAM, however, a method similar to the one used in a KSDS is used
in processing VRDS structures. Because each record may have a variable length, the location
of each record cannot be calculated solely from its RRN. Therefore, each record is sorted in
ascending order and indexed, like a KSDS, but according to RRN rather than a user-defined
key.

This RRN is not stored within the record, unlike the key in a KSDS. The index component relates
each record's RRN to its RBA, which allows it to be located by an access method.
2.1.5. Alternate Index

An alternate index (AIX) allows the access of logical records stored in a KSDS or ESDS cluster
by more than one key field. By using an alternate index, the need to store the same data in
multiple data sets simply for the purpose of processing it according to a different key field can
be eliminated.
The DEFINE ALTERNATE INDEX command of IDCAMS is used to define an alternate index,
and the BLDINDEX command is used to accumulate AIX data.
● Base Cluster
The original data set that an alternate index points to is called the base cluster. One base
cluster can have multiple alternate indexes. Any part of the records in base cluster can be
specified as an alternate key, even the primary key of the base KSDS cluster itself can be
used as an alternate key.
● Secondary Key
The data component of the secondary key stores the value of the secondary key and its
corresponding base keys in records. A secondary key is a field within a record that can be
used for searching and, unlike the primary key, does not need to be unique within a data set.
As a result, a single secondary key may correspond to several different primary keys. Consider
the example of a retail store, where the primary key within each record would be the UPC of
an item and the secondary key, its department. Obviously, one secondary key (the produce
department) corresponds to many primary keys (oranges, apples, and bananas).
Alternate Index Path

The alternate index path is a catalog entry that must first be defined before accessing a base
cluster (KSDS or ESDS) using an alternate index. An alternate index path should be defined
for each alternate index that links to a base cluster. An access path can be defined using the
IDCAMS DEFINE PATH command, and is associated with a specific alternate index using the
PATHENTRY parameter.
Direct access to the alternate index is possible without using the alternate index path, but in
this case the alternate index itself is handled as a separate KSDS cluster. When an application
uses an alternate index access path for processing a data set, TSAM internally opens the base
cluster and the index cluster together. If, on the other hand, the alternate index is opened directly
without using the alternate index path, TSAM opens the alternate index only, not the base
cluster.

[Figure 2.2] Access Path Concept
2.2. Managing Data Sets

Data set management encompasses the various tasks that you may undertake to configure,
identify, store, and read data sets within a system.
Data set management involves the following tasks:
● Data set creation
To access a TSAM-managed data set through an application or utility program, you must
create a data set.
● Data set deletion
To use system resources efficiently, you need to delete unused data sets.

● Data set inquiry and attribute modification
You can change attributes of an existing data set. Changes may be limited if the data set
already holds records or the current status of the data set makes changes unavailable.
● Record loading and copying
You can load records to an existing data set or copy the records to another data set for backup.
● Catalog management
Similar to user data sets, the catalog is a data set. In a way, cataloging is equivalent to loading
records to the catalog data set or changing the records. Therefore, managing the catalog
involves all the tasks previously listed.
Note
1. For information about OpenFrame security module TACF, refer to OpenFrame TACF
Administrator's Guide.
2. Some mainframe security features (IBM/Fujitsu RACF and Hitachi TRUST) including
password-protected data sets with expiration date are not supported in OpenFrame.
To perform these tasks, you can write a program using the TSAM API. In general, most
administrative tasks can be performed easily by using the commands provided by the IDCAMS
(JSCVSUT/KQCAMS) utility.

The following is a list of programs and utilities used to manage data sets.
Utility/Program Description
baseinit Program used to create or delete catalogs and VTOC system

tables needed during OpenFrame installation.
voladd Program used to create additional space needed for volume use
during OpenFrame installation.
IDCAMS (JSCVSUT/KQCAMS) Utility used to manage mainframe data sets (VSAM and
Non-VSAM) and catalog information.
Note
Only the main commands of the IDCAMS (JSCVSUT/KQCAMS) utility are covered in this
guide. For information about other commands of the utility, refer to OpenFrame Utility
Reference Guide.
2.2.1. baseinit
The baseinit tool is used to create or delete the catalog, VTOC, and LOCK system tables needed
during OpenFrame installation.
Usage
Execute baseinit as follows:
Usage: baseinit create <connection> [options]

| baseinit remove <connection> [options]
● Input parameters
Parameter Description
create Creates the specified table.
remove Removes the specified table.
<connection> ODBC section name set in the ofsys.conf file.
● [options]
[-t tablespace] Tablespace to create the table in.
This option is required in Tibero and Oracle, and not used in MS SQL.

Examples
The following example creates and then removes the catalog and VTOC system tables in the
DEFVOL tablespace using the ODBC section name, SYS1_ODBC, specified in the ofsys.conf
file of Tibero or Oracle.
$ baseinit create SYS1_ODBC -t DEFVOL

$ baseinit remove SYS1_ODBC -t DEFVOL
The following example creates and then removes the catalog, VTOC, and LOCK system tables
using the ODBC section name, SYS1_ODBC, specified in the ofsys.conf file of MS SQL.
$ baseinit create SYS1_ODBC

$ baseinit remove SYS1_ODBC
Environment Configuration
The baseinit tool uses the DBCONN setting in the [ICF_CATALOG] section of the ds.conf file,
and the specified DBCONN value must be configured in the ofsys.conf file.
<ds.conf>
[ICF_CATALOG]
DBCONN=SYS1_ODBC
<ofsys.conf>
[SYS1_ODBC]
DATABASE=O7
USERNAME=tibero
PASSWORD=tmax
2.2.2. voladd
The voladd tool creates and deletes management space for a volume, and adds volumes during
OpenFrame operations. It also saves mapping information to use TAPE when installing
OpenFrame for the first time. To use this tool, tablespaces and the volume.conf file must be
configured.
Usage
The voladd tool can be invoked as shown below:

Usage: voladd define <volser> [<dirpath>]
| voladd delete <volser> [options]
| voladd switch <volser> <dirpath>
define Creates management space to use a volume.
delete Deletes management space to use a volume.
switch Switches a TAPE volume to another directory.
<volser> Serial number of a volume to create or delete.
<dirpath> UNIX directory of a TAPE volume.
Examples
The following creates management space for a volume named 100000.
$ voladd define 100000
The following creates and deletes management space for a volume named VSPOOL.
$ voladd define VSPOOL

$ voladd delete VSPOOL
Environment Configuration
The voladd tool uses DBCONN connection information registered in the [ICF_CATALOG] section.
The DBCONN name must be specified in the ofsys.conf file.
<ds.conf>
[ICF_CATALOG]
DBCONN=SYS1_ODBC
<ofsys.conf>
[SYS1_ODBC]
DATABASE=O7
USERNAME=tibero
PASSWORD=tmax
2.2.3. IDCAMS (JSCVSUT/KQCAMS)

IDCAMS (JSCVSUT/KQCAMS) is a utility used to manage mainframe data sets (VSAM and
non-VSAM) and catalog information.

IDCAMS (JSCVSUT/KQCAMS) executes command inputs from SYSIN. Each command input
consists of a data set management command and its options or parameters.
IDCAMS (JSCVSUT/KQCAMS) uses the existing mainframe IDCAMS (JSCVSUT/KQCAMS)

commands that pertain to OpenFrame VSAM data sets (TSAM), OpenFrame non-VSAM data
sets, and catalogs. It can be easily used by anyone who is familiar with mainframe IDCAMS
(JSCVSUT/KQCAMS). OpenFrame IDCAMS (JSCVSUT/KQCAMS) can be run either from the
UNIX command prompt or as a batch job using JCL.
The following describes the OpenFrame IDCAMS (JSCVSUT/KQCAMS) commands.
Command Function
ALTER Changes the attributes of a data set or catalog.
BLDINDEX Makes an ALTERNATE INDEX for the specified data set.
DEFINE ALIAS Used to define ALIAS for non-VSAM data set or user catalog.
DEFINE ALTERNATEINDEX Defines an alternate index. An alternate index data set supports
an alternate indexing method for the data set (base cluster).
Use the DEFINE ALTERNATEINDEX command to define the

alternate index data set.
VSAM access method automatically updates alternate indexes

when a record is added to or deleted from the base cluster to
maintain the alternate indexes on the base cluster.
DEFINE CLUSTER Defines a VSAM data set by specifying required and optional
attributes.
DEFINE Defines catalog items for generation data group (GDG).

GENERATIONDATAGROUP
DEFINE NONVSAM Defines catalog items for non-VSAM data set (physical sequence
data sets).

Command Function
DEFINE PATH Defines a direct access path or an alternate index path to the
base cluster.
The RELATE parameter of the DEFINE ALTERNATEINDEX

specifies the relationship between the alternate index and the
base cluster, but the DEFINE PATH must be used define the
access path to the base cluster.
DEFINE PATH specifies a path between an already defined

alternate index and the base cluster. The PATH is an access path
to a single base cluster through an alternate index, and it
represents as a virtual catalog item with only logical
characteristics.
DEFINE USERCATALOG Defines a user catalog.
DELETE Deletes VSAM/non-VSAM data sets and catalogs.
Use this command to delete a VSAM or non-VSAM data set or

catalog data set item by specifying the data set or the catalog
item and the catalog name.
EXPORT Exports a catalog and VSAM data set as a portable data set, or
creates a backup copy.
IMPORT Imports an exported catalog or VSAM data set, or restores a

backed-up data set.
LISTCAT Displays information about VSAM/non-VSAM data sets registered

in a catalog.
Use this command to output various information about data sets

defined in the catalog. The output is organized into the following
categories:
– Attributes of the catalog item
– Dates of creation, update, and expiration
– Data protection information
– Data set access statistics
– Space allocation information
– Data set structure information
PRINT Prints records in VSAM/non-VSAM data sets.

Command Function
REPRO Copies data between VSAM/non-VSAM data sets.
Use this command to copy a VSAM or non-VSAM data set to

another data set that is already defined with the DEFINE
command. A VSAM data set must be registered in the catalog.
Because a mainframe catalog is normally saved in a single KSDS

cluster, REPRO can be used to copy the contents of a catalog.
It is also very common to write a record into the data set in an
application instead of using REPRO.
However, REPRO is mainly used to create data set backups for

management purposes regardless of the record content.
VERIFY Checks the data set information in the catalog including record
count after an abnormal termination of a VSAM data set and
corrects any inconsistent information.
Note
1. When a VSAM data set is closed, the last accessed record and its record number are
saved to the catalog. Any abnormal termination of the data set may cause inconsistency
between the data in the catalog and the data in the actual data set. To correct inconsistency,
use the VERIFY command.
2. As IDCAMS counterpart, Hitachi VOS3 VSAM utility is JSCVSUT and XSP/MSP VSAM
utility is KQCAMS. For detailed information about the IDCAMS (JSCVSUT/KQCAMS) utility,
refer to OpenFrame Utility Reference Guide.
2.3. Processing Data Sets

Application programs process data sets in the following order in OpenFrame.
1. Allocates a data set and logically links it to the program.
The data in the allocated data set can be accessed using the interface provided by each
access method.
Data set allocation involves the following two tasks:
– Allocate disk space for the new data set.
A data set can be allocated using the following methods:

Method Description
Access method services Use IDCAMS (JSCVSUT/KQCAMS) ALLOCATE command.

(AMS)
Job control language (JCL) Define data sets in JCL.
– Logically link the JOB STEP with the data set.
2. Use the data set's DDNAME to open the data set.
3. Use access method to read or write data to/from the data set.
4. Close the data set.
5. Unallocate the data set.
Note
Non-VSAM data sets are similarly processed.
2.3.1. Allocate/Unallocate
When you attempt to access an existing data set, the system uses the specified data set
information in JCL and the catalog to find the data set address on a physical storage device.
When you try to create a new data set, the system uses the specified data set information to
secure storage space for the data set on disk. The process of finding the storage device address
for an existing data set or securing storage space for a new data set is called allocation.
● Allocation for a new data set requires information about the volume and device where the
data set is to be created and the data set size.
● Allocation for an existing data set requires the volume and device information. If the data set
is already in the catalog, only the data set name is required.
When allocating a data set to process it, the system prepares a structure called the data control
block (DCB). The DCB is composed of buffers used to contain all the information required for
data set processing and real-time I/O reporting.
Like the data set must be allocated before processing, it must be unallocated after processing
the data set. The data set disposition method described in the JCL specifies how the system is
to process the data set when unallocating it. For example, the disposition method for a temporary
data set decides whether to retain the data set until the task is finished or to delete it right away.

The disposition method for a permanent data set decides whether to register it to the master
catalog or to the user catalog.
2.3.2. Open/Close
Before accessing a specific data set, the application must use the OPEN interface to open a
data set.The OPEN interface logically links applications, access methods, and data sets together
using a DCB.
The OPEN interface creates the DCB structure, initializes data sets, and prepares system buffer
for data set processing.
The DCB structure is composed of the following three components:
● Catalog information
● JCL DD statements
● Application information
The CLOSE interface disconnects the link between the application and the data set.
When the data set is closed, the system performs the following tasks:
– Recording data that has not been physically written
– Updating catalog information (such as data set size)
– Releasing the DCB structure used for data set processing
2.3.3. OPEN Mode

When opening a data set, you must specify an OPEN mode. The OPEN mode used depends
on whether the application is performing a read, write, or read/write operation.
Data sets can be accessed through one of the following four OPEN modes:
● INPUT Mode
When the INPUT mode is specified, the data set may only be read. An error occurs when you
attempt to modify the data set by writing, updating, or deleting a record. If an attempt is made
to open a non-existent data set and the OPTIONAL parameter is not set, an error message
is displayed.
● OUTPUT Mode

When the OUTPUT mode is specified, the application creates a new data set to write records
in. If an attempt to read a record from the data set is made, an error occurs. When an existing
data set is opened for writing in OUTPUT mode, all previous records in the data set are
deleted.
● INPUT / OUTPUT Mode
When INPUT / OUTPUT mode is specified, it is possible to read from and write to the data
set. If an attempt is made to open a non-existent data set and the OPTIONAL parameter is
not set, an error message is displayed.
● EXTEND Mode
Unlike the OUTPUT mode, the EXTEND mode is used for writing to pre-existing data sets.
In EXTEND mode, the application writes new records at the end of the file. If an attempt is
made to open a non-existent data set and the OPTIONAL parameter is not set, an error
message is displayed.
Note
If a non-existent data set is opened and the OPTIONAL parameter is set, an empty data set
will be created.
2.3.4. Access Mode

Data set access mode is the processing order of records in a data set, and is not an attribute
of the data set itself but represents the method the application is going to access the data set.
The following are data set access modes.
Sequential access mode reads or writes the records from the first record to the last record in
order. Sequentially structured data sets, such as ESDS, RRDS and KSDS, can only be
accessed sequentially. For RRDS, the order is determined by RRN and KSDS by a single
alphanumeric key from the primary key or the secondary keys.
● Random Access
Random access mode processes records in the order the user wants. All ESDS, RRDS and
KSDS support random access. To access data set records in this mode, the user must specify
the record recognizers such as RBA, RRN, and key values depending on the data set structure
type.

● Dynamic Access
Dynamic access mode can use both sequential access and random access to the data set
during application runtime. All ESDS, RRDS, and KSDS support dynamic access.
2.3.5. Record Access

After a data set is opened, records within the data set can be processed using various interfaces
provided by the access method. The READ interface, for example, can be used to read a record
from the data set and the WRITE interface to add records to the data set.
The following are the four record access interfaces.
● WRITE (Insert/Add Records)
A new record is added to the end of a sequential data set.
In a VSAM ESDS, you cannot insert a new record in the middle of a data set – all records
are added at the end of the data set. VSAM KSDS and RRDS, however, allow new records
to be added anywhere in the data set using the record key for KSDS or RRDS. Attempting
to add a new record with a duplicate key value triggers the DUPLICATE RECORD error
message.
● READ (Read Records)
– Sequential Access
When the application attempts the sequential access of a data set for the first time, it always
starts reading from the first record. However, if a random access has been performed on
the data set before, an internal record pointer may have been changed. In such cases, it
is recommended that the START interface be used to initialize the record pointer before
using the sequential access interface.
– Random Access
VSAM ESDS, KSDS and RRDS support random access through record identifiers. Random
access mode is not affected by the internal record pointer. To find the desired record, one
of the following is required for each VSAM data set type.
Data Set Information
KSDS KEY
RRDS RRN
ESDS RBA

Note
Although an ESDS can be randomly accessed by using the RBA value, this is not usually
appropriate for most business applications.
● REWRITE (Update Records)
The REWRITE interface is used to update a record. However, the primary key of a KSDS
record cannot be updated.
● DELETE (Delete Records)
The DELETE interface is used to delete a record. After deleting a RRDS record, the space
can be reused. However, an ESDS record cannot be deleted.
2.3.6. Browsing
The following are the interfaces supported for browsing.
Interface Description
START_BR Starts browsing as when reading a record from TSAM.
Initializes the browser's pointer without reading any records.
READ_NEXT Reads records sequentially from the location specified by the START_BR
interface.
READ_PREV Reads the data set in reverse order.
RESET_BR Changes the current browsing pointer when browsing starts.
The pointer can also be changed simply by modifying the RIDFLD

parameter of the READ_NEXT or READ_PREV interface.
2.3.7. Transaction
A transaction is a logical task unit representing a collection of one or more consecutive tasks
that must be processed together.
The following are transaction related interfaces.
Interface Description
COMMIT Commits the current transaction.
ROLLBACK Rolls back the current transaction.

Chapter 3. API
This appendix describes TSAM API client libraries that can be used in application programs.
3.1. Overview
TSAM APIs are categorized as follows:
● Connection
API Description
tsam_connect() Connects to the TSAM Server.
tsam_disconnect() Disconnects from the TSAM Server.
● Transaction
API Description
tsam_commit() Commits the current transaction.
tsam_rollback() Rolls back the current transaction.
● File Management
API Description
tsam_create() Creates a new data set.
tsam_remove() Deletes the current data set.
tsam_truncate() Deletes all contents of a data set.
tsam_alter() Alters attributes of a data set.
tsam_stat() Retrieves statistics on a data set.
tsam_filename() Changes a data set name to a filename.
● File Open/Close
API Description
tsam_open() Opens a data set for processing.
tsam_close() Closes a data set that was opened for processing.
Chapter 3. API 25
● Record Access
API Description
tsam_start() Moves the internal record pointer for sequential processing.
tsam_read() Reads a record from a data set.
tsam_unlock() Unlocks a record in a data set.
tsam_write() Writes a record in a data set.
tsam_rewrite() Rewrites a record in a data set.
tsam_delete() Deletes a record in a data set.
● Browsing
API Description
tsam_start_br() Prepares a browser for sequential processing of a data set.
tsam_reset_br() Resets, or moves, the pointer of a current data set browser.
tsam_end_br() Closes the data set browser in use.
tsam_read_next() Reads the next record using the data set browser.
tsam_read_prev() Reads the previous record using the data set browser.
3.2. Connection
3.2.1. tsam_connect()
Connects to a TSAM server. The connection to a TSAM server must be made before using
TSAM commands. tsam_connects takes the user ID, password, and database service name
as input and returns the connection ID (cd).
● Prototype
int tsam_connect(tsam_connect_t *conn, int flags);

● Parameters
conn (in) Connection information (user ID, password, and database). For more
information, refer to the description of tsam_connect_t struct.
flags (in) TSAM connection flags. Use '|' (bitwise or) operator to delimit multiple
flags.
Available connection flags are as follows:
– TSAM_TX_READWRITE: connects via a READ/WRITE

transaction.
– TSAM_TX_READONLY: connects via a READ ONLY transaction.
– TSAM_TX_SERIALIZABLE: connects via a SERIALIZABLE

transaction.
– TSAM_TX_AUTOCOMMIT: connects via an AUTO COMMIT

transaction.
tsam_connect_t struct is defined as follows:
typedef struct {
char username[TSAM_USERNAME_LEN + 1];
char password[TSAM_PASSWORD_LEN + 1];
char database[TSAM_DATABASE_LEN + 1];
} tsam_connect_t;
Member Description
username User ID.
password Password.
database TSAM database service name.
● Return Value
When a connection to a TSAM server is made, the connection ID (cd) is returned. If an error
occurs, a negative value is returned.
Chapter 3. API 27
3.2.2. tsam_disconnect()
Disconnects from a TSAM server. When disconnected, TSAM commands can no longer be
used.
● Prototype
int tsam_disconnect(int cd);
● Parameters
cd (in) Connection ID that was used to connect via tsam_connect(). If an

invalid connection ID is given, the error code
TSAM_ERR_INVALID_CONN_ID is returned.
● Return Value
When a connection to a TSAM server is closed, 0 is returned. If an error occurs, a negative

value is returned.
3.3. Transaction
3.3.1. tsam_commit()
Commits the current transaction.
● Prototype
int tsam_commit(int cd);
● Parameters

● Return Value
When the transaction is committed successfully, 0 is returned. If an error occurs, a negative

value is returned.

3.3.2. tsam_rollback()
Rolls back the current transaction.
● Prototype
int tsam_rollback(int cd);
● Parameters

● Return Value
When the transaction is rolled back successfully, 0 is returned. If an error occurs, a negative
value is returned.
3.4. File Management
3.4.1. tsam_create()
Creates a new data set. This can be performed after successfully connecting to the TSAM
server.
● Prototype
int tsam_create(int cd, char *filename, tsam_create_t *create);
● Parameters

Chapter 3. API 29
filename (in) Filename. Use the tsam_filename() command to change the data
set name to the filename.
The filename is registered in the catalog when the data set is first
created. Hence, the data set name does not need to be changed
every time the data set is opened. The concept of filename is different
from that of the data set name. For more information, refer to the
description of tsam_filename().
create (in) Create options. For more information, refer to the description of
tsam_create_t struct.
tsam_create_t struct is defined as follows:
typedef struct {
/* association information */
char dataname[TSAM_NAME_LEN + 1];
char indexname[TSAM_NAME_LEN + 1];
/* volumes information */
char volser[8]; /* volume serial number */
/* allocation information */
...
/* VSAM attributes */
int32_t cisize; /* size of control interval in bytes */
int16_t avglrecl; /* average record length */
int16_t maxlrecl; /* maximum record length */
int16_t keyfmt; /* KSDS key format */
int16_t keypos; /* KSDS key position */
int16_t keylen; /* KSDS key length */
...
/* VSAM information */
uint8_t vsamtype; /* VSAM data set type information */
...
/* component attributes */
...
} tsam_create_t;
● Return Value
When the data set is created successfully, 0 is returned. If an error occurs, a negative value
is returned.

3.4.2. tsam_remove()
Deletes a data set. This can be performed after successfully connecting to the TSAM server.
● Prototype
int tsam_remove(int cd, char *filename);
● Parameters

set name to the filename. The concept of filename is different from
that of data set name. For more information, refer to the description
of tsam_filename().
● Return Value
When the data set is deleted successfully, 0 is returned. If an error occurs, a negative value
is returned.
3.4.3. tsam_truncate()
Deletes the contents of a data set. This can be performed after successfully connecting to the
TSAM server.
● Prototype
int tsam_truncate(int cd, char *filename, tsam_file_t *file);
● Parameters

Chapter 3. API 31
of tsam_filename().
file (in) tsam_file_t struct that contains the data set meta information retrieved
from the catalog. For more information, refer to the description of
tsam_file_t struct.
tsam_file_t struct is defined as follows:
typedef struct {
/* comminication handle */
...
char filename[TSAM_NAME_LEN + 1];
char dataname[TSAM_NAME_LEN + 1];
char indexname[TSAM_NAME_LEN + 1];
/* volumes information */
char volser[8]; /* volume serial number */
/* open flags */
uint32_t openflags; /* file open flags */
uint16_t permissions; /* access permission */
int16_t avglrecl; /* average record length */
int16_t maxlrecl; /* maximum record length */
int16_t keyfmt; /* KSDS key format */
int16_t keypos; /* KSDS key position */
int16_t keylen; /* KSDS key length */
...
/* VSAM information */
uint8_t vsamtype; /* VSAM data set type information */
...
} tsam_file_t;
Available openflags are as follows:
Flag Description
TSAM_OPEN_INPUT Opens a data set in INPUT mode.
TSAM_OPEN_OUTPUT Opens a data set in OUTPUT mode.
TSAM_OPEN_INOUT Opens a data set in INPUT/OUTPUT mode.
TSAM_OPEN_EXTEND Opens a data set in EXTENDED mode.
TSAM_ACCESS_SEQUENTIAL Opens a data set in SEQUENTIAL ACCESS mode.

Flag Description
TSAM_ACCESS_RANDOM Opens a data set in RANDOM ACCESS mode.
TSAM_ACCESS_DYNAMIC Opens a data set in DYNAMIC ACCESS mode.
TSAM_LOCK_EXCLUSIVE Opens a data set EXCLUSIVELY.
TSAM_FLAG_OPTIONAL Creates a data set if a data set does not exist.
TSAM_FLAG_REPORT_RUNTIME Uses the runtime reporting command.
● Return Value
When the data in the data set are deleted successfully, 0 is returned. If an error occurs, a
negative value is returned.
3.4.4. tsam_alter()
Updates the attributes of a data set. This can be performed after successfully connecting to the
TSAM server.
● Prototype
int tsam_alter(int cd, char *filename, tsam_alter_t *alter);
● Parameters

of tsam_filename().
alter (in) New attribute values. For more information, refer to the description
of tsam_alter_t struct.
tsam_alter_t struct is defined as follows:
typedef struct {
...
int32_t avglrecl;
Chapter 3. API 33
int32_t maxlrecl;
int16_t keypos;
int16_t keylen;
...
} tsam_alter_t;
● Return Value
When the attributes are updated successfully, 0 is returned. If an error occurs, a negative
value is returned.
3.4.5. tsam_stat()
Retrieves statistics on a data set. This can be performed after successfully connecting to the
TSAM server.
● Prototype
int tsam_stat(int cd, char *filename, tsam_stat_t *stat);
● Parameters

of tsam_filename().
stat (out) Stats. For more information, refer to the description of

tsam_stat_t struct.
tsam_stat_t struct is defined as follows:
typedef struct {
/* allocation information */
...
/* statistics information */
int32_t rec_deleted; /* number of deleted records */
int32_t rec_inserted; /* number of inserted records */
int32_t rec_retrieved; /* number of retrieved records */
int32_t rec_updated; /* number of updated records */

int32_t rec_total; /* number of logical records */
...
} tsam_stat_t;
● Return Value
When the successfully, 0 is returned. If an error occurs, a negative value is returned.
3.4.6. tsam_filename()
Changes the data set name to the filename. This can be performed after successfully connecting
to the TSAM server.
● Prototype
int tsam_filename(int cd, char *ds_name, char *filename);
● Parameters

ds_name (in) Data set name. If tsam_filename() is invoked multiple times on the
same data set name, different file names may be returned each time.
Therefore, register the filename in the catalog when the data set is
first created, and then retrieve the filename from the catalog for
subsequent operations.
filename (out) Filename. The concept of filename is different from that of data set
name. According to the implementation of TSAM, the data set name
is changed to the physical filename or table name. Use the
tsam_filename() command to change the data set name to the table
name.
Note
Due to different constraints on table names for each database product, data set names cannot
be used directly as table names. For example, table names in Tibero or Oracle databases
cannot contain a period (.) and are limited to 30 characters in length.
Chapter 3. API 35
● Return Value
When the data set name has been changed successfully, 0 is returned. If an error occurs, a
3.5. File Open/Close
3.5.1. tsam_open()
Opens a data set for processing. This can be performed after successfully connecting to the
TSAM server. Data set records cannot be accessed without opening the data set.
● Prototype
int tsam_open(int cd, int fcnt, tsam_file_t **file, tsam_report_t **report);
● Parameters

fcnt (in) Number of files (equal to number of clusters). Set to the number of
alternate indexes including the base cluster.
file (in) tsam_file_t struct that contains the data set meta information retrieved
from the catalog. For more information, refer to the description of
tsam_file_t struct.
report (in) Runtime report buffer that is used when the

TSAM_FLAG_REPORT_RUNTIME flag is set in the openflags field
of tsam_file_t. Whenever a record is retrieved, inserted, updated, or
deleted, the contents of its relevant member in the buffer are
refreshed.
Each report buffer is an array. For more information, refer to the

description of tsam_report_t struct.
tsam_report_t struct is defined as follows:
typedef struct {
/* statistics information */
int32_t rec_deleted; /* number of deleted records */

int32_t rec_inserted; /* number of inserted records */
int32_t rec_retrieved; /* number of retrieved records */
int32_t rec_updated; /* number of updated records */
} tsam_report_t;
● Return Value
When the data set is opened successfully, 0 is returned. If an error occurs, a negative value
is returned.
3.5.2. tsam_close()
Closes an opened data set. The records of a closed data set cannot be accessed.
● Prototype
int tsam_close(int fd);
● Parameters
fd (in) File ID that was used to open the data set via tsam_open(). If an
invalid file ID is specified, the error code TSAM_ERR_INVALID_FD
is returned.
● Return Value
When the data set is closed successfully, 0 is returned. If an error occurs, a negative value
is returned.
3.6. Record Access
3.6.1. tsam_start()
Moves the internal record pointer for sequential processing. This command can be used after
a data set is successfully opened.
Sequential access of a data set occurs when the records in the data set are processed in record
units. In TSAM, this is accomplished using the tsam_read() command with the
TSAM_FLAG_NEXT or TSAM_FLAG_PREV flags.
Chapter 3. API 37
The tsam_start() command can be used to move the internal record pointer to a specific record.
This pointer defines the starting record for sequential access.
● Prototype
int tsam_start(int fd, int aix_fd, void *ridfld, int keylen, int flags);
● Parameters
is returned.
aix_fd (in) AIX file ID. The tsam_file_t struct array index used in tsam_open.
ridfld (in/out) Record ID field that is used to move the record pointer to a specific
position. The record ID field is interpreted differently depending on
which flag is set.
keylen (in) Search key length used when the record ID field is the search key.
– If TSAM_FLAG_GENERIC is not set, the search key length must

match the key length of the data set.
– If TSAM_FLAG_GENERIC is set, the search key length must be

less than the key length of the data set.
flags (in) Option flags.
Available flags are as follows:
– TSAM_FLAG_KEY: Record ID value is the search key.
– TSAM_FLAG_RBA: Record ID value is the relative byte address

(RBA).
– TSAM_FLAG_RRN: Record ID value is the relative record number

(RRN).
– TSAM_FLAG_GENERIC: Search key is a portion of the key field.
– TSAM_FLAG_EQUAL: moves to the first record whose key field

equals the search key.
– TSAM_FLAG_GTEQ: moves to the first record whose key field is

greater than or equal to the search key.
– TSAM_FLAG_FIRST: moves to the first record of the data set.
– TSAM_FLAG_LAST: moves to the last record of the data set.

● Return Value
When the record pointer has been moved successfully, 0 is returned. If an error occurs, a
3.6.2. tsam_read()
Reads a record from a data set. This command can be used after a data set is successfully
opened.
The tsam_read() command is used to process a data set sequentially or directly. Sequential
processing uses the TSAM_FLAG_NEXT or TSAM_FLAG_PREV flags.
● Prototype
int tsam_read(int fd, int aix_fd, void *ridfld, int keylen, char *buf,
int *buflen, int flags);
● Parameters
is returned.
ridfld (in/out) Record ID field that is used to directly read a record at the specified
which flag is set.


buf (out) Record buffer.
buflen (in/out) Record buffer size.
Chapter 3. API 39

(RBA).

(RRN).
– TSAM_FLAG_EQUAL: moves to the first record whose key field

– TSAM_FLAG_GTEQ: moves to the first record whose key field is

– TSAM_FLAG_FIRST: moves to the first record of the data set.
– TSAM_FLAG_LAST: moves to the last record of the data set.
– TSAM_FLAG_NEXT: reads the next record of the data set

(sequential).
– TSAM_FLAG_PREV: reads the previous record of the data set

(sequential).
– TSAM_FLAG_UPDATE: locks the specified record and returns

the lock token. The token can be used as record ID field in
tsam_unlock(), tsam_rewrite(), or tsam_delete() command.
– TSAM_FLAG_NOSUSPEND: immediately returns the

TSAM_ERR_RECORD_LOCKED error code without waiting when
the record is already in the lock state.
● Return Value
When the TSAM_FLAG_UPDATE option is not set and the read operation is successful, 0 is
returned. If the TSAM_FLAG_UPDATE option is set, a lock token with an integer value greater
than or equal to 0 is returned. If an error occurs, a negative value is returned.

3.6.3. tsam_unlock()
Unlocks a record in a data set. This command can be used when the tsam_read() command is
successfully called using the TSAM_FLAG_UPDATE option.
● Prototype
int tsam_unlock(int fd, int aix_fd, int token);
● Parameters
fd (in) File ID that was used to with the tsam_read() command (also use
the lock token returned by this command as the token parameter).
If an invalid file ID is specified, the error code
TSAM_ERR_INVALID_FD is returned.
token (in) Lock token. To unlock all locked records in the data set, set the lock
token to TSAM_TOKEN_ALL_LOCKS. If an invalid lock token is
specified, the error code TSAM_ERR_INVALID_TOKEN is returned.
● Return Value
When the lock is unlocked successfully, 0 is returned. If an error occurs, a negative value is
returned.
3.6.4. tsam_write()
Writes a record to a data set. This command can be used after a data set is successfully opened.
● Prototype
int tsam_write(int fd, int aix_fd, void *ridfld, int keylen, char *buf,
int buflen, int flags);
● Parameters
is returned.
Chapter 3. API 41
ridfld (in/out) Record ID field that is used to write a record at the specified position.
The record ID field is interpreted differently depending on which flag
is set.
keylen (in) Record key length used when the record ID field is the record key.
The record key length must match the key length of the data set.
buf (in) Record buffer.
buflen (in) Record buffer size.

(RBA).

(RRN).
– TSAM_FLAG_MASSINSERT: This operation is a part of a

MASSINSERT operation.

● Return Value
When the read operation is successful, 0 is returned. If an error occurs, a negative value is
returned.
3.6.5. tsam_rewrite()
Updates a record in a data set. This command can be used after a data set is successfully
opened.
● Prototype
int tsam_rewrite (int fd, int aix_fd, void *ridfld, int keylen, char *buf,
int buflen, int flags);

● Parameters
is returned.
ridfld (in) Record ID field that is used to update a record at the specified
which flag is set.
keylen (in) Record key length used when the record ID field is the record key.
The record key length must match the key length of the data set.

(RBA).

(RRN).
– TSAM_FLAG_TOK: Record ID field is the lock token.
– TSAM_FLAG_CURRENT: updates the last record read via

tsam_read().

● Return Value
When the rewrite operation is successful, 0 is returned. If an error occurs, a negative value
is returned.
Chapter 3. API 43
3.6.6. tsam_delete()
Deletes a record from a data set. This command can be used after a data set is successfully
opened.
● Prototype
int tsam_delete(int fd, int aix_fd, void *ridfld, int keylen, int flags);
● Parameters
is returned.
ridfld (in) Record ID field that is used to delete a record at the specified
which flag is set.




(RBA).

(RRN).
– TSAM_FLAG_TOK: Record ID field is the lock token.
– TSAM_FLAG_CURRENT: deletes the last record read via

tsam_read().

● Return Value
When the record is deleted successfully, the number of deleted records is returned. If an error
occurs, a negative value is returned.
3.7. Browsing
3.7.1. tsam_start_br()
Starts a new browser to sequentially process a data set. This can be used after a data set is
successfully opened.
TSAM provides a browser pointer in addition to the internal record pointer used for sequential
processing of data sets. Multiple browsers can be created on the same data set, and sequential
record processing through the browser uses the tsam_read_next() or tsam_read_prev()
commands.
Chapter 3. API 45
● Prototype
int tsam_start_br(int fd, int aix_fd, int reqid, void *ridfld, int keylen,
int flags);
● Parameters
is returned.
reqid (in) Request ID used to prepare for a new browser.
Use a positive integer greater than equal to 0. If an attempt is made

to open a browser using a duplicate request ID, the error code
TSAM_ERR_DUPLICATE_REQUEST_ID is returned.
ridfld (in/out) Record ID field that is used to move the internal pointer to the
specified position. The record ID field is interpreted differently
depending on which flag is set.


flags (in) Option flags. For the description of each flag, refer to
"3.6.1. tsam_start()".
● Return Value
When a new browser is started successfully, 0 is returned. If an error occurs, a negative value
is returned.
3.7.2. tsam_reset_br()
Moves the data set browser pointer. This command can be used after a browser is successfully
started.

● Prototype
int tsam_reset_br(int fd, int aix_fd, int reqid, void *ridfld, int keylen,
int flags);
● Parameters
fd (in) File ID that was used in tsam_start_br(). If an invalid file ID is

specified, the error code TSAM_ERR_INVALID_FD is returned.
reqid (in) Request ID that was used in tsam_start_br().
If an invalid request ID is specified, the error code

TSAM_ERR_INVALID_REQUEST_ID is returned.
ridfld (in/out) Record ID field that is used to move the internal pointer to the
specified position. The record ID field is interpreted differently
depending on which flag is set.


"3.6.1. tsam_start()".
● Return Value
When the browser pointer is positioned successfully, 0 is returned. If an error occurs, a

3.7.3. tsam_end_br()
Closes the data set browser pointer. This command can be used after a browser is successfully
started.
● Prototype
int tsam_end_br(int fd, int aix_fd, int reqid);
Chapter 3. API 47
● Parameters


● Return Value
When the browser pointer is closed successfully, 0 is returned. If an error occurs, a negative
value is returned.
Note
Once the pointer is closed, tsam_read_next() and tsam_read_prev() can no longer be used.
3.7.4. tsam_read_next()
Reads the next record using the data set browser. This command can be used after a browser
is successfully started.
● Prototype
int tsam_read_next(int fd, int aix_fd, int reqid, void *ridfld, int keylen,
char *buf, int *buflen, int flags);
● Parameters



ridfld (in/out) Record ID field that is used to read a record at the specified position.
is set.



(RBA).

(RRN).
– TSAM_FLAG_EQUAL: reads the first record whose key field

– TSAM_FLAG_GTEQ: reads the first record whose key field is

– TSAM_FLAG_FIRST: reads the first record of the data set.
– TSAM_FLAG_LAST: reads the last record of the data set.

● Return Value
returned.
Chapter 3. API 49
3.7.5. tsam_read_prev()
Reads the previous record using the data set browser. This command can be used after a
browser is successfully prepared.
● Prototype
int tsam_read_prev(int fd, int aix_fd, int reqid, void *ridfld, int keylen,
char *buf, int *buflen, int flags);
● Parameters


ridfld (in/out) Record ID field that is used to read a record at the specified position.
is set.


"3.7.4. tsam_read_next()".
● Return Value
returned.

Chapter 4. Administering TSAM
This chapter describes how to set up, manage, and initialize TSAM.
4.1. Environment Variables

After installing TSAM, the environment variables must be configured.
Configure the following file depending on the shell:
● korn shell: .profile of the user account used for installation/operation
● bourn shell: .bashrc or .bash_profile
The following are the environment variables required to install and operate TSAM.
Environment Variable Description
TSAM_READ_PREFETCH_FORCE Option to enable TSAM PREFETCH for tsam_read() command.

(Default: N)
TSAM PREFETCH will be enabled for the BROWSING

commands, tsam_read_next and tsam_read_prev unless
TSAM_PREFECTCH_NEVER is set to Y, regardless of this
setting.
TSAM_PREFETCH_NEVER Option to enable TSAM PREFETCH. (Y|N, Default: N)
This command is internally used to control whether to enable

TSAM PREFETCH for each OpenFrame program. This does
not need to be specified in '.profile', '.bashrc', or '.bash_profile'.
If set to Y, TSAM PREFETCH is disabled regardless of the

TSAM_READ_PREFETCH_FORCE setting.
Chapter 4. Administering TSAM 51

Environment Variable Description
TSAM_TOKEN_HASH_SIZE Performance tuning parameter for the hash table data structure
that is used by TSAM clients to manage lock tokens. (Default:
1)
A hash table data structure will have as many hash buckets

as was specified in this variable. This improves the
performance of finding lock tokens when multiple record-level
locks are requested by a single transaction. A value between
128 and 512 is recommended but it must be verified through
a performance test.
TSAM_FILENAME_MAPPING Map a TSAM data set to the specified tablespace regardless

of the volume that it is mapped to. For more information, refer
to "4.2.2. Data Set-Tablespace Mapping". (YES|NO, Default:
NO)
The following is an example of TSAM environment variable setting in Linux bash shell. Add the
setting to the '~/.bashrc' or '~/.bash_profile' file.
# TSAM
export TSAM_READ_PREFETCH_FORCE=Y
4.2. Management
This section describes other useful functions provided by OpenFrame TSAM.
4.2.1. TSAM PREFETCH

TSAM PREFETCH allows the prefetching of sequential records, reducing overall processing
time and improving performance. This is especially effective for applications that sequentially
process many small size records.
Since data is exchanged between TSAM client and server in network packet units and additional
overhead that it incurs compared to direct or random access is not significant compared to its
performance improvement effect, it is worth considering as long as the total size of records for
a single read operation is not too large. TSAM PREFETCH can be used with the following TSAM
API commands:
● Basic READ command: tsam_read()
● BROWSE READ commands: tsam_read_next/prev()

If TSAM PREFETCH is enabled for these functions, current and subsequent records in TSAM
file are read into the prefetch buffer in advance for sequential read operations. Records for
subsequent sequential read requests will be retrieved directly from the prefetch buffer.
The prefetch buffer is cleared when the pointer position is changed in the TSAM file due to a
tsam_start() or tsam_start_br() call or when the file is reopened. The TSAM PREFETCH option
is used in the aforementioned commands according to the TSAM_READ_PREFETCH_FORCE
and TSAM_PREFETCH_NEVER variable values as follows:
TSAM_PREFETCH_NEVER TSAM_READ_PREFETCH_FORCE Function TSAM

PREFETCH
Use
N N READ N
BROWSE READ Y
Y READ Y
BROWSE READ Y
Y N READ N
BROWSE READ N
Y READ N
BROWSE READ N
It is important to note that any changes made to a record by another TSAM client after it is
prefetched are not reflected immediately. This does not affect the integrity of the TSAM data
set, but applications or users may have to make another read request to get the latest value.
This is a restriction on usability that should be accepted for performance improvement. If there
is a case where performance is considered more important than usability, set
TSAM_PREFETCH_NEVER to Y.
In batch processing, a single application exclusively updates the TSAM data set and thus it is
not necessary to set "TSAM_PREFETCH_NEVER=Y". For online jobs, however, set
"TSAM_PREFETCH_NEVER=Y" to prevent varying application usability levels among
applications.
TSAM PREFETCH is not a requirement for online processing as it aims to improve performance
for batch processing a large number of small size records, and there are negligible differences
between performance of Mainframe VSAM and OpenFrame TSAM. Since
TSAM_PREFETCH_NEVER is set per process in OpenFrame, TSAM_PREFETCH_NEVER
does not need to be explicitly set by the user.

4.2.2. Data Set-Tablespace Mapping
By default, TSAM data sets are stored in the tablespace with the name of the volume that was
specified when the data sets were created. However, there might be a situation where TSAM
data sets that need to be recovered together are not stored in the same volume or are mixed
with other data sets that do not need to be recovered in the same tablespace. This creates
dependencies among online application systems as all data sets belonging to a particular
tablespace become inaccessible while it is being recovered.
[Figure 4.1] Data Sets of Different Online Systems Stored in a Single Tablespace
To avoid such situations, the data sets for the same recovery unit should be mapped to the
same volume name when the data sets are created. To do this, the VOLUME parameter must
be specified in the DEFINE CLUSTER statement in the TSAM management utility, such as
IDCAMS or JSCVSUT, that is used to create TSAM data sets. However, this entails modifying
multiple JCLs. The TSAM_FILENAME_MAPPING function can be used instead to map data
sets to a specific tablespace regardless of the volume they are defined with.
In general, TSAM data sets for online application systems such as IBM IMS, Hitachi ADM, or
Fujitsu AIM are well defined in the online application system setting so that it is easy to determine
the target list of the TSAM data sets that need to be recovered together. Therefore, it is also
easy to configure the target TSAM data sets in a separate tablespace.

[Figure 4.2] Using TSAM Data Set-Tablespace Mappings
The following are the steps for using the data set-tablespace mapping.
1. Set the TSAM_FILENAME_MAPPING environment variable.
Set TSAM_FILENAME_MAPPING for the current TSAM client to YES. If not specified, the
default value is NO.
export TSAM_FILENAME_MAPPING=YES
2. Create the tablespace to save the mapped data sets.
The following is an example of creating tablespaces in Tibero.
$ tbsql sys/tibero<<EOF
create tablespace "X" datafile 'X.dbf' autoextend on;
create tablespace "Y" datafile 'Y.dbf' autoextend on;
EOF
3. Define a data set-tablespace mapping.
Mapping is specified as a data set name-tablespace name pair in

$OPENFRAME_HOME/config/tsam_filename.conf. In the following example, the data sets
DBX.ESDS and DBX.KSDS are mapped to tablespace X while DBY.ESDS and DBY.KSDS
are mapped to tablespace Y. The volume defined for each data set when it is created will be
ignored.

DBX.ESDS = X
DBX.KSDS = X
DBY.ESDS = Y
DBY.KSDS = Y
4.3. Initialization
Before starting TSAM, it must first be initialized. The initialization involves creating the master
catalog and adding the volume to store TSAM data sets. The examples in this section assume
using Tibero as the database.
4.3.1. Creating a Tablespace for Catalog

Because TSAM catalogs are treated as TSAM data sets, a volume (tablespace) must be created
before creating a catalog.
For example, prior to creating a catalog in the volume VOLSER=100000, a tablespace that
corresponds to VOLSER=100000 must be created as follows:
SQL> CREATE TABLESPACE "100000"

DATAFILE '100000.dbf' SIZE 100M
EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;
Tablespace '100000' created.
4.3.2. Creating a System Table

After creating a volume (tablespace) for TSAM data set catalog, create the system table in the
tablespace by executing the baseinit command. Also execute the voladd command to extend
the volume for space management purposes.
The following example creates and initializes a catalog and VTOC related system table on
volume 10000. The voladd define command defines the tablespace 100000 as a volume and
then creates additional space for management.
$ baseinit create SYS1_ODBC -t 100000

Note
For more information about OpenFrame baseinit and voladd tools, refer to OpenFrame Tool
Reference Guide.

4.3.3. Adding a Volume
To add a TSAM volume, execute the CREATE TABLESPACE statement to create a TSAM
tablespace. Define the tablespace as a volume by executing voladd define.
The following is an example of adding the volume VOLSER=100001 by using the tablespace
100001.
SQL> CREATE TABLESPACE "100001"

DATAFILE '100001.dbf' SIZE 2G AUTOEXTEND ON NEXT 100M MAXSIZE 3G
EXTENT MANAGEMENT LOCAL UNIFORM SIZE 20M;

Glossary
Catalog
The catalog describes dataset attributes and the information about the volume where datasets are.
Cluster
A cluster is a set of up to two related components. For example, KSDS, allows a cluster to have one
data component and one index component. The cluster concept simplifies TSAM processing by
combining the data component and the index component into one entity which can be registered to
a catalog.
Component
A component is a part of a TSAM dataset. Each component has a name and is registered to both
catalog and the VTOC. KSDS and VRDS have data components and index components, while
ESDS and RRDS have only data components.
● Data Component
The data component is a part of an alternate index, the catalog, or a TSAM dataset which includes
data records.
● Index Component
The index component is used to create a hierarchical structure so that records can be quickly
found by the direct access method. If given a key, TSAM uses the index components to narrow
the number of records that must be searched to find a given record.
DSNAME
When a new dataset is allocated, it must be given a unique name. Generally, dataset names are
set using the DSNAME format of JCL.
Key Field
The key field is one of the most important fields for logical records. It is used to search for and identify
a logical record. Customer or component numbers are included.
Logical Record
A logical record is a basic unit of information that is stored in a TSAM dataset. The logical record is
composed of bytes of information about individual items that are processed by an application, such
as customers, products, employees, etc.
Glossary 59
Physical Record
Physical records are device-dependent records whose size is determined when a dataset is defined.
All physical records have the same size. Physical records are also called physical blocks or simply
blocks.
Record Identifier
In TSAM, there are three methods used to differentiate records within a record set. These methods
are collectively called record identifiers or record separators. Key field, relative byte address, and
relative record number are included.
VSAM
VSAM is an advanced access method created to improve on the inefficiencies of the non-VSAM
access methods.

D
Index data set allocation
AMS, 20
JCL, 20
data set-tablespace mapping, 54
dbms log, 25
A DCB structure, 21
access method, 1 direct access, 7, 9, 10
access method services (AMS), 20 dynamic access, 23
access mode, 22
adding a volume, 57 E
allocation, 20 ESDS data sets, 7
alternate index, 11 EXTEND mode, 22
AMS, 3
F
B File Management API
base cluster, 11 tsam_alter(), 33
baseinit, 14, 56 tsam_create(), 29
browsing, 24 tsam_filename(), 35
Browsing API tsam_remove(), 31
tsam_delete(), 45 tsam_stat(), 34
tsam_end_br(), 47 tsam_truncate(), 31
tsam_read_next(), 48 File Open/Close API
tsam_read_prev(), 50 tsam_close(), 37
tsam_reset_br(), 46 tsam_open(), 36
browsing interfaces
READ_NEXT, 24 I
READ_PREV, 24
ICF, 3
RESET_BR, 24
IDCAMS, 3
START_BR, 24
IDCAMS (JSCVSUT/KQCAMS) commands
ALTER, 17, 18
C BLDINDEX, 17
catalog information, 3 DEFINE ALIAS, 17
close, 21 DEFINE ALTERNATEINDEX, 17
Connection API DEFINE CLUSTER, 17
tsam_connect(), 26 DEFINE GENERATIONDATAGROUP, 17
tsam_disconnect(), 28 DEFINE NONVSAM, 17
WRITE, 26, 28 DEFINE PATH, 18
creating a system table, 56 DEFINE USERCATALOG, 18
creating a tablespace for catalog, 56 DELETE, 18
IMPORT, 18
LISTCAT, 18
Index 61
PRINT, 18 RRDS data sets, 10
REPRO, 19
VERIFY, 19 S
initialization, 56 secondary key, 11
Initialization tool sequential access, 7, 8, 10, 22, 23
batchinit, 14 skip-sequential access, 9, 10
voladd, 15
INPUT / OUTPUT mode, 22 T
INPUT mode, 21
transaction, 24
Transaction API
J tsam_commit(), 28
job control language (JCL), 20 tsam_rollback(), 29
transaction interfaces
K COMMIT, 24
KSDS data set access methods, 8 ROLLBACK, 24
direct access, 9 TSAM environment variables, 51
sequential access, 8 TSAM_FILENAME_MAPPING, 52
skip-sequential access, 9 TSAM_PREFETCH_NEVER, 51
KSDS data sets, 8 TSAM_READ_PREFETCH_FORCE, 51
TSAM_TOKEN_HASH_SIZE, 52
N TSAM PREFETCH, 52
non-VSAM data set access methods, 1 TSAM-related modules
AMS, 3
O ICF, 3
IDCAMS(JSCVSUT/KQCAMS), 3
open, 21
tsam_alter(), 25, 33
OPEN mode, 21
tsam_alter_t struct, 33
OUTPUT mode, 21
tsam_close(), 25, 37
tsam_commit(), 25, 28
R
tsam_connect(), 25, 26
random access, 22, 23
tsam_create(), 25, 29
record access, 23
tsam_delete(), 26, 44
Record Access API
tsam_disconnect(), 25, 28
tsam_close(), 37
tsam_end_br(), 26, 47
tsam_delete(), 44
tsam_file_t struct, 32
tsam_read(), 39
tsam_filename(), 25, 35
tsam_rewrite(), 42
TSAM_FILENAME_MAPPING, 52
tsam_unlock(), 41
tsam_open(), 25, 36
tsam_write(), 41
TSAM_PREFETCH_NEVER, 51
RRDS data set access methods
tsam_read(), 26, 39
direct access, 10
tsam_read_next(), 26, 48
sequential access, 10
TSAM_READ_PREFETCH_FORCE, 51
skip-sequential access, 10

tsam_read_prev(), 26, 50
tsam_remove(), 25, 31
tsam_report_t struct, 36
tsam_reset_br(), 26, 46
tsam_rewrite(), 26, 42
tsam_rollback(), 25, 29
tsam_start(), 26, 37
tsam_start_br(), 26, 45
tsam_stat(), 25, 34
tsam_stat_t struct, 34
TSAM_TOKEN_HASH_SIZE, 52
tsam_truncate(), 25, 31
tsam_unlock(), 26, 41
tsam_write(), 26, 41
U
user data sets, 3
V
voladd, 15, 56
VRDS data sets, 10
VSAM data set access methods, 1
Index 63

OpenFrame Base 7 Fix#3 TSAM Guide v2.1.4 en

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

OpenFrame Base 7 Fix#3 TSAM Guide v2.1.4 en

Enviado por

Direitos autorais:

Formatos disponíveis

OpenFrame

Copyright © 2018 TmaxSoft Co., Ltd. All Rights Reserved.

Copyright © 2018 TmaxSoft Co., Ltd. All Rights Reserved.

Restricted Rights Legend

Open Source Software Notice

Document Name: OpenFrame TSAM Guide

Document Created: 2018-10-19

Software Version: OpenFrame/Base 7 Fix#3

Document Version: v2.1.4

Chapter 1. TSAM Introduction ..................................................................................... 1

Chapter 2. Data Sets ................................................................................................... 5

Chapter 3. API ........................................................................................................... 25

Chapter 4. Administering TSAM ................................................................................ 51

iv OpenFrame TSAM Guide

About This Document vii

Descriptions of each is as follows:

● Chapter 1: TSAM Introduction

● Chapter 2: Data Sets

Describes how to configure, manage, and process TSAM data sets.

● Chapter 4: Administering TSAM

Describes how to set up, manage, and initialize TSAM.

viii OpenFrame TSAM Guide

<AaBbCc123> Program source code file name

[Button] Name of a GUI button or menu

Italics Reference to another guide

'Input' User input on the screen

Hyperlink Email account, website, or a reference to other chapters or sections

> Proceeding order of menu

+---- Files or directories exist in this directory

|---- Files or directories do not exist in this directory

[Figure 1.1] Figure caption

AaBbCc123 Commands, screen output after executing command, or sample code

About This Document ix

Platform Solaris 11 (SunOS 5.11) or later (32-bit, 64-bit)

Linux x86 2.6 or later (32-bit, 64-bit)

Linux ia64 2.6 or later (32-bit, 64-bit)

Hardware More than 5 GB hard disk space

More than 8 GB RAM

Database Tibero 6 FixSet05

Oracle 11g or 12c

Compiler MF-COBOL or OpenFrame COBOL compiler

OpenFrame PL/I compiler

Contact TmaxSoft Technical Support about IBM or HP-UX platform support.

x OpenFrame TSAM Guide

OpenFrame Outlines basic concepts of OpenFrame and describes all the

OpenFrame Outlines how to install and set up OpenFrame/Base.

Base Installation Guide

OpenFrame Describes overall features of OpenFrame/Base.

OpenFrame Describes OpenFrame utilities.

Utility Reference Guide

OpenFrame Describes OpenFrame tools.

Tool Reference Guide

OpenFrame Describes information and steps needed to migrate resources from

OpenFrame Describes potential errors and troubleshooting methods.

About This Document xi

IBM Mainframe z/OS DFSMS: Using Data Sets

z/OS DFSMS: Managing Catalogs

z/OS DFSMS: Access Method Services for Catalogs

Hitachi Mainframe VOS3 Data Management Description

VOS3 Data Formats

VOS3 VSAM Description

Fujitsu Mainframe OS IV / MSP Data Management Description

OS IV / MSP Data Set Utility User Guide