Escolar Documentos
Profissional Documentos
Cultura Documentos
TSAM Guide
OpenFrame/Base 7 Fix#3
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.
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
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
Glossary ...................................................................................................................... 59
Index ........................................................................................................................... 61
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.
Outlines mainframe data sets and access methods and describes TSAM functions, and
implementation, and related modules.
● Chapter 3: API
Describes TSAM API client libraries that can be used in application programs.
<Ctrl>+C Hold down the Ctrl key and press the C key
Bold Emphasis
" " (Double quotation Reference to a chapter or section in this or another guide
marks)
Reference or caution
Note
{} Required items
[] Optional items
| Selective items
MS SQL 2014
Note
Base Guide
OpenFrame Outlines OpenFrame data sets and describes data set types and
cataloging methods.
Data Set Guide
Error Message
Reference Guide
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
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
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
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
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).
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.
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.
These functions are used to prepare control information for an application using TSAM data
sets (CONN and OPEN/CLOSE).
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).
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
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 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.
Module Description
Note
IDCAMS is equivalent to Hitachi VOS3 VSAM's JSCVSUT utility and XSP/MSP VSAM's
KQCAMS utility.
This chapter describes how to configure, manage, and process TSAM data sets.
Structure Description
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.
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
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
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.
● 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.
● 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:
● Sequential Access
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.
● 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.
The following shows a recommended way to set the data block size. Other methods may cause
unusable space or fragmentation in an RRDS.
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:
● Sequential Access
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.
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).
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.
To access a TSAM-managed data set through an application or utility program, you must
create a data set.
To use system resources efficiently, you need to delete unused data sets.
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.
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.
Utility/Program Description
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:
● Input parameters
Parameter Description
● [options]
Parameter Description
This option is required in Tibero and Oracle, and not used in MS SQL.
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.
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:
Parameter Description
Examples
The following creates management space for a volume named 100000.
The following creates and deletes management space for a volume named 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
Command Function
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).
DEFINE CLUSTER Defines a VSAM data set by specifying required and optional
attributes.
DEFINE NONVSAM Defines catalog items for non-VSAM data set (physical sequence
data sets).
DEFINE PATH Defines a direct access path or an alternate index path to the
base cluster.
EXPORT Exports a catalog and VSAM data set as a portable data set, or
creates a backup copy.
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.
The data in the allocated data set can be accessed using the interface provided by each
access method.
3. Use access method to read or write data to/from the data set.
Note
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.
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.
● 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:
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 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.
● Sequential Access
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 mode can use both sequential access and random access to the data set
during application runtime. All ESDS, RRDS, and KSDS support dynamic access.
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.
– 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.
KSDS KEY
RRDS RRN
ESDS RBA
Although an ESDS can be randomly accessed by using the RBA value, this is not usually
appropriate for most business applications.
The REWRITE interface is used to update a record. However, the primary key of a KSDS
record cannot be updated.
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
READ_NEXT Reads records sequentially from the location specified by the START_BR
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.
Interface Description
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
● Transaction
API Description
● File Management
API Description
● File Open/Close
API Description
Chapter 3. API 25
● Record Access
API Description
● Browsing
API Description
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
Parameter Description
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.
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
password Password.
● 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
● Parameters
Parameter Description
● Return Value
3.3. Transaction
3.3.1. tsam_commit()
Commits the current transaction.
● Prototype
● Parameters
Parameter Description
● Return Value
● Prototype
● Parameters
Parameter Description
● Return Value
When the transaction is rolled back successfully, 0 is returned. If an error occurs, a negative
value is returned.
3.4.1. tsam_create()
Creates a new data set. This can be performed after successfully connecting to the TSAM
server.
● Prototype
● Parameters
Parameter Description
Chapter 3. API 29
Parameter Description
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.
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.
● Prototype
● Parameters
Parameter Description
filename (in) Filename. Use the tsam_filename() command to change the data
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
● Parameters
Parameter Description
Chapter 3. API 31
Parameter Description
filename (in) Filename. Use the tsam_filename() command to change the data
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().
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.
typedef struct {
/* comminication handle */
...
/* association information */
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 */
/* VSAM attributes */
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;
Flag Description
● 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
● Parameters
Parameter Description
filename (in) Filename. Use the tsam_filename() command to change the data
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().
alter (in) New attribute values. For more information, refer to the description
of tsam_alter_t struct.
typedef struct {
/* association information */
...
/* VSAM attributes */
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
● Parameters
Parameter Description
filename (in) Filename. Use the tsam_filename() command to change the data
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().
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 */
● Return Value
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
● Parameters
Parameter Description
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
negative value is returned.
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
● Parameters
Parameter Description
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.
typedef struct {
/* statistics information */
int32_t rec_deleted; /* number of deleted records */
● 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
● Parameters
Parameter Description
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.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
Parameter Description
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.
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.
When the record pointer has been moved successfully, 0 is returned. If an error occurs, a
negative value is returned.
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
Parameter Description
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.
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 directly read a record at the specified
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.
Chapter 3. API 39
Parameter Description
● 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.
● Prototype
● Parameters
Parameter Description
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.
aix_fd (in) AIX file ID. The tsam_file_t struct array index used in tsam_open.
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
Parameter Description
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.
aix_fd (in) AIX file ID. The tsam_file_t struct array index used in tsam_open.
Chapter 3. API 41
Parameter Description
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.
● 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,
Parameter Description
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.
aix_fd (in) AIX file ID. The tsam_file_t struct array index used in tsam_open.
ridfld (in) Record ID field that is used to update 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.
● 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
Parameter Description
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.
aix_fd (in) AIX file ID. The tsam_file_t struct array index used in tsam_open.
ridfld (in) Record ID field that is used to delete a record at the specified
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.
● 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
Parameter Description
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.
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 internal pointer to the
specified 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.
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.
int tsam_reset_br(int fd, int aix_fd, int reqid, void *ridfld, int keylen,
int flags);
● Parameters
Parameter Description
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 internal pointer to the
specified 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.
flags (in) Option flags. For the description of each flag, refer to
"3.6.1. tsam_start()".
● Return Value
3.7.3. tsam_end_br()
Closes the data set browser pointer. This command can be used after a browser is successfully
started.
● Prototype
Chapter 3. API 47
● Parameters
Parameter Description
aix_fd (in) AIX file ID. The tsam_file_t struct array index used in tsam_open.
● 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,
● Parameters
Parameter Description
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 read a record at the specified 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.
● Return Value
When the read operation is successful, 0 is returned. If an error occurs, a negative value is
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,
● Parameters
Parameter Description
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 read a record at the specified 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.
flags (in) Option flags. For the description of each flag, refer to
"3.7.4. tsam_read_next()".
● Return Value
When the read operation is successful, 0 is returned. If an error occurs, a negative value is
returned.
This chapter describes how to set up, manage, and initialize TSAM.
The following are the environment variables required to install and operate TSAM.
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)
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.
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:
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:
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.
[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.
The following are the steps for using the data set-tablespace mapping.
Set TSAM_FILENAME_MAPPING for the current TSAM client to YES. If not specified, the
default value is NO.
export TSAM_FILENAME_MAPPING=YES
$ tbsql sys/tibero<<EOF
create tablespace "X" datafile 'X.dbf' autoextend on;
create tablespace "Y" datafile 'Y.dbf' autoextend on;
EOF
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.
For example, prior to creating a catalog in the volume VOLSER=100000, a tablespace that
corresponds to VOLSER=100000 must be created as follows:
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.
Note
For more information about OpenFrame baseinit and voladd tools, refer to OpenFrame Tool
Reference Guide.
The following is an example of adding the volume VOLSER=100001 by using the tablespace
100001.
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.
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
U
user data sets, 3
V
voladd, 15, 56
VRDS data sets, 10
VSAM data set access methods, 1
Index 63