TXSeries For Multiplatforms SFS Server and PPC Gateway Server - Advanced Administration Version 6.2

TXSeries for Multiplatforms
SFS Server and PPC Gateway Server:

Advanced Administration
Version 6.2
SC34-6627-02
SFS Server and PPC Gateway Server:

Advanced Administration
Version 6.2
SC34-6627-02
Note
Before using this information and the product it supports, be sure to read the general information under Notices on page
247.
Third Edition (January 2008)

Order publications through your IBM representative or through the IBM branch office serving your locality.
Copyright International Business Machines Corporation 1999, 2008. All rights reserved.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
About this book . . . . .
Who should read this book .
Document organization . . .
Conventions used in this book
How to send your comments .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 1. Introduction to the Server interfaces

Using the command-line interfaces . . . . . .
Using the tkadmin command-line interface . .
Using server-specific command-line interfaces .
Command syntax and use . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 2. Creating volumes . . . .

Data storage in CICS SFS . . . . . .
Physical and logical volumes . . . .
Creating physical devices for volumes .
Using file devices as disks . . . .
Expanding volumes . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xiii
xiii
xiii
xiv
xv
.
.
.
.
.
1
1
1
3
3
. 7
. 7
. 7
. 9
. . . . . . . . . . . . . . . 10
. . . . . . . . . . . . . . . 11
Chapter 3. Maintaining volumes . . . . . .

Using administrative mode . . . . . . . .
When to use administrative mode . . . . .
Restarting a server in administrative mode . .
Renaming and relocating volumes . . . . . .
Renaming logical volumes . . . . . . . .
Renaming physical volumes . . . . . . .
Renaming volumes (AIX logical volumes) . .
Relocating physical volumes . . . . . . .
Reclaiming storage space . . . . . . . . .
Reclaiming storage space (AIX logical volumes).
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
13
13
13
14
14
15
15
16
17
18
Chapter 4. Managing server transactions

Viewing server transaction information . .
Administering transactions . . . . . . .
Intervening in unresolved transactions .
Intervening in problematic transactions .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
21
21
21
21
22
Chapter 5. Performing backups . . . .

Overview . . . . . . . . . . . . .
Media archiving. . . . . . . . . . .
Enabling media archiving . . . . . .
Flushing the media archive . . . . .
Backing up server data volumes . . . .
Using the tkadmin backup lvol command
Creating a complete backup . . . . .
Backing up server restart data . . . . .
Moving backups offline . . . . . . . .
Managing backup files . . . . . . . .
Querying a backup of a data volume . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
23
23
24
24
25
25
26
27
28
28
29
29
Copyright IBM Corp. 1999, 2008
iii
Querying a log volume . . . . . . . . . . . . . . . . . . . . . 31

Chapter 6. Recovering from failures
Abnormal server termination . . . .
Media failure . . . . . . . . . .
Diagnosing a media failure . . .
Viewing restart files . . . . . .
Restoring lost or damaged data . .
Ensuring that media is functional .
Repairing a failed mirror . . . .
Restoring a data volume . . . .
Restoring a log volume . . . . .
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
33
33
33
33
34
35
36
39
40
42
Chapter 7. Using the CICS Toolkit Trace Facility . . .

Introduction to the CICS Toolkit Trace Facility . . . . .
Types of trace output and destinations . . . . . . .
Tools for tracing . . . . . . . . . . . . . . .
How to change tracing . . . . . . . . . . . . . .
Trace specifications . . . . . . . . . . . . . .
Trace destinations . . . . . . . . . . . . . . .
Modifying trace specifications . . . . . . . . . .
Redirecting trace output . . . . . . . . . . . .
Manipulating trace output . . . . . . . . . . . . .
Dumping the ring buffer . . . . . . . . . . . . .
Translating trace binary files into readable text . . . .
Format of trace output . . . . . . . . . . . . .
Customizing trace output . . . . . . . . . . . .
Translating error and status codes . . . . . . . . .
Manipulating trace output with WinTrace (Windows only)
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
45
45
45
46
46
46
49
51
51
51
52
54
54
56
56
56
Chapter 8. Managing SFS files . . . . . . . .

Creating SFS files . . . . . . . . . . . . . .
General information . . . . . . . . . . . .
Creating entry-sequenced files . . . . . . . .
Creating relative files. . . . . . . . . . . .
Creating clustered files . . . . . . . . . . .
Using the CICSSDT command to create SFS files .
Copying and renaming files . . . . . . . . . .
Copying a file . . . . . . . . . . . . . .
Renaming a file. . . . . . . . . . . . . .
Expanding and reorganizing files . . . . . . . .
Expanding a file . . . . . . . . . . . . .
Reorganizing an entry-sequenced file . . . . .
Displaying file and transaction information . . . . .
Listing files . . . . . . . . . . . . . . .
Querying a file . . . . . . . . . . . . . .
Listing open file descriptors . . . . . . . . .
Querying an open file descriptor . . . . . . .
Displaying transaction information . . . . . . .
Displaying file locks . . . . . . . . . . . .
Forcing files to close . . . . . . . . . . . . .
Closing a file OFD . . . . . . . . . . . .
Emptying and deleting files . . . . . . . . . .
Emptying a file . . . . . . . . . . . . . .
Deleting a file . . . . . . . . . . . . . .
Importing and exporting files . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
59
59
61
63
64
65
65
66
66
67
67
68
68
68
68
69
70
72
73
74
76
76
76
76
77
77
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
|
|
|
|
|
|
|
Importing SFS files . . . . . . . .

Exporting SFS files . . . . . . . .
Segmenting a file during export . . . .
Using UNIX pipes to transfer SFS files .
Allowing file modification during exports .
Recovering from a failed import or export
Improving import/export performance . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
77
80
85
85
86
86
87
server information .
. . . . . . . .
. . . . . . . .
. . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
89
89
89
90
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
91
91
91
91
92
92
92
92
Chapter 11. Monitoring and maintaining a gateway server. . . . .

Determining conversation status . . . . . . . . . . . . . . .
List conversations . . . . . . . . . . . . . . . . . . . .
Query conversations . . . . . . . . . . . . . . . . . . .
Determining LUW status . . . . . . . . . . . . . . . . . .
List transactions . . . . . . . . . . . . . . . . . . . .
List LUWs . . . . . . . . . . . . . . . . . . . . . .
Query an LUW . . . . . . . . . . . . . . . . . . . .
Determining resynchronization status and canceling resynchronizations
List resynchronizations . . . . . . . . . . . . . . . . .
Query resynchronizations . . . . . . . . . . . . . . . .
Destroy conversations . . . . . . . . . . . . . . . . . .
Cancel resynchronizations . . . . . . . . . . . . . . . .
Determining log exchange status . . . . . . . . . . . . . . .
List log identifier name exchange status . . . . . . . . . . .
Query log identifier name exchange status . . . . . . . . . .
Force log identifier name exchange . . . . . . . . . . . . .
Damage reporting during resynchronization . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 97
. 97
. 97
. 98
. 99
. 99
. 100
. 100
. 102
. 103
. 104
. 105
. 106
. 108
. 109
. 109
. 110
. 110
Chapter 12. The ppcadmin command

ppcadmin cancel resync . . . . . .
ppcadmin destroy conv . . . . . .
ppcadmin force xln . . . . . . . .
ppcadmin list convs . . . . . . . .
ppcadmin list luws . . . . . . . .
ppcadmin list resyncs . . . . . . .
ppcadmin list transactions . . . . .
ppcadmin list xlns . . . . . . . .
ppcadmin query conv . . . . . . .
ppcadmin query luw . . . . . . .
ppcadmin query resync . . . . . .
ppcadmin query xln . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 13. The sfsadmin command
. . . . . . . . . . . . . . . 137
Chapter 9. Obtaining SFS volume

Listing volumes . . . . . . . .
Displaying volume status . . . .
Displaying server information . . .
and
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 10. Improving the performance of the

Tuning an SFS server . . . . . . . . . .
Specifying chunk size for physical volumes .
Specifying buffer pool size . . . . . . . .
Specifying thread pool sizes . . . . . . .
Specifying checkpoint interval . . . . . .
Using Fast Local Transport (Open Systems) . .
Using FLT (SFS servers) . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
SFS
. .
. .
. .
. .
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
server
. . .
. . .
. . .
. . .
. . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
113
113
116
118
119
121
122
124
125
126
131
133
135
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
copy file . . . .
expand file . . .
rename file . . .
reorganize file . .
create clusteredfile
create relativefile .
create sequentialfile
list files . . . . .
destroy file . . .
empty file . . . .
export file . . . .
import file . . . .
query file . . . .
list ofds . . . .
query ofd . . . .
terminate ofd . .
query export . . .
query server . . .
enable server . .
list lvols . . . .
query lvols . . .
acquire lvol . . .
release lvols . . .
add lvol . . . .
query filelock . .
query tranlock . .
add index . . . .
delete index . . .
deactivate index .
rebuild index . . .
query index . . .
rename index . .
expand index . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 14. The tkadmin command

tkadmin abort transaction . . . .
tkadmin add mirror . . . . . . .
tkadmin backup lvol. . . . . . .
tkadmin create lvol . . . . . . .
tkadmin create pvol . . . . . . .
tkadmin delete disk . . . . . . .
tkadmin delete lvol . . . . . . .
tkadmin delete pvol . . . . . . .
tkadmin disable lvol . . . . . . .
tkadmin disable mediaarchiving . .
tkadmin dump ringbuffer . . . . .
tkadmin enable archfile . . . . .
tkadmin enable logfile . . . . . .
tkadmin enable lvol . . . . . . .
tkadmin enable mediaarchiving . .
tkadmin expand lvol . . . . . .
tkadmin expand pvol . . . . . .
tkadmin flush lvol . . . . . . .
tkadmin flush mediaarchive . . . .
tkadmin force transaction. . . . .
tkadmin init disk . . . . . . . .
vi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
138
139
140
140
141
143
145
146
147
148
149
149
149
151
154
156
157
157
158
158
159
160
162
163
164
166
168
170
171
172
173
174
175
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
177
178
179
180
181
182
183
184
185
186
187
187
188
189
190
191
191
192
194
194
195
196
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
|
list disks . . . . .
list lvols . . . . .
list pvols . . . .
list redirect . . . .
list rmi . . . . .
list trace . . . . .
list transactions . .
map lvol . . . . .
move pvol . . . .
query backup . . .
query disk . . . .
query logvol . . .
query lvol . . . .
query mediaarchiving
query pvol . . . .
query redirect . . .
query trace. . . .
query transaction .
recover lvols . . .
recreate lvol . . .
redirect trace . . .
remap lvol . . . .
remove mirror . .
rename lvol . . .
rename pvol . . .
restore logvol . . .
restore lvols . . .
retain backups . .
set ringbuffer size .
show ringbuffer size
sync mirrors . . .
trace specification .
unmap lvol . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
197
198
199
199
200
200
202
204
205
207
210
211
211
212
213
214
214
215
216
217
218
220
221
222
223
224
225
227
228
229
229
230
232
Appendix. Environment Variables . . . . . . . . . . . . . . . . . 235

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Trademarks and service marks . . . . . . . . . . . . . . . . . . 248
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Contents
vii
viii
Figures
1.
2.
3.
4.
5.
6.
7.
8.
A disk and its units of allocation . . . . .

Physical and logical volumes . . . . . .
Files used as disks on Windows . . . .
Role of backups in recovery . . . . . .
Multiple complete backups . . . . . .
Anatomy of a trace message . . . . .
Sample records for SFS file types . . .
Record updates for an entry-sequenced file
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . . 8
. . . 9
. . . 11
. . . 24
. . . 26
. . . 55
. . . 60
. . . 63
ix
Tables
|
|
|
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
Road map of CICS SFS Server and PPC Gateway Server: Advanced Administration . . . . . . xiii
Conventions that are used in this book. . . . . . . . . . . . . . . . . . . . . . . xiv
Using the command-line interfaces . . . . . . . . . . . . . . . . . . . . . . . . . 1
Using the tkadmin interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Repairing Logical Volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
CICS Toolkit Trace classes . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Standard trace options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Comparison of SFS file types . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Valid SFS field types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Status code for file import and export . . . . . . . . . . . . . . . . . . . . . . . 82
Determining whether to destroy a conversation . . . . . . . . . . . . . . . . . . . 105
Determining resync responsibility from transaction states . . . . . . . . . . . . . . . 107
PPC Services audit messages concerning resynchronization damage and errors . . . . . . . 110
String values and their expressions . . . . . . . . . . . . . . . . . . . . . . . 240
Trace class and events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Values of the timeout variables . . . . . . . . . . . . . . . . . . . . . . . . . 243
xi
xii
About this book

This guide describes how to administer the SFS Server and PPC Gateway Server
components of TXSeries for Multiplatforms.
Who should read this book

This book is for system administrators who are responsible for administering the
CICS SFS Server and PPC Gateway Server.
Familiarity with administration of your operating system is helpful because many of
the system administration procedures are used with TXSeries for Multiplatforms.
Document organization
Table 1. Road map of CICS SFS Server and PPC Gateway Server: Advanced
Administration
If you want to...
Refer to...
Read about the conventions used in this

book.
Conventions used in this book on page xiv.
Learn about the command line interfaces

used to perform administrative tasks.
Chapter 1, Introduction to the Server

interfaces, on page 1.
Learn about how to perform volume

Chapter 2, Creating volumes, on page 7.
management tasks for the CICS SFS Server.
Learn about how to temporarily disable a
volume to perform tasks that require the
volume to be offline.
Chapter 3, Maintaining volumes, on page

13.
Learn about how to display information about Chapter 4, Managing server transactions,
transactions, and resolve transaction
on page 21.
problems.
Learn about how to back up log volumes,
data volumes, and restart data, and manage
backup files.
Chapter 5, Performing backups, on page

23.
Learn about how to recover from abnormal

server termination and media failure.
Chapter 6, Recovering from failures, on

page 33.
Learn about using the CICS Toolkit Trace

Facility.
Chapter 7, Using the CICS Toolkit Trace

Facility, on page 45
Learn how to create, copy, allocate and

reclaim space for, and display information
about SFS files. Learn about the SFS
import-export facility.
Chapter 8, Managing SFS files, on page

59.
Learn about obtaining SFS volume and

server information.
Chapter 9, Obtaining SFS volume and

server information, on page 89
Learn about improving the performance of

the SFS server.
Chapter 10, Improving the performance of

the SFS server, on page 91
Learn about how to monitor and maintain a

gateway server.
Chapter 11, Monitoring and maintaining a

gateway server, on page 97.
Learn about the ppcadmin command
Chapter 12, The ppcadmin command, on

page 113
xiii
Table 1. Road map of CICS SFS Server and PPC Gateway Server: Advanced
Administration (continued)
If you want to...
Refer to...
Learn about the sfsadmin command
Chapter 13, The sfsadmin command, on

page 137
Learn about the tkadmin command
Chapter 14, The tkadmin command, on

page 177
Learn about the Environment Variables
Environment Variables, on page 235
Conventions used in this book

TXSeries for Multiplatforms documentation uses the following typographical and
keying conventions.
Table 2. Conventions that are used in this book
xiv
Convention
Meaning
Bold
Indicates values that you must use literally, such as commands,

functions, and resource definition attributes and their values. When
referring to graphical user interfaces (GUIs), bold also indicates
menus, menu items, labels, buttons, icons, and folders.
Monospace
Indicates text that you must enter at a command prompt. Monospace

also indicates screen text and code examples.
Italics
Indicates variable values that you must provide (for example, you
supply the name of a file for file_name). Italics also indicates
emphasis and the titles of books.
<>
Encloses the names of keys on the keyboard.
<Ctrl-x>
Where x is the name of a key, indicates a control-character

sequence. For example, <Ctrl-c> means hold down the Ctrl key
while you press the c key.
<Return>
Refers to the key labeled with the word Return, the word Enter, or
the left arrow.
Represents the UNIX command-shell prompt for a command that

does not require root privileges.
Represents the UNIX command-shell prompt for a command that

requires root privileges.
C:\>
Represents the Windows command prompt.
>
When used to describe a menu, shows a series of menu selections.

For example, Select File > New means From the File menu,
select the New command.
Entering commands
When instructed to enter or issue a command, type the command

and then press <Return>. For example, the instruction Enter the ls
command means type ls at a command prompt and then press
<Return>.
[]
Encloses optional items in syntax descriptions.
{}
Encloses lists from which you must choose an item in syntax

descriptions.
Separates items in a list of choices enclosed in { } (braces) in syntax

descriptions.
Table 2. Conventions that are used in this book (continued)

Convention
Meaning
...
Ellipses in syntax descriptions indicate that you can repeat the

preceding item one or more times. Ellipses in examples indicate that
information was omitted from the example for the sake of brevity.
IN
In function descriptions, indicates parameters whose values are used

to pass data to the function. These parameters are not used to
return modified data to the calling routine. (Do not include the IN
declaration in your code.)
OUT
In function descriptions, indicates parameters whose values are used

to return modified data to the calling routine. These parameters are
not used to pass data to the function. (Do not include the OUT
declaration in your code.)
INOUT
In function descriptions, indicates parameters whose values are

passed to the function, modified by the function, and returned to the
calling routine. These parameters serve as both IN and OUT
parameters. (Do not include the INOUT declaration in your code.)
$CICS
Indicates the full path name of the location in which the CICS
product is installed; for example, /usr/lpp/cics on AIX. If the CICS
environment variable is set to the product path name, you can use
the examples exactly as shown in this book; otherwise, you must
replace all instances of $CICS with the CICS product path name.
CICS on Open
Systems
Refers collectively to the CICS product for all supported UNIX

platforms.
TXSeries for
Multiplatforms
Refers collectively to the CICS for AIX, CICS for HP-UX (HP-UX
PA-RISC and HP-UX IPF), CICS for Solaris, and CICS for Windows
products.
CICS
Refers generically to the CICS for AIX, CICS for HP-UX, CICS for
Solaris, and CICS for Windows products. Other CICS products in the
CICS Family are distinguished by their operating system (for
example, IBM mainframe-based CICS for the z/OS platform).
How to send your comments

Your feedback is important in helping to provide the most accurate and highest
quality information. If you have any comments about this book or any other
TXSeries for Multiplatforms documentation, send your comments by e-mail to
idrcf@hursley.ibm.com. Be sure to include the name of the book, the document
number of the book, the version of TXSeries for Multiplatforms, and, if applicable,
the specific location of the information you are commenting on (for example, a page
number or table number).
About this book
xv
xvi

Use the command-line interfaces to perform administrative tasks (such as creating
backups) using server-specific interfaces. For example, the sfsadmin interface
allows you to manage an SFS server. Table 3 lists the command-line interfaces
used for various administrative tasks.
Table 3. Using the command-line interfaces
Administrative Task
Interface Used
Backing up volumes
tkadmin
Moving, restoring, and renaming volumes
tkadmin
Administering an SFS server
sfsadmin
Administering a PPC Gateway server
ppcadmin
The command-line interfaces are described in the following sections.
Using the command-line interfaces

This section briefly describes the command-line interfaces. These interfaces are
used to perform maintenance tasks such as removing, restoring, and renaming
volumes. They are also used to perform server-specific administrative tasks such as
administering a PPC Gateway server.
Using the tkadmin command-line interface

The tkadmin command-line interface can be used for a wide range of volume
management, transaction administration, and application tracing tasks. It can be
used for basic tasks such as creating and mirroring volumes, performing daily
backups, and querying server attributes. It can also be used for less-frequent tasks,
such as renaming volumes and restoring data.
Table 4 shows administrative tasks and their corresponding tkadmin commands.
Note: On non-AIX Open systems, volumes can be stored on disks. On AIX
systems, volumes can be stored in operating system logical volumes or on
disks. On Windows systems, volumes can be stored on physical disks, on
logical disk drives, or in operating system files.
Table 4. Using the tkadmin interface
Administrative Task
tkadmin Commands
Backing up volumes
tkadmin backup lvol
Comments
tkadmin query backup

tkadmin retain backups
tkadmin truncate backup
Creating physical and logical
volumes; adding volumes
tkadmin init disk

tkadmin create pvol
tkadmin create lvol
tkadmin enable lvol
Relocating physical volumes
tkadmin move pvol
The server must be in

administrative mode.
Table 4. Using the tkadmin interface (continued)

Administrative Task
tkadmin Commands
Comments
Renaming physical and

logical volumes
tkadmin rename pvol

administrative mode. If AIX
operating system logical
volumes are in use, rename
them by using the AIX
Logical Volume Manager, and
then use the tkadmin unmap
lvol and tkadmin remap lvol
commands.
tkadmin rename lvol

tkadmin unmap lvol (AIX
logical volumes only)
tkadmin remap lvol (AIX
Expanding volumes
tkadmin expand pvol
tkadmin expand lvol
Reclaiming space
tkadmin remove mirror

tkadmin delete lvol
tkadmin delete pvol
tkadmin delete disk
tkadmin unmap lvol (AIX
Creating and synchronizing

mirrors
tkadmin create pvol

tkadmin add mirror
tkadmin sync mirrors
If AIX operating system

logical volumes are in use,
first expand them by using
the AIX Logical Volume
Manager, and then use the
tkadmin expand lvol
command to expand the
logical volume.
unmap them by using the
tkadmin unmap lvol
command, then delete them
by using the AIX Logical
Volume Manager.
On Windows, Windows
operating system can be
used for mirroring. If AIX
operating system logical
volumes are in use, create
mirrors by using the AIX
Logical Volume Manager.
Repairing mirrors

repair mirrors by using the
AIX Logical Volume Manager.
Restoring data volumes

tkadmin restore lvols

tkadmin enable archfile
tkadmin recover lvols
Restoring log volumes
tkadmin restore logvol


tkadmin enable logfile

Tracing
All tkadmin trace-related

commands
Audit, Error, and Warning

messages are automatically
sent to the output file of the
SFS server (/var/cics_servers
/SSD/cics/sfs/server_name
/msg). Other tracing
operations can be done using
tkadmin commands.
Note: To perform certain administrative tasks such as restoring volumes, the server
must be in administrative modethat is, the volumes that are being worked
on must not be available for I/O. You must first start a server in
administrative mode as described in Using administrative mode on page
13, and then use tkadmin commands to administer the server.
Using server-specific command-line interfaces

The following server-specific command-line interfaces allow you to manipulate
server objects after a server is started:
v sfsadmin Use the sfsadmin interface for administering an SFS server.
v ppcadmin Use the ppcadmin interface for administering PPC Gateway
servers.
Command syntax and use

The following sections describe the syntax of administrative commands, how to
issue the commands interactively, and how to get online help. The examples use
tkadmin commands to illustrate syntax. However, the command syntax is the same
for the sfsadmin, and ppcadmin command suites.
Command syntax
All administrative commands use the same general syntax conventions. The
following shows these conventions:
suite verb object {argument...} -option
argument [-option] {argument | argument}
A description of each element of the command follows:

v suiteThe command suite name specifies the group of related commands to
which the command belongs.
v verb objectTwo words describing the action initiated by the command and the
object of that action. Some commands have verbs only.
v argumentParameters that provide the command with information it uses to
execute.
v optionA word preceded by a - (dash) that either tells the command to execute
in a certain way or tells the command that a certain type of information follows in
the form of an argument.
v { | } (braces containing a vertical bar) indicate that you can enter only one of the
arguments separated by the vertical bars.
v {...} (braces containing an ellipsis) indicate that you can enter one or more
instances of the argument or group of arguments that precede the ellipsis.
v [ ] (square brackets) indicate optional parts of the command.
The following syntax for the command illustrates these elements:
tkadmin backup lvol -server server_name logical_volume_name\
[-fileprefix file_prefix] [-filesize file_size] \
[-nfiles number_of_files]
In the preceding tkadmin example, tkadmin is the suite, backup is the verb, lvol is
the object, -server, -fileprefix, -filesize, and -nfiles are options, and server_name,
logical_volume_name, file_prefix, file_size, and number_of_files are arguments. The
-fileprefix, -filesize, and -nfiles options are optional.
Using the Commands

When entering command names use a space to separate each element on a
command line. Also use spaces to separate any multiple arguments. Do not use a
space to separate an option from its - (dash).
Specifying units of size: Administration of the SFS Server often involves
managing physical storage. The unit of physical storage can be bytes, pages, or
megabytes, depending upon the argument specification for individual commands. To
make specification of very large numbers easier, administrative commands accept a
k or K appended to an integer argument, interpreting the k or K to mean a multiple
of 1024. For example, 2k is interpreted as 2048.
Using commands in interactive mode: CICS provides a shortcut for typing
administrative commands interactively. You can omit the command suite name and
type only the verb, object, and arguments. To enter commands interactively, enter
the command suite name with no argumentsfor example, tkadmin. When you do
so, the prompt becomes the name of the command suite as the following example
shows:
%
tkadmin
Toolkit Administration tool.

Type "help" for help, "exit" to exit.
tkadmin>
Abbreviating commands: You can abbreviate a command name to the shortest

form that still distinguishes it from other command names. You cannot, however,
abbreviate the command suite name. For example, you can shorten the command
to tkadmin e p because no other command in the tkadmin interface has a verb
beginning with the letter e and a object beginning with the letter p.
When two commands are similar, be sure to avoid ambiguous abbreviation.
Specifying the server name: Each administrative command must indicate the
server for which the command is being issued. The server can be specified by
using the -server option or by using a server environment variable. A value
provided on the command line overrides a value defined in an environment variable.
The command examples in this document assume that the server environment
variable has been set to the name of the server. The -server option is omitted on
the command line.
Each server has its own server environment variable. The server environment
variables are as follows:
v The CICS_TK_SERVER environment variable sets the name of the server for
tkadmin commands.
v The CICS_TK_SFS_SERVER environment variable sets the name of the SFS
server for sfsadmin commands.
v The CICS_PPC_GWY_SERVER environment variable sets the name of the PPC
Gateway server for ppcadmin commands.
For administrators who frequently configure one server, setting the server
environment variables can conveniently reduce the amount of information that must
be specified on the command line. The following steps describe the commands that
are used to set environment variables on different operating systems.
On Open Systems. To set a server environment variable in a Korn shell, use the
export command. The following example sets the CICS_TK_SERVER variable to
the server named /.:/cics/sfs/mysfs:
%
export CICS_TK_SERVER /.:/cics/sfs/mysfs
On Windows. To set a server environment variable, use either of the following

methods:
v At the DOS prompt, use the set command to set the variable. The following
example sets the CICS_TK_SERVER variable to the server named
/.:/cics/sfs/mysfs:
C:\ set CICS_TK_SERVER=/.:/cics/sfs/mysfs
Note that the value of the environment variable remains in effect only for
commands issued in that DOS shell.
v From the Start menu, choose the Settings menu and then choose Control
Panel. Double-click the System icon. Type the name of the server environment
variable and its value in the text fields at the bottom of the dialog box. Choose
the Set button to set the variable. The new environment variable becomes
available the next time you log on.
Chapter 2. Creating volumes

This chapter presents basic concepts and procedures for managing data storage in
the CICS SFS Server. It describes how to define and allocate volumes, add and
expand volumes, add and remove mirrors, and perform other volume management
tasks.
Data storage in CICS SFS

An important task in defining a server is allocating physical storagespecifying
where to store application data (data created by users of the system) and where to
store log data (transaction state information and descriptions of changes to data).
Servers use the CICS Toolkit Volume Service to manage their physical storage. The
Volume Service removes the physical boundaries of standard devices (disks) by
providing a volume. A volume is an abstract representation of storage space that
can contain storage areas from one or more disks. For instance, the xyz volume
can have storage space allocated from both disk1 and disk2. Thus, SFS servers
can use arbitrarily large volumes to store application and log data.
Volumes can be used as log volumes (to store a servers log files) or as data
volumes (to store a servers application data). Each SFS server requires one
volume on which to store its log file and one or more volumes on which to store its
application data. Whether they are used as log or data volumes, CICS Toolkit
volumes are managed in the same way.
CICS Toolkit volumes can use the following physical devices:
v On HP-UX and Solaris. Volumes can be stored on disks (disk partitions).
v On AIX. Volumes can be stored on raw disk partitions or on AIX logical volumes.
v On Windows. Volumes can be stored on a physical disk, a logical disk drive
(partition), or one or more fully allocated operating system files. These files can
reside on a single disk (logical drive) or span multiple disks.
Physical and logical volumes

The Volume Service uses two types of volumes: physical volumes and logical
volumes. A physical volume is a collection of disk partitions used to store all server
data. Physical volumes have a maximum size of 16 TB. Because a physical volume
can contain any portion of one or more disks, you must specify several
characteristics of a physical volume when creating it. Disk space is divided into
regions, regions are divided into chunks, and chunks are divided into pages. The
common unit of measurement is a page. Figure 1 on page 8 illustrates the concepts
of disk divisions, including a disk, region, chunk, and page.
Figure 1. A disk and its units of allocation
A disk is defined as byte-addressable random access secondary storage. A disk is

identified by a disk name, which is a system-specific printable character string. In
most versions of Open Systems, a disk is actually a disk partition; in this case, you
specify the name of the disk partitionfor example, /dev/rsd2c. On Windows, you
can specify an entire physical disk, a logical disk drive (partition), or a fully allocated
operating system file for the disk name.
Note: If you are using a physical disk, you must ensure that it does not contain any
configured partitions. CICS cannot access a physical disk containing existing
partitions.
A region is a collection of pages with contiguous addresses on a single disk. The
size of a disk region should be a multiple of the chunk size. A region size that is not
a multiple of the chunk size is rounded down to the nearest exact multiple; the
rounding process results in wasted storage space. For example, if the chunk size is
32 pages, a region size specified as 72 pages is rounded down to 64 pages. A
region cannot be smaller than a chunk.
A chunk is a unit of space allocation that can be used by SFS Server applications.
Chunk size is the number of contiguous pages on a disk (provided that the disk
supports that number of contiguous pages). Chunk size is important for applications
that require their data to be contiguously written to disk to achieve the highest
possible I/O performance. It impacts how efficiently disk space is used and the
amount of system overhead incurred when allocating space.
A chunk is larger than a page but smaller than a region. Chunk size is specified as
a number of pages; the number must be a power of 2. The recommended chunk
size is 64 pages. When you create a physical volume for storing SFS application
data, cicscp automatically allocates a chunk size of 64. All physical volumes
backing a logical volume must use the same chunk size. In most cases, it is best to
accept the default chunk size. See Chapter 10, Improving the performance of the
SFS server, on page 91 for more information on chunk size.
A page is the smallest addressable unit of space administered by the Volume

Service. Page size is a fixed CICS-configured parameter defined to be 4096 bytes;
it is not a device specification.
Physical volumes are managed by logical volumes. A logical volume presents a
user with a contiguous address space; that is, a logical volume simulates one large
contiguous storage space by using regions of different disks. One logical volume
can manage one physical volume and its mirrors (identical copies of the same
data). A logical volume manages physical volumes by controlling all I/O and by
mounting and dismounting the volumes. Note that a logical volume cannot be larger
than the total of all physical disks that back the logical volume. Figure 2 shows a
logical volume that is composed of two physical volumes, each of which is a
collection of regions of disks.
Figure 2. Physical and logical volumes
Creating physical devices for volumes

Before you can allocate a volume for CICS storage, you must create a physical
device to be used as the volume. The type of physical device required depends on
your platform. CICS supports the following storage devices:
v On HP-UX and Solaris. CICS supports raw disk partitions and file devices. Use
an operating system utility to create one or more disk partitions. Use an
operating system utility such as dd to create file devices. Because disk I/O is
faster than file I/O, it is strongly recommended that raw disk partitions be used in
production environments and performance benchmarking.
Note: To prevent buffering, use character devices instead of block devices. For
easy replacement of a failed disk you can use symbolic links to the disk
partitions.
v On AIX systems. CICS supports AIX logical volumes, raw disk partitions, and
UNIX file devices. Note that you must use an AIX utility to create an AIX logical
volume. In addition, you must use the AIX Logical Volume Manager (LVM) to
manage AIX logical volumes. Use the CICS LVM to manage volumes stored on
raw disk partitions and UNIX file devices on AIX.
v On Windows systems. CICS supports physical disks, logical disk drives
(partitions), or one or more fully allocated operating system files. Use the Disk
Administrator to create partitions. Because disk I/O is faster than file I/O, it is
strongly recommended that raw disk partitions be used in production
environments and performance benchmarking.
Note: If you are using a physical disk, make sure that it does not contain any
configured partitions.
Using file devices as disks

You can use file devices as disks. File devices are created by using operating
system utilities such as UNIX dd. File devices can be useful for development
environments in which quick prototyping of systems does not require large
production-size disks. However, it is strongly recommended that file devices not be
used in production systems or for performance benchmark testing for the following
reasons:
v File I/O can be buffered. CICS log data must be reliably written (not buffered).
v Performance is poor.
On Open systems. To create file devices, you can use the Unix dd command. For
example, the following command creates an 8-MB file device on Open Systems:
% echo x | dd seek=16k of=/var/cics_servers/vols/sfsDataVol
On Windows systems. If you are using files as volumes, you must create one or
more fully allocated operating system files. You can use the CICS fileVol program
(or your own program) to create the files. The fileVol program creates a fully
allocated operating system file. The command syntax is
fileVol file_name file_size
Specify the name of the file to create as the file_name argument and the size of the
file (in bytes or kilobytes) as the file_size argument. Specify bytes as an integer and
kilobytes as an integer followed by the letter k. For example, the following
command creates a fully allocated 4000- kilobyte operating system file named
D:\var\cics_servers\vols\sfsDataVol: :
C:\> fileVol D:\var\cics_servers\vols\sfsDataVol 4000k
The operating system files can be located on a disk partition (logical drive) or on a
volume or stripe set that spans multiple disks. A file can be made to encompass an
entire disk or disk partition. The use of network or floppy disk files for storing CICS
Toolkit logical volumes is strongly discouraged. Do not store the files in a
compressed file system or on RAM disks. A Windows File System partition is the
best choice.
The shaded portions in Figure 3 on page 11 represent files. As shown, a volume
can be a single file or multiple files on the same logical drive (a logical drive can be
a Windows volume set). An operating system file can also encompass an entire
physical disk or disk partition (logical drive).
10
Figure 3. Files used as disks on Windows
The full path name of the operating system file (including the drive letter) should be
specified as the disk name for any disk_name arguments in CICS commandsfor
example, D:\serverdata. Files used as volumes have the same units of space
allocationregions, chunks, and pagesas disks have.
Expanding volumes
Use the tkadmin expand lvol on page 191 and tkadmin expand pvol on
page 192 commands to expand volumes.
11
12
Chapter 3. Maintaining volumes

This chapter describes how to use administrative mode, how to rename and
relocate volumes, and how to reclaim space from volumes no longer needed by a
server.
Using administrative mode

This section describes when to use administrative mode and how to restart a server
in administrative mode.
When to use administrative mode

Some administrative tasks require a servers volumes to be temporarily disabled.
Restarting a CICS server in administrative mode temporarily disables its volumes.
When restarted in administrative mode, a server:
v Exports only its administration remote procedure call (RPC) interface; it does not
export any of its other RPC interfaces. For example, a Structured File Server
(SFS) server restarted in administrative mode does not export the SFS client
interface but exports only the interface needed by the tkadmin program.
v Does not perform recovery on its volumes (as it would if started in normal
operations mode with enabled volumes).
The following tasks can be done only when a server is in administrative mode:
v Recovering from media failure (log or data volumes have been damaged and you
need to restore the volumes). Note that administrative mode is not necessary to
recover from damage to mirrors.
v Renaming logical and physical volumes (the tkadmin rename lvol and tkadmin
rename pvol commands).
v Relocating physical volumes (the tkadmin move pvol command).
v Reclaiming storage space occupied by a logical volume (the tkadmin delete lvol,
tkadmin delete pvol, and tkadmin delete disk commands).
v Performing any other operation that requires a volume to be offline.
The commands for renaming and relocating volumes are covered in Renaming and
relocating volumes on page 14. The procedure for reclaiming storage space is
covered in Reclaiming storage space on page 17 and Reclaiming storage space
(AIX logical volumes) on page 18. The procedure for restoring data and log
volumes is covered in Chapter 6, Recovering from failures, on page 33.
To perform administrative-mode tasks, you must first restart a server in
administrative mode and then use the appropriate tkadmin commands to administer
the server. The following section describes how to enter administrative mode by
using the command line.
Restarting a server in administrative mode

Start a server in administrative mode by using the -nlv option of the cicssfs
command.
1. Determine the original options specified when the server was cold started.
2. Issue the cicssfs command. Use the original options and add the -nlv option.
This indicates that the SFS server is to be started with no log volumes open.
13
3. Perform the required volume maintenance or recovery tasks by using tkadmin

commands.
4. Stop the server and restart it by using cicscp command.
Table 5 provides a summary of the steps necessary for repairing volumes and
returning the server to normal operation. This summary applies to the use of
server-specific startup commands. See Chapter 6, Recovering from failures, on
page 33 for details on recovering volumes.
Table 5. Repairing Logical Volumes
Action
Restoring or Relocating
Data Volumes
Restoring or Relocating
Log Volumes
Restart a Server in
Administrative Mode
Use cicssfs/cicsppcgwy
command
Use cicssfs/cicsppcgwy
command
Restore (or relocate) volumes tkadmin restore lvols and/or

as necessary
tkadmin move pvol
tkadmin restore logvol or

tkadmin move pvol or both
Enable the log file (if log

volumes are being restored)
(Not applicable)
Restore the data volume (if

log volumes are being
restored)
(Not applicable)
Recover the volumes
Restart the server
Use cicscp command
Use cicscp command
Renaming and relocating volumes

This section contains procedures for renaming and relocating volumes for
organizational purposes.
The following procedures describe how to use the tkadmin command to rename
volumes after they have been configured.
Renaming logical volumes

Perform the following steps to rename a logical volume:
Note: If AIX operating system logical volumes are used, see Renaming volumes
(AIX logical volumes) on page 15 for instructions.
1. Restart the server in administrative mode. See Using administrative mode on
page 13 for instructions.
2. At an operating system prompt, use the tkadmin rename lvol command to
rename the volume. The command syntax is
tkadmin rename lvol -server server_name old_name new_name
You must specify the old name of the logical volume for the old_name argument
and the new name of the logical volume for the new_name argument. For
example, enter the following command to rename a logical volume named
sfsvol3 to cicsvol1:
%
tkadmin rename lvol sfsvol3 cicsvol1
3. Restart the server in normal operations mode.
14
Renaming physical volumes

Perform the following steps to rename a physical volume:
2. Use the tkadmin rename pvol command to rename the volume. The command
syntax is
tkadmin rename pvol -server server_name old_name new_name
You must specify the old name of the physical volume for the old_name
argument and the new name of the physical volume for the new_name
argument. For example, enter the following command to rename a physical
volume named sfspvol1 to cicspvol1:
%
tkadmin rename pvol sfspvol1 cicspvol1
Renaming volumes (AIX logical volumes)

The link between a CICS Toolkit logical volume and an AIX logical volume is the
name of the supplied AIX logical volume. Changing the name of an AIX logical
volume that backs a CICS Toolkit logical volume disrupts the physical storage of the
server using that logical volume. If it is necessary to rename an AIX logical volume,
the CICS Toolkit logical volume must be unmapped and then remapped to the
renamed AIX logical volume. If possible, avoid renaming AIX logical volumes
mapped to CICS Toolkit volumes.
Perform the following steps to remap a CICS Toolkit logical volume to a renamed
AIX logical volume:
2. Use an AIX utility to rename the AIX logical volume.
3. Use the tkadmin unmap lvol command to unmap the CICS Toolkit logical
volume. The command syntax is
tkadmin unmap lvol -server server_name logical_volume_name
You must specify the name of the CICS Toolkit logical volume for the
logical_volume_name argument. For example, enter the following command to
unmap a logical volume named sfsvol3:
%
tkadmin unmap lvol sfsvol3
4. Use the tkadmin remap lvol command to remap the CICS Toolkit logical volume.
The command syntax is
tkadmin remap lvol -server server_name logical_volume_name
operating_system_logical_volume_name chunk_size
logical_volume_name argument, the new name of the AIX logical volume for the
operating_system_logical_volume_name argument, and the chunk size of the
CICS Toolkit logical volume for the chunk_size argument. For example, enter
the following command to remap a logical volume named sfsvol3 to the
renamed AIX volume aixvol3:
%
tkadmin remap lvol sfsvol3 aixvol3 64
Note: Use the command to determine the chunk size of a physical volume.
15
Relocating physical volumes

To manage disk usage, you can relocate a servers logical volume to a different
collection of disks. A logical volume is relocated by moving its underlying physical
volumes. To find the names of underlying physical volumes, review the output of the
tkadmin query pvol command.
Note: If you need to relocate physical volumes after a media failure, refer to the
restore procedures in Chapter 6, Recovering from failures, on page 33.
Perform the following steps to relocate a physical volume:
2. If necessary, create a new physical disk (the destination disk). On Open
Systems, use an operating system utility to create a disk or disk partition. On
Windows, use the Disk Administrator to create a new disk or the CICS fileVol
program to create a new fully allocated operating system file.
Note: The disk space created for the destination disk must be at least as large
as the disk space of the original (source) disk.
3. Use the tkadmin init disk command to initialize the disk. The syntax is
tkadmin init disk -server server_name disk_name
You must specify the name of the disk to be initialized for the disk_name
argument.
On Open Systems. For example, enter the following command to initialize the
disk /dev/rsd1f:
%
tkadmin init disk /dev/rsd1f
On Windows. For example, enter the following command to initialize the disk
D:\serverdata:
C:\> tkadmin init disk D:\serverdata
4. Use the tkadmin move pvol command to move the physical volume. The syntax
is
tkadmin move pvol -server server_name physical_volume_name
number_of_regions {{source_disk_name source_disk_offset
region_size destination_disk_name destination_disk_offset}...}
You must specify the name of the physical volume for the
physical_volume_name argument and the number of regions for the
number_of_regions argument. For each region, you must specify the source
disk name for the source_disk_name argument, the source disk offset for the
source_disk_offset argument, the size of the region for the region_size
argument, the destination disk name for the destination_disk_name argument,
and the destination disk offset for the destination_disk_offset argument. Disk
offsets and the region size are measured in units of pages (4096 bytes).
On Open Systems. For example, enter the following command to move one
region of a physical volume named sfspvol2 from a disk named /dev/rsd1f
(with an offset of 0 and a region size of 1984 pages) to a disk named
/dev/rsd2g with an offset of 0:
%
tkadmin move pvol sfspvol2 1 /dev/rsd1f 0 1984 /dev/rsd2g 0
On Windows. For example, enter the following command to move a physical

volume named sfspvol2 from a disk named D:\serverdata (with an offset of 0
and a region size of 2880 pages) to a disk named F:\serverdata with an offset
of 0:
16
C:\> tkadmin move pvol sfspvol2 1 D:\serverdata 0 2880 F:\serverdata 0
Reclaiming storage space

You can reclaim space occupied by a servers logical volumes by deleting the
logical volume and its associated physical volumes and disks. (Be sure that a
logical volume is no longer in use before reclaiming its storage space.) The
underlying physical volumes and disks need not be deleted if they can be used by
the same server to store other data. However, they must be deleted if you plan to
use the space for another server.
You must delete logical volumes, physical volumes, and disks in that order. The
following list summarizes the steps needed to reclaim storage space:
1.
2.
3.
4.
5.
6.
Remove all mirrors of the volume.

Restart the server in administrative mode.
Delete the logical volume.
Delete the physical volume or volumes.
Delete the disk or disks (if no other physical volume is stored on the disk).
(Windows Only) Delete the operating system files used as disks.
Note: If AIX operating system logical volumes are used, see Reclaiming storage
space (AIX logical volumes) on page 18 for instructions.
The examples in this procedure reclaim the space occupied by the logical volume
sfslvol1. Assume that the logical volume sfslvol1 is backed by two physical
volumesthe original physical volume, sfspvol1, and a mirror, sfspvol1.mirr. Each
physical volume resides on its own Open Systems disk partitionfor example,
sfspvol1 on /dev/rsd0f and sfspvol1.mirr on /dev/rse0f.
Perform the following steps to reclaim storage space:
1. Remove all mirrors of the backing physical volume using the tkadmin remove
mirror command. The syntax of the tkadmin remove mirror command is
tkadmin remove mirror -server server_name logical_volume_name
physical_volume_name
You must specify the name of the logical volume for the logical_volume_name
argument and the name of the physical volume for the physical_volume_name
argument. (You can determine which physical volume and mirrors back a logical
volume by using the tkadmin query lvol command.)
For example, enter the following command to remove a mirror named
sfspvol1.mirr from a logical volume named sfslvol1:
%
tkadmin remove mirror sfslvol1 sfspvol1.mirr

3. Use the tkadmin delete lvol command to delete the logical volume. Deleting the
logical volume removes the mapping of a physical volume to the logical volume
it backs. You must delete a logical volume before you delete its backing physical
volumes. The command syntax is
tkadmin delete lvol -server server_name logical_volume_name
argument. For example, enter the following command to delete a logical volume
named sfslvol1:
17
tkadmin delete lvol sfslvol1
4. Use the tkadmin delete pvol command to delete the physical volume. You must
delete a physical volume before you delete (uninitialize) the disks that back it.
The command syntax is
tkadmin delete pvol -server server_name physical_volume_name
You must specify the name of the physical volume to be deleted as the
physical_volume_name argument. Be sure to delete all physical volumes,
including physical volumes that back mirrors. For example, enter the following
command to delete a physical volume named sfspvol1:
%
tkadmin delete pvol sfspvol1
5. Use the tkadmin delete disk command to delete each disk that backs a physical
volume. Deleting a disk marks the disk as uninitialized. The command syntax is
tkadmin delete disk -server server_name disk_name
You must specify the name of the disk as the disk_name argument. Any attempt
to delete a disk that still stores a physical volume fails. Remember that some
physical volumes are stored on multiple disks and that a single disk can hold
multiple physical volumes or portions of physical volumes.
In this example, each physical volume resides on its own disk partitionfor
example, sfspvol1 on /dev/rsd0f and sfspvol1.mirr on /dev/rse0f. You must
delete both disk partitions.
On Open Systems. For example, enter the following command to delete a disk
named /dev/rsd0f:
%
tkadmin delete disk /dev/rsd0f
On Windows. For example, enter the following command to delete a disk

named D:\rqs1data:
C:\> tkadmin delete disk D:\rqs1data
6. (Windows Only) Delete the operating system file serving as a disk (the file
initially created by using the fileVol program or your own program). Use any
standard file deletion mechanism to delete the file.
Note: A server retains a logical volumes name even after the volume is deleted.
Further, all volumes of a Toolkit server must have unique names. If you want
to reuse the name of a deleted logical volume, you must rename it (change
the stored name to a different name). Then the original volume name can be
reused (the server no longer retains information about this volume name).
Reclaiming storage space (AIX logical volumes)

You can reclaim space occupied by a servers logical volumes. (Be sure that a
logical volume is no longer in use before reclaiming its storage space.) On AIX, you
reclaim space by unmapping the CICS Toolkit logical volume and then deleting the
backing AIX operating system logical volume. Perform the following steps to reclaim
space occupied by an AIX logical volume:
volume from its backing AIX logical volume. The command syntax is
argument. For example, enter the following command to unmap a logical
volume named sfslvol1:
18
tkadmin unmap lvol sfslvol1
3. Use an AIX utility to delete the AIX logical volume. You can then reuse the
space previously occupied by the volume.
19
20
Chapter 4. Managing server transactions

To effectively administer transactions, you need to understand the states of
transactions, how transactions are identified across servers, and how transactions
use locking. This chapter describes transaction concepts and terminology useful in
reviewing and (if necessary) intervening in problematic unresolved transactions. It
describes how to use the tkadmin commands to display information about
transactions, and how to evaluate and act on transactions.
Viewing server transaction information

You can use the following tkadmin commands to display information about
transactions:
v The tkadmin list transactions command, which displays all unresolved
transactions and their current states.
v The tkadmin query transaction command, which displays details about a
transactions state, initiating application, participating applications, global
identifier, and start time.
Administering transactions
Administrators do not normally need to intervene in server transactions. Timeouts
associated with transactions prevent any one transaction from holding resources at
a server for too long. For example, if two transactions are competing for the same
resource (one holds a lock on a resource and the other is requesting that lock, and
the lock modes conflict) timeouts will eventually abort one of the transactions: the
idle timeout will abort a transaction that is inactive too long, and the operation
timeout will abort an active transaction that is taking too long. Nevertheless, a
transaction can hang indefinitely if, for example, the transaction is prepared but
the coordinator is unreachable.
If a hung transaction is interfering with the operation of your server (perhaps holding
locks that other critical transactions are waiting for), you may need to intervene.
This section describes the types of actions you can take to handle problematic
unresolved transactions.
Intervening in unresolved transactions

To investigate why a transaction is unresolved, begin by using the tkadmin
commands described above to review transaction information at the server. The
action that you take for an unresolved transaction depends on the transactions
state, that is, whether or not it has prepared. In general, the following rules of
thumb apply:
v If a transaction has not yet prepared, you can abort the transaction at any time.
v If a transaction has prepared, you can allow the system to resolve it (allow
normal processing to take place) or you can force an outcome.
Intervening in unprepared transactions

An unprepared transaction can be aborted at any time. Unprepared transaction
states include active, inactive, and preparing. Aborting an unprepared transaction
does not affect the consistency of datathe transactions participants have not yet
notified a coordinator of their readiness to commit. If you abort an unprepared
transaction, any work that was completed on behalf of the transaction is rolled back.
21
When you abort a transaction, the aborted transaction releases locks that other
transactions may be waiting for, possibly freeing a server to perform other
operations. However, any work that was done by the transaction must be redone.
You must weigh the impact of aborting a transaction. Allowing the transaction to
release its locks (abort) can result in better server performance but with a penalty of
later rework.
Intervening in prepared transactions

With transactions that have already prepared, any action that you take is more
significant. To release the locks held by a prepared transaction, you must force it to
commit or to abort. Forcing might be required in the following situations:
v When a transaction can never be completed
v When critical resources are held
v When system performance suffers
You can introduce data inconsistencies whether you force a transaction to commit
or force it to abort. Forcing a transaction to abort results in better damage reporting
to other applications.
Evaluating transactions
You can examine the following areas to determine whether to force a transaction to
commit or to abort:
v Review the transaction state in each of the transactions participating
applications. Participating applications of a transaction share a unique global TID.
In some cases, you can determine the intended outcome of a transaction by
reviewing the local transaction states of each participant.
v Examine locks. A hung transaction can be caused by conflicting locks. After
determining the number of locks held and waiting, you may need additional
information about a locks mode. You can obtain information about the types of
locks being held by a particular transaction by using server-specific lock
commands. For example, the tkadmin query tranlock command can be used to
investigate the source of locking conflicts that can cause two or more
transactions to deadlock for SFS servers. This command displays the lock mode
that the transaction holds, the name of the file on which the lock is placed, and
the key value that is locked.
Intervening in problematic transactions

Note: You can introduce inconsistencies into server data by forcing a transaction to
the wrong outcome.
You can use the following tkadmin commands to manage transactions:
v The tkadmin abort transaction command, which aborts a transaction that is not
yet in the prepared state.
v The tkadmin force transaction command, which forces a transaction outcome. If
this command is issued with no options, the transaction is forced to abort. The
-commitdesired option forces the transaction to commit. The -finish option
forces a transaction to finish regardless of whether its outcome has been
reported to all participating applications.
22
Chapter 5. Performing backups

This chapter describes the procedures used to back up Toolkit server log volumes,
data volumes, and restart data. It also provides procedures for managing backup
files.
Overview
You can use CICSs backup facility to back up server data for CICS recoverable
servers such as Structured File Server (SFS) servers. In the event of a media
failure, server data can be restored from CICS backup files, log archive files, and
the log file as described in Chapter 6, Recovering from failures, on page 33.
The CICS recovery process uses the following files:
v The log file stores information about updates made to recoverable data. A log file
can be thought of as a running journal of changes made to application data. A
recovery service uses the information stored in a log file to restore modified data
to a consistent state in the event of a system failure. The log file is required to
restore the volume to its latest consistent state. The log volume must be mirrored
to ensure the availability of the log file. See Chapter 2, Creating volumes, on
page 7 for information on mirroring.
v Log archive files back up log data in a servers log volume. Log archive files are
automatically generated when media archiving is enabled. Media archiving
moves older data from a log file to log archive files to free storage space. The
CICS recovery process applies the changes recorded in log files and log archive
files to backup files to restore a data volume to a consistent state. (The log
archive files are sometimes referred to as media recovery archive (MRA) files in
CICS messages.)
v Backup files back up application data in a servers data volume. A complete
backup (consisting of one or more backup files) covers an entire volume. Backup
files must be created manually with the tkadmin backup lvol command.
CICS associates each complete backup with the particular log archive file that
contains the earliest data required to restore the volume. (This earliest log
archive file marks the beginning of a sequence of archive files required for that
backup.) A complete backup, along with its associated log files, is required to
restore a data volume.
Figure 4 on page 24 shows the use of backup files, log archive files, and the log file
in the recovery process. Backup files alone are insufficient to restore a volume.
Backup files and log information restore data to a consistent state. Backup files hold
a copy of the volume as it stood when the last backup was made; log information
brings the old data forward (applying the more recent changes to data that had not
yet been backed up). As shown in the figure, older log information is stored in the
archives; current information is in the log file.
23
To recover data from a disk failure on 1/6/05

Log archive files
(media recovery
archives)
Backup files
Log
file
Time
05
6/
1/
05
5/
1/
05
4/
1/
05
3/
1/
05
2/
1/
05
1/
1/
Figure 4. Role of backups in recovery
The first time you start a server, a file named restart is automatically created in the
servers working directory. This file contains volume names, locations, and
configurations. On subsequent restarts, the server uses this file to recover
configuration information about volumes. Server restart files must be manually
backed up by using operating system commands.
The following steps summarize the procedure you follow to create and manage
backups for a server:
1. Enable media archiving To generate log archive files and back up data
volumes, you must enable media archiving. See Media archiving for details.
2. Back up server data volumes Use the tkadmin backup lvol command to back
up server data volumes. See Backing up server data volumes on page 25 for
details.
3. Back up server restart data In addition to backing up server volumes, you
must also back up server restart files. See Backing up server restart data on
page 28 for details.
4. Move backups offline To minimize the risk of losing data, you must move log
archive, backup, and restart files offline. See Moving backups offline on page
28 for details.
5. Manage backup files You must periodically remove old backups to reclaim
storage space. Use the tkadmin query backup command to obtain information
about backups and the tkadmin retain backups command to retain information
about a certain number of backups. See Managing backup files on page 29 for
details.
Media archiving
Media archiving is the process of transparently moving older data from a log file to
log archive files to free storage space. Media archiving must be enabled to
automatically generate the log files needed to recover a servers data volumes. This
section describes how to enable media archiving and, if necessary, how to flush the
media archive (write cached log records from a log file to log archive files).
Enabling media archiving

To generate log archive files and create backups, you must enable media archiving.
Media archiving can be enabled for servers that manage data in SFS servers, but
not for servers that store only log data (Peer-to-Peer Communications (PPC)
gateway servers).
24
With media archiving enabled, log archive files are automatically generated and, by
default, stored in the logArchive directory under the servers working directory. You
must allocate adequate disk space (approximately 4 MB) for this directory. Log
archive filenames are based on the name of the log volume storing the servers log
file and a sequence number beginning with 0 (zero). For example, an SFS server
that stores its log file on a volume named sfslogvol creates archive files named
sfslogvol.LA.0, sfslogvol.LA.1, sfslogvol.LA.2, and so on.
Use the tkadmin query mediaarchiving command to determine whether media
archiving is enabled for a server. The syntax for the command follows:
tkadmin query mediaarchiving -server server_name
Use the tkadmin enable mediaarchiving command to enable media archiving. The
syntax for the command follows:
tkadmin enable mediaarchiving -server server_name
Perform the following procedure to enable media archiving:

1. Use the tkadmin query mediaarchiving command to determine whether media
archiving is enabled for a server. For example, enter the following command to
check media archiving in a server:
%
tkadmin query mediaarchiving
Media archiving is disabled.
2. Use the tkadmin enable mediaarchiving command to enable media archiving for
a server. For example, enter the following command to enable media archiving:
%
tkadmin enable mediaarchiving
To minimize the risk of losing data, you must move log archive files offline as soon
as they are completed. See Moving backups offline on page 28 for details.
Flushing the media archive

A server intermittently writes data to log archive files. If a backup is done but there
is insufficient activity to trigger writing to the log archive, information about the
recent backup is not reflected in the archive file. You can use the tkadmin flush
mediaarchive command to ensure that you have captured all recent activity in the
log archive files. This command writes the cached data to the active archive file,
closes the file, and opens a new archive file for recording subsequent log activity.
The syntax is as follows:
tkadmin flush mediaarchive -server server_name
The following command flushes log records from the log file to log archive files:
%
tkadmin flush mediaarchive
Backing up server data volumes

Backing up a data volume involves dumping its contents to a set of backup files by
using the tkadmin backup lvol command. The command backs up the volume; it
does not back up data structures such as files. To use the tkadmin backup lvol
command, media archiving must be enabled (see Media archiving on page 24).
You can back up a volume while the server is running, although performance may
be slowed.
Each backup file covers some part of the volume. A complete backup exists when
all of the volume has been copied once. Backups are incrementalafter a complete
backup of a volume is created, each additional backup file ends a new complete
25
backup. Different backups of the same volume can overlap or share files. Figure 5
illustrates how complete backups can overlap.
Figure 5. Multiple complete backups
On day 1, a complete backup consisting of four files, 0 through 3, is made. On day

2, two additional backup files are made, each creating a new complete backup (files
1 through 4 and 2 through 5). By day 4, two independent complete backups exist
(files 0 through 3 and 4 through 7). Two backups are independent if they do not
overlap or share files.
Backup file names have the form file_prefix.TRB.sequence_number. The file_prefix
determines the location of the file in the native file system. The string TRB is a
constant that identifies backup files. The sequence_number is appended to make
the backup file names belonging to a particular volume unique. The sequence
numbers are automatically generated by the system. Complete backups are
identified by the sequence number of the most recent file in the backup. For
example, the first complete backup, which ends with file 3, is considered backup 3
(not the third backup).
Using the tkadmin backup lvol command

The syntax of the tkadmin backup lvol command follows:
tkadmin backup lvol -server server_name logical_volume_name \
[-fileprefix file_prefix]
[-filesize file_size] \
Specify the name of the server for the server_name argument and the name of the
logical volume to be backed up for the logical_volume_name argument.
By default, this command generates one backup file containing at most 1 MB of
information. If your volume is larger than 1 MB, using the default values results in a
partial backup. Recall that a complete backup exists when all of the volume has
been copied once. If more than 1 MB of data needs to be backed up, the tkadmin
backup lvol command returns the following warning:
As yet, there is no complete backup of volume volume_name
You must reissue the tkadmin backup lvol command (which generates an additional
1-MB backup file each time it is issued) until no warning is returned. Alternatively,
you can use the -filesize and -nfiles options to specify the size and number of
backup files needed to back up the entire volume. See Creating a complete
backup on page 27 for an explanation of how to calculate the required size and
number of files.
26
The tkadmin backup lvol command has the following optional arguments:
v file_prefix Specifies a prefix used for each backup filename. The prefix can be
a complete or relative pathname used to write the files to a different locationfor
example, /bkups/sfsvol1 (Open Systems), D:\BKUPS\SFSVOL1 (Windows), or
sfsvol1. Using the latter example, the backup files are named
sfsvol1.TRB.000000, sfsvol1.TRB.000001, sfsvol1.TRB.000002, and so on. A
relative pathname is interpreted within the context of the servers working
directory. If a file prefix is not specified, the default is the volume name.
v file_size Specifies the file size. The file_size argument can be specified in
bytes (an integer) or in kilobytes (an integer followed by the letter kfor
example, 51k). If a file size is not specified, the default file size is 1 MB.
v number_of_files Specifies the number of files to be created. If a number of
files is not specified, the default is one file.
Creating a complete backup

You can create a complete backup by reissuing the tkadmin backup lvol command
until no warning is returned, or by specifying the size and number of backup files
needed to back up the entire volume. The CICS Recovery Service keeps track of
the backup files created and automatically begins each new backup file where the
last one ended. A complete backup exists when enough files are created to restore
the entire volume.
To create a complete backup, perform the following steps:
1. Determine the size and number of backup files you want to create. By default,
one backup file containing at most 1 MB of information is generated. This may
not be sufficient for large volumes.
If a volume is very large, you can specify a file size and number of files
sufficient to create a complete backup with one or two issues of the command.
Use the tkadmin query lvol command to determine the volume size. The
command syntax follows:
tkadmin query lvol -server server_name logical_volume_name
Specify the name of the data volume for the logical_volume_name argument.
For example, enter the following command to display information for a volume
named sfsvol1:
%
tkadmin query lvol sfsvol1
Information about logical volume sfsvol1

All sizes and offsets are in pages. Page size is: 4 Kbytes
size: 1998 chunksize: 64
Backing physical volumes (only clean and dirty volumes\
are active):
sfsvol1_physicalVol1 (clean)
Volume is currently enabled.
As the output indicates, the volume is 1998 pages (7992 KB) in size. You must
allow 1 KB per backup file for header information. Therefore, to make a
complete backup for this volume, each backup file must be (7992/n) + 1 KB in
size, where n is the number of files to be created. For example, to create a
complete backup consisting of eight files, each file must be 1000 KB in size.
2. Use tkadmin backup lvol to create the backup. Enter the following command to
back up a 7992-KB volume named sfsvol1 with eight backup files of 1000 KB
each:
%
tkadmin backup lvol sfsvol1 -filesize 1000k -nfiles 8
The command produces eight backup files, sfsvol1.TRB.000000 through

sfsvol1.TRB.000007, each 1000 KB in size. These files constitute a complete
27
backup of the entire volume. This backup is referred to by the backup sequence
number 7 (the number of the last file in the sequence). Additional backups result
in backup files named sfsvol1.TRB.000008, sfsvol1.TRB.000009, and so on.
Each additional file is a valid endpoint of a complete backup; backup 8 consists
of files 1 through 8, and backup 9 consists of files 2 through 9.
3. Use the tkadmin flush mediaarchive command to immediately write cached log
data to an archive file. (The log volume intermittently writes data to archive files.
If a backup is done but there is insufficient activity to trigger writing to the log
archive, information about the recent backup is not reflected in the archive file.)
The syntax is as follows:
The following command writes cached log records to the log archives:
%
Only one backup can be in progress for any given volume. If you try to back up a
volume for which a backup is already in progress, the backup in progress is aborted
and the original invocation of the backup command returns with an error. If a
backup is interrupted by a system or server crash, you can continue the backup
after the server is restarted by reissuing the tkadmin backup lvol command with the
same parameters as before. All previously written files are valid, but the incomplete
file is rewritten.
To minimize the risk of losing data, you must move backup files offline as soon as
they are completed. See Moving backups offline for details.
Backing up server restart data

In addition to backing up server volumes, it is also important to back up server
restart data. The first time you start a server, a file named restart is automatically
created in the /var/cics_servers/SSD/cics/sfs/sfs_server_name directory. This file
contains information required to restart the server. A copy of the restart file, named
restart.bak, is also stored in the same directory. You must back up the restart file
and store the backup offline in case both online copies are lost; see Moving
backups offline for details.
Moving backups offline

To minimize the risk of losing data, you should move all backups offline as soon as
they are completed. This includes all backup files, log archive files, and copies of
server restart files.
Use an operating system utility (for example, the tar command on Open Systems
operating systems and the Backup program on Windows) to move all backups
offline to secure storage. The rate at which you must move backups offline depends
on how frequently they are created.
v Log archive files The rate at which log archive files are generated depends on
how much log data is generated by the server. The log archive file with the
highest sequence number is the most recent archive file. It is possible that the
server is still writing data into that archive file and it should not be moved offline.
Move only inactive (complete) archive files offline.
Note that you can use the tkadmin flush mediaarchive command to immediately
write cached log data to an archive file. This writes the cached data to the active
28
archive file, closes the file, and opens a new log archive file for recording
subsequent log activity. See Creating a complete backup on page 27 for details
on this command.
Log archive files should be moved offline in duplicate. Each complete backup is
associated with a log archive file. This archive file is the earliest file needed to
restore a volume to a consistent state. (It marks the beginning of a sequence of
archive files required for that backup.) To successfully restore a volume, you
need the entire sequence of archive files.
v Backup files The frequency with which you back up a servers data volumes
depends on how much log data you are willing to retain. Each complete backup
of a servers data volume is associated with a particular log archive file that
contains the earliest log data required to restore the volume. The older the
backup, the more log archive files are required to restore the volume. Use the
tkadmin query backup command to determine the earliest log archive file
required by a particular backup (see Querying a backup of a data volume for
details). Move backup files offline as soon as they are completed.
v Restart files All administrative commands affecting a servers volume
configuration change the restart file. For example, creating new logical volumes
for the server or renaming the servers existing volumes changes the restart file.
To ensure you maintain the latest copy of a servers restart file, back up the
restart file once after the server is initially configured and each time you make
changes to the servers configuration. Move the backup file offline as soon as it
is completed.
To restore a volume or server restart file, you must move the appropriate files back
online as described in Chapter 6, Recovering from failures, on page 33.
Managing backup files

To reclaim storage space, you must determine how many backups to retain and
periodically remove old backup and log archive files. Use the tkadmin query backup
command to obtain information on backups and the tkadmin retain backups
command to retain information about a specified number of backups and invalidate
information for old backups.
Querying a backup of a data volume

Use the tkadmin query backup command to obtain information on backups of a data
volume. This command determines how many complete, independent backups exist
for a data volume and the earliest log archive file required for each complete
backup. The command displays the names of the files constituting a backup, the
date and time each file was created, and the earliest log archive file required for the
backup (if a complete backup).
The syntax of the tkadmin query backup command follows:
tkadmin query backup -server server_name logical_volume_name
[-backupfilenum backup_file_number] [-count count] [-all]
You must specify the logical volume name for the logical_volume_name argument.
You can specify the following options and arguments with the command:
v -backupfilenum backup_file_number Specifies the backup file number of the
backup to display. The backup file number is the sequence number of the file that
ends the complete backup. The backup_file_number argument defaults to the
most recent backup for the specified volume.
29
v -count count Specifies the number of complete, independent backups to

display, starting with the most recent backup.
v -all Displays a list of all complete, independent backups for the volume.
The following sections provide examples of how the tkadmin query backup
command can be used to display information about backups.
Querying the most recent backup

To display information about the most recent complete backup for a volume, use the
tkadmin query backup command without specifying any options. For example, enter
the following command to display information for a volume named sfs1_dataVol:
%
tkadmin query backup sfs1_dataVol
A backup for volume rsfs1_dataVol comprises 6 files:

In directory . (relative to servers working directory) :
sfs1_dataVol.TRB.000012 (started Fri May 6 09:55:22 2005)
sfs1_dataVol.TRB.000017 (started Fri May 6 09:55:29 2005,
end of backup 17)
Earliest log archive file required to restore this data volume from
this backup (without restoring associated log volume):
/var/cics_servers/archives/sfs1/sfs1_logVol.LA.43
Earliest log archive file required to restore the log volume can
be determined via the tkadmin query logvol command.
As the output indicates, the most recent backup of sfs1_dataVol consists of six
backup files, numbered 12 through 17. The log archive file named logvol.LA.43 is
the earliest log archive file required to restore the volume using this backup.
Querying a specific backup

To display information about a specific backup, use the -backupfilenum option with
the tkadmin query backup command. For example, enter the following command to
display information about an older backup ending with file number 3 for a volume
named sfsvol1:
%
tkadmin query backup -backupfilenum 3
A backup for volume sfsvol1 comprises 4 files:

In directory . (relative to the servers working directory):
sfsvol1.TRB.000000 (started Tue May 3 18:01:43 EST 2005)
sfsvol1.TRB.000003 (started Tue May 3 18:28:32 EST 2005,
end of backup 3)
Earliest log archive file required to restore this data volume
from this backup (without restoring associated log volume):
The backup that ends with backup file number 3 includes files numbered 0 through
3. The log archive file named logvol.LA.39 is the earliest log archive file required to
restore the volume using this backup.
Listing all complete, independent backups

To display information about all complete, independent backups for a volume, use
the -all option with the tkadmin query backup command. For example, enter the
following command to display information for a volume named sfsvol1:
30
tkadmin query backup sfsvol1 -all
Volume sfsvol1 contains the following complete backups.

(The most recent backup appears first.)
1: The first complete backup comprises the following 4 files:
In directory . (relative to servers working directory):
Earliest MRA file required to restore this data volume from this backup:
2: The second complete backup comprises the following 4 files:
In directory . (relative to servers working directory):
sfsvol1.TRB.000003 (started Mon May 2 18:28:32 EST 2005)
Earliest MRA file required to restore this data volume from this backup:
The output displays two independent backups. The first (and most recent)
independent backup consists of backup files 4 through 7. The second independent
backup consists of backup files 0 through 3.
Retaining backups
Use the tkadmin retain backups command to keep information about a specified
number of complete, independent backups, starting with the most recent backup.
The command does not remove any backups, but it invalidates the information
associated with old backups. The command deletes any log archive files associated
with the invalidated backup files. Upon successful completion, the command
displays a list of backup files that can be removed. Use an operating system
command to remove the files.
The command syntax follows:
tkadmin retain backups -server server_name logical_volume_name number_of_backups
Specify the name of the logical volume for the logical_volume_name argument and
the number of independent backups to retain for the number_of_backups argument.
For example, assume the volume sfsvol1 has three independent backups: one
consisting of files 0 through 3, another consisting of files 4 through 7, and the third
consisting of files 8 through 11. Enter the following command to retain the two most
recent independent backups for the volume named sfsvol1:
%
tkadmin retain backups sfsvol1 2
Truncated backup for volume sfsvol1

The following files are no longer needed.
numFiles: 4
0: sfsvol1.TRB.000000
The output indicates that files 0 through 3 can be removed safely.
Querying a log volume

Use the tkadmin query logvol command to obtain information about a log volume.
The command displays the following information:
v The name of the log volume.
v The name of the associated archive device.
31
v The name of the oldest archive file stored on that device.

v The available free space on the log volume.
v The number and names of the log files stored on the volume.
The syntax of the tkadmin query logvol command follows:
tkadmin query logvol -server server_name logical_volume_name
The following example displays information about the log volume sfs1_logVol:
%
tkadmin query logvol sfs1_logVol
Information about log volume : sfs1_logVol

Archive device :
/var/cics_servers/archives/sfs1/
Oldest offline archive file :
Number of free pages : 2048
Number of log files : 1
Log file list :
logFile
32

This chapter provides instructions for recovering from the following types of SFS
and PPC Gateway server failures:
v Abnormal Server Termination An abnormal server termination is a
configuration or system problem that causes a server to terminate unexpectedly.
For example, a power failure can cause a server to terminate abnormally.
v Media Failure A media failure is any failure of disk storage that causes a loss
of data. For example, a disk head crash that makes the disk unavailable or
destroys data is a media failure. Media failures can affect any of a servers
logical volumes (a log volume or a data volume). The procedure to recover from
a failure depends on the type of volume affected, the type of device backing the
logical volume, and your backup and archiving policies.
Abnormal server termination

An SFS and PPC Gateway server can terminate abnormally due to system
problems. At the time of failure, active transactions are interrupted. The system
automatically recovers from this type of interruption when the server is restarted in
normal operations mode. Specifically, the servers log file is replayed to update the
servers data to its state just before the time of failure.
SFS and PPC Gateway server data is transactionally consistent across restarts. In
most cases, restarting the server is all that is needed to fix the problem.
Media failure
Physical storage media can fail for many reasons. One common cause of media
failure is a hardware (disk) failure. When a media failure occurs, you must
determine the extent of the damage and restore a servers data before resuming
server operation.
Diagnosing a media failure

When a media failure occurs and a servers attempt to use a disk fails, the server
issues a warning message. An example warning message follows:
Volume sfslvol1 error 0x7857B004 disk admv4_restartingacicstoolkitserver/dev/rsd3c
VolPageNumber 0x00000001 DiskPageNum 0x00000008
Server messages are sent through the CICS Trace Facility to a specific destination.
The default destination for error trace class output (which includes warning
messages) is the servers standard error stream.
After reviewing the CICS error message, check the operating system error log for
further information on the disk failure. For example, on Open Systems, view all error
output to determine the following:
v The name of the damaged disk
v The disk sector that is damaged
v The name of the logical volume that is backed by the damaged disk
v The availability of the volumes data (whether the volume was mirrored and
whether at least one mirror remains undamaged)
33
You can use the tkadmin query lvol command to determine exactly how a logical
volume was affected by a media failure. Depending on the extent of the damage,
you can choose the appropriate repair procedure. You need to either repair a failed
mirror or restore a data or log volume.
Viewing restart files

When a server is not available or cannot be started, you can use restart information
from CICS Toolkit volume restart files to determine how a servers volumes are
configured. This information is an alternative to issuing the tkadmin administrative
commands that display volume and mirror information (for example, the tkadmin
query lvol and tkadmin query pvol commands).
Restart files should be read for informational purposes only. Any attempt to modify
them manually can lead to irreversible damage to the restart data. It is
recommended that you contact your product support representative for assistance
in evaluating and resolving volume configuration problems. If your volumes are
managed by the AIX LVM instead of by CICS, use AIX utilities to determine how
volumes are configured.
A volume restart file contains volume names and their disk locations. Restart files
are automatically created when the server is started for the first time. On
subsequent restarts, the server uses the file to recover configuration information
about volumes.
The restart files were specified as the argument to the -v option of the startup
command.
Use operating system commands to view restart filesfor example, use cat or
more on Open Systems or notepad on Windows. The following example displays
volume restart information for a CICS server on an Open System. The command is
issued in the directory /var/cics_servers/SSD/cics/sfs/sfs1, the working directory
of the server.
% cd /var/cics_servers/SSD/cics/sfs/sfs1
%
more restart
The output consists of lists of attribute-value pairs. The sections of output are as
follows:
v Lists that begin "EntryType" "disk" provide general information about disks,
including raw disk device name, disk size, regions, and offsets.
v Lists that include "EntryType" "physicalVol" describe the physical volumes for
the server. Information includes the volume name, its raw disk device name, its
ID, its state, number of pages, and number of regions.
v Lists that include "EntryType" "logicalVol" describe the logical volumes for the
server. Information includes the volume name, number of pages, and the ID
number of backing physical volumes.
The example output indicates that there are two logical volumes, sfsLogLvol and
sfsLvol. The logical volume sfsLogLvol is 992 pages. It has one backing physical
volume: sfsLogPvol (disk partition /dev/rdsk/c0t3d0s6). The logical volume
sfsLvol is 992 pages. It has one backing physical volume: sfsPvol (disk partition
/dev/rdsk/c0t3d0s7).
("LastId" 14
"ReleaseNumber" 3
"ReleaseVersion" 0)("EntryType" "disk"
34
"Label" "/dev/rdsk/c0t3d0s6"
"Name" "/dev/rdsk/c0t3d0s6"
"NumRetries" 5
"RegionOffset" [0]
"RegionSize" [992]
"Size" 1024)("EntryType" "disk"
"Label" "/dev/rdsk/c0t3d0s7"
"Name" "/dev/rdsk/c0t3d0s7"
"NumRetries" 5
"RegionOffset" [0]
"RegionSize" [992]
"Size" 1024)("ChunkSize" 32
"Disks" ["/dev/rdsk/c0t3d0s6"]
"EntryType" "physicalVol"
"Id" 11
"Name" "sfsLogPvol"
"NumPages" 992
"PageNum" [0]
"RegionOffset" [0]
"State" 84)("ChunkSize" 32
"Disks" ["/dev/rdsk/c0t3d0s7"]
"EntryType" "physicalVol"
"Id" 13
"Name" "sfsPvol"
"NumPages" 992
"PageNum" [0]
"RegionOffset" [0]
"State" 84)("Destroyed" 0
"EntryType" "logicalVol"
"Id" 12
"LvmMapped" 0
"Mirrors" [11]
"Name" "sfsLogLvol"
"NumPages" 992)("Destroyed" 0
"EntryType" "logicalVol"
"Id" 14
"LvmMapped" 0
"Mirrors" [13]
"Name" "sfsLvol"
"NumPages" 992)
Restoring lost or damaged data

The procedure to use for restoring lost or damaged data depends on whether your
volumes are mirrored and on the extent of the media damage, as follows:
v If the logical volume affected by a media failure was mirrored and a mirror copy
of the volume remains undamaged, you can synchronize the failed mirror with
the functional one. Data mirroring makes the repair process less costly because
the repair can be done without having to restore data. (Restoring data requires a
temporary server outage.) See Repairing a failed mirror on page 39 for
instructions on repairing a failed mirror.
v If the logical volume affected by the media failure was not mirrored or if the
media failure affected all mirror copies, you must stop the server and restore the
data by using backup files and log archive files. See Restoring a data volume
on page 40 or Restoring a log volume on page 42 for instructions on restoring a
data volume or log volume.
Ensuring that media is functional on page 36 contains instructions for ensuring
that a logical volume is backed by functional disks or a functional AIX logical
volume. This is the one common procedure required in all repair or restore
instructions. It is explained once, in detail, and referred to throughout the remainder
of the repair and restore procedures.
35
Ensuring that media is functional

Before you can repair a failed mirror or restore a logical volume, you must first
make sure that the disk (or AIX logical volume) backing the failed mirror or logical
volume is functional. In some cases, a temporary error in writing to a disk causes a
failure. In other cases, the failure is caused by a permanent conditionfor example,
a hardware malfunction. You must determine the cause and nature of the failure:
temporary or permanent.
If the failure is temporaryfor example, a power failureyou can repair or restore
the servers data when power returns. This can be as simple as restarting the
server or issuing a command to instruct the server to synchronize its mirrors. If the
failure is permanent, you must first relocate the volume onto functional physical
storage devices before repairing or restoring the servers data.
Open Systems and Windows. You can ensure that a volume is backed by
functional disks in one of the following ways:
v Move the physical volume from damaged disks to functional disks (when there is
at least one good mirror for the logical volume). See Moving a physical volume
to functional disks (Open Systems and Windows).
v Recreate the logical volume using different, functional disks (when there is not a
good physical volume backing the logical volume). See Recreating a logical
volume on functional disks (Open Systems and Windows) on page 37.
AIX logical volumes. You can ensure that a logical volume is backed by a
functional AIX operating system logical volume in one of the following ways:
v Move the AIX operating system logical volume onto functional disks (when there
is at least one good mirror for the logical volume). See Moving an AIX logical
volume to functional disks (AIX logical volumes) on page 39.
v Remap the logical volume to a different, functional AIX logical volume (when
there is not a good physical volume backing the logical volume). See
Remapping a logical volume to functional AIX volumes (AIX logical volumes) on
page 39.
Moving a physical volume to functional disks (Open Systems

and Windows)
To ensure that a mirror or volume is backed by functional disks, use the tkadmin
move pvol command to move the physical volume from failed disks to functional
disks. This command copies as much of the existing physical volume as possible
but does not guarantee that the new physical volume is an accurate copy if there
are read errors on the original physical volume.
Perform the following steps to move a physical volume to functional disks:
2. Create a new physical disk. On Open Systems, use an operating system utility
to create a disk or disk partition. On Windows, use the Disk Administrator to
create a new disk partition or the CICS fileVol program to create a new, fully
allocated operating system file.
3. Use the tkadmin init disk command to initialize the disk. The command syntax
follows:
You must specify the name of the disk to be initialized as the disk_name
argument.
36
On Open Systems. For example, enter the following command to initialize a

disk named /dev/rsd0f:
%
On Windows. For example, enter the following command to initialize a disk

named D:\rsfs1data:
C:\> tkadmin init disk D:\sfs1data
4. Use the tkadmin move pvol command to move the physical volume. The
tkadmin move pvol -server server_name physical_volume_name
number_of_regions {{source_disk_name source_disk_offset region_size
destination_disk_name destination_disk_offset}...}
physical_volume_name argument and the number of regions for the
number_of_regions argument. For each region, you must specify the source
disk name for the source_disk_name argument, the source disk offset for the
source_disk_offset argument, the size of the region for the region_size
argument, the destination disk name for the destination_disk_name argument,
and the destination disk offset for the destination_disk_offset argument. The disk
space specified for the destination disk must be at least as large as the disk
space of the original (source) disk.
You can use the tkadmin move pvol command to obtain information about the
physical volume needed in this command. Moving physical volumes does not
affect the mapping of physical volumes to logical volumes. (Deleting and
recreating the logical volume is not necessary.)
Note: You must move all regions that backed the original physical volume. If an
original source disk is not backing a physical volume after this operation,
it can be removed.
On Open Systems. For example, enter the following command to move a
region (with an offset of 0 (zero) and size of 1984) of the physical volume
named pvol8. The region is moved from disk partition /dev/rsd1f to disk
partition /dev/rsd2g at an offset of 0:
%
tkadmin move pvol pvol8 1 /dev/rsd1f 0 1984 /dev/rsd2g 0
On Windows. For example, enter the following command to move a region

(with an offset of 0 (zero) and size of 1984) of the physical volume named
pvol8. The region is moved from the disk D:\serverdata to the disk
F:\serverdata at an offset of 0:
C:\> tkadmin move pvol pvol8 1 D:\serverdata 0 1984 F:\serverdata 0
Recreating a logical volume on functional disks (Open Systems

and Windows)
To ensure that a failed mirror or volume is backed by functional disks, delete and
recreate the logical volume on functional disks. This procedure destroys all data in
the logical volume. The data must be restored.
Perform the following steps to recreate a logical volume on functional disks:
2. Use the tkadmin delete lvol command to delete the mapping between the CICS
Toolkit logical volume and the existing physical volumes. The command syntax
follows:
37
argument. For example, enter the following command to delete the mapping for
a logical volume named lvol8:
%
tkadmin delete lvol lvol8
3. Create a new physical disk. On Open Systems, use an operating system utility
to create a disk or disk partition. On Windows, use the Disk Administrator to
create a new disk partition or the CICS fileVol program to create a new, fully
allocated operating system file.
4. Use the tkadmin init disk command to initialize the disk. The command syntax
follows:
You must specify the name of the disk to be initialized as the disk_name
argument.
On Open Systems. For example, enter the following command to initialize a
disk named /dev/rsd0f:
%
On Windows. For example, enter the following command to initialize a disk

named D:\sfs1data:
C:\> tkadmin init disk D:\sfs1data
5. Use the tkadmin create pvol command to create a new physical volume . The
tkadmin create pvol -server server_name physical_volume_name
chunk_size number_of_regions {{disk_name disk_offset
[-regionsize region_size]}...}
physical_volume_name argument, the chunk size (in pages) of the physical
volume for the chunk_size argument, and the number of regions comprising the
physical volume for the number_of_regions argument. For each region, specify
the name of the disk supplying the region for the disk_name argument, the
offset of the region for the disk_offset argument, and optionally, the size of the
region for the region_size argument.
The physical volume can contain one or more regions from one or more disks.
Further, the physical volume can cover an entire disk partition (when disk offset
is 0 (zero) and no region size is specified) or a portion of a disk partition (when
the disk offset is nonzero, the region size is specified, or both).
On Open Systems. For example, enter the following command to create a
physical volume named sfspvol2 made up of one region, with a chunk size of
64 and an offset of 0, on a disk named /dev/rsd0g:
%
tkadmin create pvol sfspvol2 64 1 /dev/rsd0g 0
Because the disk offset is 0 (zero) and a region size is not specified, the region
encompasses the entire disk partition (partition /dev/rsd0g).
On Windows. For example, enter the following command to create a physical
volume named sfspvol2 made up of one region, with a chunk size of 64 and an
offset of 0, on a disk named D:\serverdata:
C:\> tkadmin create pvol sfspvol2 64 1 D:\serverdata 0
Because the disk offset is 0 (zero) and a region size is not specified, the region
encompasses the entire disk partition (logical drive D:).
6. Use the tkadmin recreate lvol command to recreate the logical volume. The
tkadmin recreate lvol -server server_name logical_volume_name
38
This command creates a new mapping from the logical volume to the new
functional physical volume. You must specify the name of the logical volume for
the logical_volume_name argument and the name of the physical volume for the
physical_volume_name argument. For example, enter the following command to
map a logical volume named lvol8 to a functional physical volume named
pvol8:
%
tkadmin recreate lvol lvol8 pvol8
Moving an AIX logical volume to functional disks (AIX logical

volumes)
You must use an AIX administrative utility to move an AIX operating system logical
volume. The tkadmin commands cannot be used to move AIX logical volumes.
Remapping a logical volume to functional AIX volumes (AIX

logical volumes)
If you are using an AIX operating system logical volume to back a CICS Toolkit
logical volume, you must unmap the CICS Toolkit logical volume and then remap it
to a functional AIX logical volume. This procedure destroys all data in the logical
volume. The data must be restored.
Perform the following steps to remap a logical volume:
1. Discard the failed AIX logical volume (the space can be reclaimed later).
volume. The command syntax follows:
logical_volume_name argument. For example, enter the following command to
unmap a logical volume named sfslvol1:
%
tkadmin unmap lvol sfslvol1
4. Create a new AIX logical volume (or use an existing one) to replace the failed
AIX logical volume. The new AIX logical volume must be at least as large as the
original AIX volume.
5. Use the tkadmin remap lvol command to remap the CICS Toolkit logical volume
to a functional AIX logical volume. The command syntax follows:
operating_system_logical_volume_name
logical_volume_name argument and the name of the AIX logical volume for the
operating_system_logical_volume_name argument. For example, enter the
following command to remap a CICS Toolkit logical volume named sfslvol1 to
an AIX logical volume named aix.sfslvol1:
%
tkadmin remap lvol sfslvol1 aix.sfslvol1
Repairing a failed mirror

If a media failure affects one mirror of a mirrored volume, you can return the
volume to its normal state by repairing the failed mirror. For CICS Toolkit logical
volumes backed by physical volumes, you synchronize the mirrors. For CICS Toolkit
logical volumes backed by AIX logical volumes, you must use AIX administrative
utilities to repair the AIX mirror.
39
In either case, the server can continue operating. Depending on the needs and use
of the specific server, you may choose to shut down a server before repairing the
mirror. Restarting the server in administrative mode before repairing a failed mirror
prevents further media failure.
On Open Systems and Windows. Perform the following steps to repair a failed
mirror:
1. Make sure that the storage devices backing the failed volume are functional.
Refer to the procedures described in Ensuring that media is functional on page
36.
2. If necessary, restart the server in normal operations mode.
3. Synchronize the original copy and the new mirrored copy of the data. (Both
copies are referred to as mirrors.) You synchronize the mirrors by using the
tkadmin sync mirrors command. The command syntax follows:
tkadmin sync mirrors -server server_name logical_volume_name
argument. The command does not return until the synchronization is complete.
For example, enter the following command to synchronize all the mirrors
backing a logical volume named sfslvol1:
%
tkadmin sync mirrors sfslvol1
On AIX logical volumes. On the AIX operating system, the mirroring of data can
be performed by the operating system or by CICS. To correct the mirroring of an
AIX logical volume used to store a CICS Toolkit logical volume, you must repair the
AIX volume with an AIX utility. The tkadmin commands cannot be used.
However, if a media failure affecting AIX logical volumes results in a loss of data,
the data must be restored using CICS (not AIX utilities). Instructions for restoring
volumes are provided in Restoring a data volume and Restoring a log volume on
page 42.
Restoring a data volume

For the restore process to succeed, the servers log volume (log file) must be
undamaged (or must already have been restored, if lost). The restore procedure for
a data volume has two phases. In the first phase, the servers recovery service
component copies the contents of the backup files onto the volume. A backup is
identified by the sequence number of the most recent file that is part of the backup
(the one with the highest number). The oldest backup file is copied first, and the
newest backup file is copied last.
All backup files need not be online at the same time. During restoration, if an offline
backup file is needed, the restore command returns a bad backup file number
error message. You can then bring the backup file online and resume the restore by
reissuing the restore command. The restore process can be resumed from where it
left off; the backup files that have already been used (copied to the new logical
volume) are no longer needed online.
For example, consider a backup that contains files with sequence numbers 0 (zero)
through 6. Only files 4 through 6 are online at the beginning of the restore. When
the restore command returns with a bad backup file number error message, you
can bring the backup files numbered 0 (zero) through 3 online and resume the
restore by reissuing the command.
40
The second phase of the restore begins after all the backup files have been copied
onto the volume. In this phase, all updates to the volume made since the backup
are redone using the records in the servers log file (from the oldest data in the
archive files to the latest data in the log file). This may require the server to read
log data from archive files that are no longer online. In that case, the server issues
a message requesting an offline archive file. You must monitor the server during a
restore and respond to any requests.
A summary of the restore procedure follows:
1. Restart the server in administrative mode.
2. Remove all mirrors of the logical volume.
3. Ensure that media is functional.
4. Restore data volumes.
5. Monitor the restore process, and, if necessary, move archive files online.
6. Recover the servers data volumes.
7. Add new mirrors and synchronize them.
The procedure to restore a servers data volumes from backup files and log archive
files is the same for all devices used to back CICS Toolkit logical volumes.
Perform the following steps to restore a data volume:
2. Use the tkadmin remove mirror command to remove all mirrors of the logical
volume (leaving only one copy of the data to be restored). This command must
be issued once for each mirror being removed. The command syntax follows:
tkadmin remove mirror -server server_name logical_volume_name
You must specify the logical volume name for the logical_volume_name
argument and the physical volume name of the mirror to be removed for the
physical_volume_name argument. (You can view information about which
physical volumes back a logical volume by using the tkadmin query lvol
command.)
For example, enter the following command to remove the mirror named
sfspvol1 backing the logical volume sfslvol1:
%
tkadmin remove mirror sfslvol1 sfspvol1
3. Make sure that the failed volume is backed by functional disks. Refer to the
procedures described in Ensuring that media is functional on page 36.
4. Use the tkadmin restore lvols command to restore the data volumes. The
tkadmin restore lvols -server server_name number_of_volumes
{{logical_volume_name [-backupfilenum backup_file_number]}...}
[-noresume]
You must specify the number of logical volumes to be restored as the

number_of_volumes argument. For each logical volume, you specify the name
of the logical volume for the logical_volume_name argument and (optionally) a
backup file number for the backup_file_number argument. The default backup
file number is the number of the last complete backup of the volume. For
example, enter the following command to restore a logical volume named
testVol using backup file number 5:
%
tkadmin restore lvols 1 testVol -backupfilenum 5

41
Because each server has a single log file, restoring multiple volumes via
separate invocations of the restore command requires reading the same log file
several times. To avoid this, the restore command accepts a list of volumes to
be restored concurrently. However, you can have only one outstanding restore
request at a time. Do not issue a second restore command until the first is
complete.
5. After restoring failed volumes, use the tkadmin recover lvols command to
recover the servers data volumes. The command brings a servers data
volumes up- to-date with the information in the servers log file, if any, and
mounts the enabled logical volumes, if any. The command syntax follows:
tkadmin recover lvols -server server_name
For example, enter the following command to recover data volumes:

%
6. Add new mirrors and synchronize them.

Restoring a log volume

You can restore a servers log volume if you have enabled media archiving and
periodically moved archive files to secure offline storage. If you have stored a
servers log archive files, a log volume can be restored to a consistent state.
However, some log data can be lost. Log data stored in the log file but not yet
moved to archive files is lost, and any online archive files (including the most recent
archive file) can be lost. Move archive files offline to safe storage at regular
intervals to minimize the potential loss.
Log archive files still online at the time of failure may not be lost. Always attempt to
collect the most recent archive files available. Using the last complete archive file
available enables you to restore the log volume to the most recent state possible.
The following is a summary of the restore procedure for log volumes:
1. Restart the server in administrative mode.
2. Ensure that media is functional.
3. Restore the log volume.
4. Monitor the restore process.
5. Enable the log file.
6. Restore the servers data volumes (see Restoring a data volume on page 40).
The procedure for restoring log volumes from log archive files is the same for all
devices used to back CICS Toolkit logical volumes.
Perform the following steps to restore a log volume:
2. Make sure that the log volumes are backed by functional disks. Refer to the
procedures described in Ensuring that media is functional on page 36.
3. Use the tkadmin restore logvol command to restore the log volume. The
tkadmin restore logvol -server server_name log_volume_name
archive_device_name archive_file_name
42
You must specify the name of the log volume as the log_volume_name
argument, the name of the archive device associated with the log volume as the
archive_device_name argument, and the name of the latest archive file as the
archive_file_name argument.
The server reads in a range of archive files ending with the specified archive
file. It uses these files to restore the log volumes contents. At least the latest
archive files to be used in the restore should be available online. As other
archive files are required, the server displays a message requesting that the
necessary archive file be fetched. After fetching the required archive file, use the
tkadmin enable archfile on page 188 command to inform the server that the
file is available. The restore procedure continues, using the requested archive
file.
On Open Systems. For example, enter the following command to restore a log
volume named sfslogvol using archive files in the logarchive directory. The
command uses archive files up to the sfslogvol.LA.27 archive file (sequence
number 27):
%
tkadmin restore logvol sfslogvol logarchive logarchive/sfslogvol.LA.27
On Windows. For example, enter the following command to restore a log

volume named sfslogvol using archive files in the logarchive directory. The
command uses archive files up to the sfslogvol.LA.27 archive file (sequence
number 27):
C:\> tkadmin restore logvol sfslogvol logarchive logarchive\sfslogvol.LA.27
4. Monitor the restore process. During the restore process, log archive files that
are offline may be needed. You must monitor the warning messages generated
by the server during a restore in case archive files need to be moved online. An
example message follows:
OP MSG: Fetch archive file sfslogvol.LA.14
After fetching, invoke tkadmin enable archfile.
After receiving a warning message asking for an archive file, use an operating
system utility to move the archive file online. Then, use the tkadmin enable
archfile on page 188 command to notify the server that the archive file is
available. The command syntax follows:
tkadmin enable archfile -server server_name archive_file_name
You must specify the name of the archive file as the archive_file_name
argument.
On Open Systems. For example, enter the following command to enable an
archive file named sfslogvol.LA.14:
%
tkadmin enable archfile logarchive/sfslogvol.LA.14
On Windows. For example, enter the following command to enable an archive

file named sfslogvol.LA.14:
C:\> tkadmin enable archfile logarchive\sfslogvol.LA.14
5.
Use the tkadmin enable logfile command to enable the log file. The command
syntax follows:
tkadmin enable logfile -server server_name log_file_name
You must specify the name of the log file as the log_file_name argument. The
format is log_volume/log_file_name, where log_volume is the volume on which
the log file is storedfor example, sfslogvol/sfslogfile. You can obtain the
name of the log file by using the tkadmin query logvol command. The following
command enables a log file named sfslogfile on the volume sfslogvol:
%
tkadmin enable logfile sfslogvol/sfslogfile
6. Restore all data volumes. This synchronizes the servers data volumes with its
log file. This must be done regardless of whether the data volumes were
43
damaged. See Restoring a data volume on page 40 for instructions on using

backup files and log data to restore a data volume.
CAUTION:
After restoring the log file, any attempt to start a server in normal
operations mode may corrupt its log file. Be sure to remain in administrative
mode to restore data volumes. Note that you do not have to stop and restart
the server in administrative mode. After you restore and enable the log
file, the server is in the same state as it would be if started in
administrative mode with a valid log file.
44
Chapter 7. Using the CICS Toolkit Trace Facility

This chapter introduces the CICS Toolkit Trace Facility and describes how to enable
and redirect trace output. It also describes how to format trace output and dump
state information. For information on interpreting trace output and troubleshooting
CICS, contact your CICS product support representative.
Introduction to the CICS Toolkit Trace Facility

The CICS Toolkit Trace Facility provides tools that monitor error messages, enable
selective tracing of execution path events, and dump information about the state of
an SFS or PPC Gateway server. You can use the CICS Toolkit Trace Facility to
specify the type and destination of trace output generated for an SFS or PPC
Gateway server and to manipulate trace output.
This section describes the types of trace output and the tracing that is always
enabled.
Types of trace output and destinations

The CICS Toolkit Trace Facility classifies different types of trace output. Table 6 lists
the classes of trace output and their default destinations for Monitor processes.
Table 6. CICS Toolkit Trace classes
Trace class
Content of trace output
audit
Messages related to security and

configuration events
error
Nonfatal error (warning) messages
fatal
Fatal and termination messages
entry
Execution path entry and exit information
event
Execution path event information
param
Execution path parameter information
dump
State information
All trace output is captured in a main memory ring buffer. You can redirect any class
of trace output from the ring buffer to one of the following destinations:
v A file
v A standard input/output (I/O) stream, such as the standard error or standard
output devices
v The AIX trace (trace) or error logging (errlog) facility
Fatal, error, and audit output is always enabled. By default, output is directed to
the standard error device.
Note: On Windows systems, output is directed to both the standard error device
and the Windows Event Log.
By default, entry, event, param, and dump output is not enabled, meaning that it
is captured only in the main memory ring buffer. The entry, event, and param
classes of output can be enabled selectively and redirected by using trace masks;
45
see Trace specifications for more information. The dump class of output can be
enabled by using tkadmin commands.
Because tracing affects performance, consider the implications of sending trace
output to different locations. Sending trace output to a file, I/O stream, or AIX facility
can slow performance. Because trace output can be large, use caution when
sending trace output to a file or I/O stream.
Tools for tracing

The CICS Toolkit Trace provides tools for performing the following trace functions:
v Enabling and redirecting trace output
v Manipulating trace output
v Dumping state information
v Obtaining thread-specific error histories
On all platforms, the CICS Toolkit Trace provides the following commands for
manipulating trace output. Manipulating trace output on page 51 describes how to
use each of these commands.
v The tkadmin dump ringbuffer command dumps trace output contained in a main
memory ring buffer to a file.
v The tkadmin set ringbuffer size command changes the size of a ring buffer.
v The indentTrace command indents nested functions in trace output to make them
more visible.
v The interpretTrace command translates a trace binary output file into readable
text.
v The translateError command translates CICS or RPC status codes.
Finally, on Windows, WinTrace provides the functionality of the indentTrace,
interpretTrace, and translateError commands in a graphical interface. Manipulating
trace output with WinTrace (Windows only) on page 56 describes how to use
WinTrace.
How to change tracing

You can control tracing by using the tkadmin trace specification and tkadmin
redirect trace commands.
Trace specifications
You can enable, modify, or disable selective tracing of the entry, event, and param
classes of output for a server by using trace masks. A trace mask is a 32-bit
unsigned integer associated with each CICS Toolkit component running in a server.
Bits in the trace mask enable various types of tracing in a component. To determine
the components running in a server, use the tkadmin list trace command; see
Listing components on page 48.
A trace option is used to specify types of tracing and is identified by a string value
or its associated hexadecimal value. Bits 0 through 7 (0x000000FF) represent the
standard trace options common to all components. The remaining 24 bits represent
component-specific trace options. Table 7 on page 47 lists the standard trace
options common to all CICS Toolkit components. To list the trace options that are
specific to a component, use the tkadmin query trace command; see Listing trace
options on page 49.
46
Table 7. Standard trace options

Trace Option
Hex Value
C Symbolic
Constant
Type of Tracing
Enabled
trace_event
0x00000001
TRACE_EVENT
Events in all functions
trace_entry
0x00000002
TRACE_ENTRY
Entry/exit of all
exported functions
trace_param
0x00000004
TRACE_PARAM
Parameters of all
exported functions
trace_export
0x00000006
TRACE_ENTRY+
TRACE_PARAM
Entry/exit and
parameters of all
exported functions
trace_internal_
entry
0x00000008
TRACE_INTERNAL_
ENTRY
Entry/exit of
nonexported
functions
trace_internal_
param
0x00000010
TRACE_INTERNAL_
PARAM
Parameters of
nonexported
functions
trace_global
0x0000001F
TRACE_GLOBAL
Entry/exit and
parameters of all
functions
trace_all, all
0xFFFFFFFF
None
All bits in the trace

mask
The basic syntax of a trace mask specification follows:

name=trace_options...
You must specify a valid component name for the name argument and one or more
trace options or their corresponding hexadecimal values for the trace_options
argument. Use the following syntax conventions when specifying a trace mask:
v To combine trace options by bitwise addition, use the syntax
trace_option+trace_option
v To combine trace options by bitwise subtraction, use the syntax

trace_option-trace_option
v To set or replace the components current trace mask with the trace options
specified, use the syntax
name=trace_options...
v To turn off or subtract specific trace options in the current trace mask, use the
syntax
name-=trace_options...
v To add trace options to the current trace mask, use the syntax
name+=trace_options...
v To disable all tracing for the named component, specify 0 (zero) for the
trace_options argument.
v To assign the same trace options to multiple component trace masks, use the
syntax
name1=name2=trace_options...
For example, the following trace mask specification enables entry, exit, and param
tracing for the trpc component:
trpc=trace_entry+trace_exit+trace_param
47
The following trace mask specification adds event tracing to the current trace mask
for the trpc component:
trpc+=trace_event
The following trace mask specification disables event tracing for the trpc
component:
trpc-=trace_event
The following trace mask specification disables tracing for all components:
all=0
Listing components
You can list the products and components running in a server and their associated
trace masks by using the command. The command syntax follows:
tkadmin list trace -server server_name [-product product_name]
[-component component_name]
For example, enter the following command to list the products and components
running in a server and their associated trace masks:
% tkadmin list trace
% tkadmin list trace
CICS Toolkit Server Core:
lock=0
rec=default
log=default
vol=default
restart=0
CICS Toolkit Area Manager:
area=default
CICS Toolkit Executive:
threadTid=0
alf=0
tran=0
tc=0
trpc=trace_all
trdce=trace_all
epm=0
admin=default
util=0
CICS Toolkit Private:
npr=0
sutils=0
startup=0
CICS SFS:
sfs_dir=0
sfs_ar=general
sfs_es=0
sfs_rel=0
sfs_btree=0
sfs_ddt=0
sfs_svr=trace_all
CICS Toolkit BDE:
bde=0
As the output indicates, the CICS Toolkit Executive, CICS Toolkit Base Development
Environment (BDE), and CICS SFS products along with others are listed with their
components and associated trace masks. A trace mask value of 0 (zero) indicates
48
that tracing is not enabled for the component. A trace mask value of default
indicates that the default trace mask for that component is used.
Listing trace options

You can display the current trace mask of a component and all of the trace options
available for that component by using the tkadmin query trace command. The
tkadmin query trace -server server_name component_name
Specify a component name for the component_name argument. For example, enter
the following command to display the current trace mask and valid trace options for
the tmxa component:
%
tkadmin query trace tmxa
0x00000401:
0x00000100:
0x00000200:
0x00000400:
0x00000800:
0x00001000:
tmxa_traceMask
xa
lock
callback
xa90
init
As the output indicates, the current trace mask value for the component is
0x00000401 or tmxa_traceMask. All other valid hexadecimal values and their
corresponding string values are also listed.
Trace destinations
By default, fatal, error, and audit trace class output is redirected from the ring
buffer to the servers standard error device. Messages generated by these classes
can greatly impact the operation of the system and should be monitored. These
trace classes can be redirected to a different file, but they must be directed to some
destination for monitoring (they cannot be allowed to remain in the ring buffer only).
Specify a trace output destination by using the tkadmin redirect trace command.
The basic syntax is as follows:
tkadmin redirect trace -server server_name trace_class -destination destination
The trace_class argument can be one or more of the standard trace classes: trace,
fatal, error, audit, dump, entry, event, or param. CICS also provides the following
aliases for frequently used combinations of trace classes:
v The critical alias includes the audit, error, and fatal trace classes.
v The trace alias includes the entry,event, and param trace classes.
v The all alias includes all of the standard trace classes.
You can also specify an option argument, which describes the buffering and
formatting characteristics of the output. You can specify any of the following as
options: buffered or unbuffered, and formatted or unformatted.
If output is buffered, trace events are stored and sent in batches using a single
output operation to reduce performance costs. If output is unbuffered, each trace
event is reported in a single output operation. Formatted output is in ASCII format;
unformatted output is in binary format. If the specified destination type provides
buffering, buffering is used. By default, output is unbuffered and formatted. The
buffered and formatted options can each take an argument. In the form
buffered=maximum_size, the maximum_size argument indicates the maximum
number of bytes that are buffered to a destination that is temporarily unavailable.
The default is 64K. In the form formatted=format_mode, the format_mode
49
argument controls the amount of trace information that is displayed. Its value is an
unsigned integer interpreted as a bit mask. If a bit is set in the mask, then the
corresponding field appears in the formatted trace output. If no value is specified, all
fields except the high-order 16 bits of the process id are displayed. The thread id,
prefix, and message always appear in the formatted output. Other fields are
controlled by the following bit values:
v 1 hours, minutes, and seconds
v 2 date
v
v
v
v
v
v
3 milliseconds
4 microseconds
0x10 low-order 16 bits of process id
0x20 all bits of process id
0x40 use local time instead of GMT
0x100 traceID
The destination_type argument directs output to a general destination type. The

destination type must appear in uppercase and can be any one of the following:
v The FILE destination type refers to a local operating system file. The valid
destinations for this class are complete or relative pathnames of a file.
v The STREAM destination type refers to well-defined standard I/O streams. The
valid destinations are the standard output or standard error device (by default,
the server.out file in the servers working directory).
Note: On Windows, applications that do not have standard output or standard
error devices cannot use the STREAM destination type. Such applications
can use the environment variable CICS_TK_TRACE_REDIRECT to
redirect trace output. The variable accepts any valid trace output
destination.
v The AIX destination type refers to the local tracing and error logging facilities on
the AIX operating system. The valid destinations for this type are trace and
errlog.
v The NT destination type refers to a Windows event logging service. The valid
destination for this type is the Windows Event Log service (eventlog).
The destination argument can be one of the following:
v For the FILE destination type, a complete or relative pathname of a file. The
filename cannot include the special symbols : (colon) or = (equal sign). If the
specified name is a relative pathname, the file is stored relative to the current
working directory of the server. If the file already exists, tracing information is
appended to it. If the file does not exist, the file is created. By convention, trace
output files reside in the primary local directory where the server was started (for
example, /var/cics_servers/SSD/cics/sfs/sfs1).).
v For the STREAM destination type, the standard output or standard error devices
of the server.
v For the AIX destination type, the trace or errlog devices. The trace device
directs trace output to the AIX trace stream, and the errlog device directs trace
output to the AIX system error log.
v For the NT destination type, the eventlog Event Log service.
For example, the following trace output destination redirects unformatted event
output to a file named event.data:
event=[unformatted]FILE:event.data
50
You can list the trace destinations for all trace classes by using the tkadmin list
redirect command. The command syntax follows:
tkadmin list redirect -server server_name
For example, enter the following command to list the trace destinations of all trace
classes for a server:
%
tkadmin list redirect
entry:
event:
param:
audit: [formatted,unbuffered]STREAM:stderr
dump:
error: [formatted,unbuffered]STREAM:stderr
fatal: [formatted,unbuffered]STREAM:stderr
Modifying trace specifications

If you modify the trace mask while the server is running, the changes remain in
effect only while the server is running and revert to the default settings when the
server is stopped and restarted.
Note: Setting or modifying the trace specification overrides the value of the
CICS_TK_TRACE environment variable.
Modify a trace specification by using the tkadmin trace specification command. The
basic syntax is as follows:
tkadmin trace specification -server server_name specification
The following example sets the trace mask of the trpc component to trace entry and
exit of exported functions:
% tkadmin trace specification trpc=trace_entry
Redirecting trace output

If you redirect tracing while the server is running, the changes remain in effect only
while the server is running and revert to the default settings when the server is
stopped and restarted. Otherwise, the changes remain in effect when the server is
restarted.
Redirect the trace by using the tkadmin redirect trace command, as described in
Trace destinations on page 49.
Manipulating trace output

All trace output generated by a server is captured in a main memory ring buffer.
The ring buffer is finite in size (the default size is 64K) and can hold only a certain
number of the most recent trace output messages, and then the messages are
overwritten.
You can manually dump and format the contents of the ring buffer by using the
tkadmin dump ringbuffer command. You can also have the ring buffer dumped
automatically when a traced process encounters certain conditions. This is done by
setting CICS environment variables. For more information on manually and
automatically dumping the ring buffer, see Dumping the ring buffer on page 52.
You can also change the size of the ring buffer by using the tkadmin set ringbuffer
size command. See Setting the ring buffer size on page 53 for details.
51
When the ring buffer is dumped using the methods described in Dumping the ring
buffer, by default, a file named ToolkitTraceBuffer.pid is created, where pid is the
process identifier of the server. This file is dumped in binary format. You can
translate binary files into readable text by using the interpretTrace command
(available on all platforms) or WinTrace (on Windows). See Translating trace binary
files into readable text on page 54 for information on using the interpretTrace
command. See Manipulating trace output with WinTrace (Windows only) on page
56 for information on using WinTrace.
The default format of trace output is described in Format of trace output on page
54.
The CICS Toolkit Trace Facility contains the following commands for manipulating
trace output. These commands are available on all platforms:
v The indentTrace command indents trace output to make it more readable. See
Customizing trace output on page 56 for information on indenting trace output.
v The translateError command translates error and status codes into text
messages. See Translating error and status codes on page 56 for information
on error and status codes.
WinTrace, which is available on Windows only, contains all of the functionality
provided by these commands. For more information on using WinTrace, see
Manipulating trace output with WinTrace (Windows only) on page 56.
Dumping the ring buffer

You can manually dump the ring buffer using the tkadmin dump ringbuffer command
or you can set environment variables to cause an automatic dump of the ring buffer
under specific circumstances.
Manual ring buffer dumps

Use the tkadmin dump ringbuffer command to dump trace output from the ring
buffer. Trace output is sent to the file specified.
Note: Use the tkadmin dump ringbuffer command as a diagnostic tool. Using this
command during normal server operation can degrade performance.
The complete syntax follows:
tkadmin dump ringbuffer -server server_name file_name [-binary] [-overwrite]
Specify a filename for the file_name argument. By default, the file generated by this
command is a readable ASCII file. If the -binary option is used, the trace output is
in binary format. If the -overwrite option is used, the output file is overwritten rather
than extended. For example, enter the following command to dump the servers ring
buffer into a file named ringbuffer.out:
%
tkadmin dump ringbuffer ringbuffer.out
Automatic ring buffer dumps

There are four circumstances under which a ring buffer can be automatically
dumped: when a specific trace identifier is encountered, when the ring buffer
becomes full, when a process exits, and when a specific signal is received by a
process.
To trigger an automatic ring buffer dump when a specific trace identifier (ID) is
encountered in a trace event, you must identify the trace ID. To do this, set the
value of the CICS_TK_TRACE_BUFFER_DUMP_ON_UIDS environment variable to
52
the hexadecimal trace ID. You can identify multiple trace IDs for automatic dump by
setting the value of the environment variable to a comma-separated list of the
corresponding hexadecimal trace IDs as shown in the following example:
export CICS_TK_TRACE_BUFFER_DUMP_ON_UIDS 280c1825,280c1835,280c1845
To trigger a ring buffer dump when the buffer is full, set the
CICS_TK_TRACE_BUFFER_DUMP_WHEN_FULL environment variable as follows:
export CICS_TK_TRACE_BUFFER_DUMP_WHEN_FULL
The ring buffer is dumped before the buffer wraps, and begins to reuse segments.
To trigger a ring buffer dump when a process exits, set the
CICS_TK_TRACE_BUFFER_DUMP_ON_EXIT environment variable to a nonzero
numeric value.
To trigger a ring buffer dump when a specific signal is received, set the
CICS_TK_TRACE_BUFFER_DUMP_ON_SIGNAL environment variable to the
numeric value of that signal. For example, to cause an automatic dump when the
signal 31 is received, set the environment variable as follows:
export CICS_TK_TRACE_BUFFER_DUMP_ON_SIGNAL 31
When a ring buffer is automatically dumped by using any of these four methods, the
contents of the buffer are placed in the file ToolkitTraceBuffer.pid (where pid is the
process ID of the process that caused the automatic dump). You can change the
default name of the ring buffer output file by using the
CICS_TK_TRACE_FILE_FORMAT environment variable. This environment variable
takes a sprintf string (a string containing %d, where %d defines the position of the
pid within the string) as shown in the following example:
export CICS_TK_TRACE_FILE_FORMAT MyTraceBuffer.%d
Setting the ring buffer size

The size of a ring buffer is set when a server is initialized. By default, the ring buffer
is 65536 bytes (64 KB). You can resize the ring buffer in either of the following
ways:
v By setting the CICS_TK_TRACE_RING_SIZE environment variable. If you use
this environment variable, the change to the ring buffer size takes effect the next
time the server is started.
v By using the tkadmin set ringbuffer size command. If you use this command, the
change to the ring buffer size takes effect immediately.
For both the environment variable and the command, specify the size in bytes.
The initial number of segments in a ring buffer is fixed at eight. Each segment is
one-eighth of the total size of the ring buffer. You can increase the size of the ring
buffer (and thus the number of segments), but you cannot decrease the size below
the initial buffer size of 64 KB. The segment size is fixed at 8192 bytes. To make
the best use of the available space, the ring buffer size must be a multiple of the
segment size.
To display the current size of a ring buffer and its current segment size, use the
tkadmin show ringbuffer size command. The syntax is as follows:
tkadmin show ringbuffer size -server server_name
The following command displays the current ring buffers total size and its segment
size, in bytes, on the standard output stream:
53
% tkadmin show ringbuffer size

Present Ring Buffer Size: 65536
Present Ring Buffer Segment Size:
8192
To set the CICS_TK_TRACE_RING_SIZE variable in a Korn shell, specify the

appropriate ring buffer size (for example, 524288 to set the size to 512 KB) as
follows:
% export CICS_TK_TRACE_RING_SIZE 524288
To set the ring buffer size dynamically, use the tkadmin set ringbuffer size
command. The syntax is as follows:
tkadmin set ringbuffer size
-server server_name size
The command sets the ring buffer size and displays its current and new size, as
well as its segment size, on the standard output stream. The following example sets
the ring buffer size to 85536 bytes and displays the current and new sizes of the
ring buffer. Note that the resulting ring buffer size is 90112 (8192 * 11). If you
specify a size that is not a multiple of the segment size, the next multiple of the
segment size is used.
% tkadmin set ringbuffer size 85536
Present Ring Buffer Segment Size: 8192
Requested Ring Buffer Size: 85536
Resulting Ring Buffer Size: 90112
Translating trace binary files into readable text

CICS provides an interpreter command named interpretTrace to translate
ToolkitTraceBuffer.pid files into readable text format. The complete syntax follows:
interpretTrace [-rrep] [-mmode] [-spid] [-ffile] [] [files...]
Specify the process identifier of an ToolkitTraceBuffer.pid file for the pid argument,
a single filename for the file argument, or multiple filenames for the files argument.
Separate each filename with a space. Optionally, you can specify a 0 (zero) for the
mode argument to make output less verbose. See the reference page for the
interpretTrace command for more information.
For example, enter the following command to convert the file
ToolkitTraceBuffer.17123 to readable text and to send the output to the standard
output stream:
%
interpretTrace -s17123
The output from this command can be made more readable by using the
indentTrace command. See Customizing trace output on page 56 for more
information.
Format of trace output

Figure 6 on page 55 provides an example trace message in the default (verbose)
format. The thread identifier, process identifier, timestamp, trace identifier, trace
class (or subclass) code, and message body fields are labeled.
54
Thread ID
14
Process ID
Timestamp
Trace ID
Trace Class Code
35678 05/05/03-16:58:57.908844 502c5425 E Registering SFS interface

Message Body
Figure 6. Anatomy of a trace message
A description of each field follows:

v Thread identifierA system-dependent identifier of the thread in which the event
occurred.
v Process identifierA system-dependent identifier of the process in which the
event occurred.
v TimestampThe date and time at which the event occurred, in hours, minutes,
seconds, and microseconds. By default, the timestamp refers to the local time
zone.
v Trace identifierA unique hexadecimal identifier for the message. The trace
identifier is provided for customer support purposes or for use when error
message catalogs are not available.
v Trace Class CodeA one- or two-character abbreviation representing the class
(or subclass) of trace output. This can be one of the following:
> indicates a function entry
< indicates a function exit
<R indicates a function exit with a return value
A indicates an audit message
D indicates a state dump message
E indicates an event message
F indicates a fatal error message
P indicates a parameters message
T indicates a termination message
W indicates a nonfatal error (warning) message
v Message BodyA description of the event that generated the message. The
description can include event-specific data, such as the location of the source file
where the event occurred.
The following trace output (in the default format) shows example trace messages
for error (warning), event, fatal, entry, param, audit, and dump classes:
1
22753 96/01/01-08:17:51.003038 a0040437 W Unable to bind to
server /.:/cics/sfs/mysfs (ERZ-rpc-0214: not registered in
endpoint map)
1
22644 96/01/01-19:40:18.557693 50400415 E sfs: Hello from
SERVER
31
22644 96/01/01-19:43:43.724026 30349826 F Undo operation has
repeatedly failed
31
22644 96/01/01-19:43:43.744425 00000006 F /abc.com/project/
build/src/sfs/server/sfs.c 932
1
01324 96/01/02-00:27:18.905458 28040c00 > trpc_UseWkEndpoints
1
01324 96/01/02-00:27:18.905520 28040c23 P bindingVectorP:
360d30; count 0.
1
01324 96/01/02-00:27:18.905840 28040c01 <R trpc_UseWkEndpoints
trpc.c trpc -> 00000000
55
1
22719 96/01/03-19:05:45.755217 04800017 A
Wed Jan 3 19:05:45 1996
1
09515 96/01/04-12:35:41.987159 10043819 D
dump for thread id: 1
sfs: Initialized ...

threadTid state
Note that fatal (F) errors generate two messages. The body of the first message
describes the event; the body of the second message includes the name of the
source file in which the statement that generated the error appears and the line of
the file where the error occurred.
Customizing trace output

CICS provides the indentTrace command to accept translated trace output and
indent each nested function or event within a function to make it more readable.
indentTrace [-u] [file]
Specify the name of the file to be used as input for the file argument. Optionally,
you can specify the -u option to cause the output to be unbuffered. For example,
enter the following command to indent output of the ASCII file trace.out:
%
indentTrace trace.out
The following command uses the interpretTrace command and a | (pipe) to format
the binary file ToolkitTraceBuffer.17123, and send it through the indentTrace
command:
%
interpretTrace -s17123 | indentTrace
Translating error and status codes

CICS provides the translateError command to translate CICS or RPC error and
status codes into their associated messages. An error or status code can be
represented in the following forms in the CICS Toolkit:
v An CICS or RPC status string, such as ENC-enc-1025 or ERZ-rpc-0036
v A decimal number, such as 1907401729
v A hexadecimal number, such as 0x16c9a024
v A CICS or RPC C constant, such as TRAN_NOT_READY or rpc_s_comm_failure
translateError [codes...]
Specify one or more status codes to be translated for the codes argument.
Separate each code with a space. For example, the following command displays
the ENC-tra-1135 status string and its associated message, C constant, and
hexadecimal number:
%
translateError ENC-tra-1135
ENC-tra-1135: All acceptable applications refused to coordinate

[TRAN_ABORT_NO_SUITABLE_COORDINATOR] (0x7796846f)
Manipulating trace output with WinTrace (Windows only)

On Windows, you can use individual commands to translate trace output
(interpretTrace), format trace output (indentTrace), and translate error and status
codes (translateError ), or you can use WinTrace. WinTrace combines and extends
the functionality of the individual commands within a graphical user interface.
56
WinTrace does not provide functionality to manually or automatically dump the trace
ring buffer. You must still use the commands and environment variables described
in Dumping the ring buffer on page 52 to dump the ring buffer.
To open WinTrace, choose WinTrace from the Start menu or run the
\opt\ibm\cics\bin\winTrace.exe command. For more information on using
WinTrace, see the WinTrace online help.
Opening trace files

In WinTrace, binary and text trace files are opened in the same way. Perform the
following steps to open any trace file with WinTrace:
1. Choose the Open Trace File command from the File menu or choose the Open
button from the toolbar. The Open file window appears.
2. Specify the pathname of the binary file in the File Name field and choose the
OK button. A new window displays the contents of the file, converted into
readable text format.
Because WinTrace is fully integrated with the Windows environment, you can use
any of the standard methods of opening a file. For example, you can
v Drag and drop a file into a WinTrace window
v Associate a file extension with WinTrace so that when you double-click a file with
that extension, WinTrace is automatically started and the selected file is opened
v Start WinTrace from the command line and specify a file to open when the
program starts
Customizing trace output

You can use WinTrace to indent nested functions within trace output. Perform the
following steps to indent trace output:
1. Open a trace output file in WinTrace (see Translating trace binary files into
readable text on page 54).
2. Position your cursor on the trace output you want to indent and press the right
mouse button.
3. Choose the Indent+ command from the right mouse button menu. The trace
output is indented. You can increase the amount of indentation in increments by
choosing the Indent+ command again.
Note: To decrease or remove indentation, you can choose the Indentcommand from the right mouse button menu.
Other customization options are available with WinTrace. For example, you can
display messages for a specified thread or trace class, or you can specify colors for
different types of messages. You can also toggle display of line numbers and
verbose format. See the WinTrace online help for information about these features.
Translating error status codes

You can use one of the following methods in WinTrace to translate an error or
status code:
1. Choose the Translate Error button from the toolbar. The Translate Error dialog
box appears. Type the error or status code in the Error Text field and choose
the Translate button. A message box displays the translated message. Choose
the OK button to dismiss the message box.
57
2. Open a trace output file, select the error or status code on the trace output,
position your cursor on the selected text, press the right mouse button, and then
choose the Translate Error command. A message box displays the translated
message. Choose the OK button to dismiss the message box.
58
Chapter 8. Managing SFS files

SFS provides three types of files: entry-sequenced (also called sequential), relative,
and clustered files. Use the SFS commands and CICSsdt commands described in
this chapter to create, copy, allocate and reclaim space for, and display information
about SFS files. This chapter also describes the SFS import-export facility.
Creating SFS files

You can create SFS files with entry-sequenced (sequential), relative, or clustered
formats. These three formats differ in the organization of their records:
v Records in entry-sequenced, or sequential, files are organized by their entry
sequence numbers (ESNs), which describe the order in which the records were
inserted in the file.
v Records in relative files are organized by their relative slot numbers (RSNs),
which describe the position of each record in an array of record slots.
v Records in clustered files are organized in a tree structure based on the value of
the key field or fields of the primary index.
Figure 7 on page 60 shows sample records from each of the three SFS file types.
59
Figure 7. Sample records for SFS file types
v The MerchandiseOrders file is an entry-sequenced file. Each record represents

an order placed. The record is inserted into the file chronologically, as each order
is taken. The physical arrangement of records provided by entry-sequenced files
is optimal for applications needing chronological access to information.
v The Inventory file is a relative file that stores information about stock items for a
company. The records are organized by stock item number. The value of the
StockNum field contains the RSN for records in this file. Applications can directly
access inventory records using this number.
60
v The Accounts file is a clustered file. Its records are physically ordered according
to the value of the customerName and customerAddress fields.
Table 8 summarizes the differences between the three types of SFS files.
Table 8. Comparison of SFS file types
Characteristics
Entry-sequenced
Relative
Clustered
Primary index
Implicit: based on
entry sequence
number (ESN)
Explicit: based on
relative slot number
(RSN)
Explicit: specified
when the file is
created
Optimal type of
access
Chronological access, Direct access, by

by ESN
RSN
Access through
primary key value
Valid record types
Fixed or variable
length
Fixed length slots,

variable length
records
Fixed or variable
length
Maximum records per 236 - 10

file
232 - 10
264 - 10
Limitations on
updating records
New record cannot

exceed the size of
the original record
New record cannot

exceed the maximum
record size specified
when the file was
created
New record cannot

exceed the maximum
record size specified
when the file was
created
Capability to
automatically reuse
space from deleted
records
No (must reorganize
the file to reuse
space)
Yes
Yes
The following sections describe how to create each of the three SFS file types by
using CICSSDT commands. Files can also be created programmatically. See the
TXSeries for Multiplatforms Application Programming Guide.
General information
The file creation commands for all three SFS file types have several required and
optional arguments in common. For example, when you create any type of SFS file,
you must specify
v File, field, and index names. These include the name of the file, the names of the
fields that each record will contain, the name of the primary index, and, for
relative and clustered files, the name(s) of the field(s) on which the primary index
will be based.
v Field descriptions. The description includes the data type of each field, and, for
some types of fields, the size of the field.
When you create a file, you can optionally allocate space for it and limit the number
of records it can contain.
This section describes in detail how to specify this common information. The
information is not repeated in the discussion for each file creation command.
Specifying file, field, and index names

The names of files, fields, and indices can be any sequence of null-terminated
characters and must follow these rules:
v File names cannot contain the / (slash) character, and must be less than or equal
to 254 characters.
61
v Field and index names must be less than or equal to 32 characters.
Specifying field types and sizes

Each field of an SFS record has a type (specified with the field_type argument).
Some field types are fixed-lengthfor example, unsigned 32-bit integer fieldsand
some are variable-lengthfor example, variable-length byte array fields. When
specifying record fields, you must specify fixed-length fields before variable-length
fields. Table 9 lists valid field types. Some field types, indicated by Yes in the third
column, require that you specify a maximum size for the field (the field_size
argument).
Table 9. Valid SFS field types
62
Fixed-length data types
Value
Must specify maximum

field size
unsignedInt16
Unsigned 16-bit integer.
signedInt16
Signed 16-bit integer.
unsignedInt32
signedInt32
unsignedInt64
signedInt64
decimal
A decimal number. The field Yes

size can be from 1 byte to 18
bytes.
float
32-bit floating point number.
double
64-bit floating point number.
string
Array of 8-bit characters. The Yes

string must be
null-terminated. The length
(including the null terminator)
must be less than or equal to
the maximum field size.
Characters following the first
null character are ignored.
nlsString
Array of 8-bit characters. The Yes

string must be
null-terminated. Characters
following the first null
character are ignored. NLS
strings are ordered as
specified by the collating
language of the server.
byteArray
Array of unsigned 8-bit bytes. Yes
timestamp
An 8-byte field consisting of

two 4-byte unsigned integers.
The high-order word signifies
the number of seconds from
(00:00:00) January 1, 1970,
GMT. The low-order word
contains the number of
microseconds within the
second.
Variable-length data types
Value
Must specify maximum

field size
Table 9. Valid SFS field types (continued)

varLenByteArray
Array of unsigned 8-bit bytes Yes

with an unsigned 4-byte
length header. The length
header specifies the number
of bytes following the header;
it does not include the size of
the header itself.
shortVarLenByteArray
Array of unsigned 8-bit bytes Yes

with an unsigned 2-byte
length header. The length
header specifies the number
of bytes following the header;
it does not include the size of
the header itself.
Creating entry-sequenced files

The records in an SFS entry-sequenced file are stored in the order in which they
are inserted in the file; new records are always appended to the end of the file.
Entry-sequenced files are useful for keeping time-sequenced event records, such as
log files or audit trails.
The primary index of an entry-sequenced file is based on entry sequence numbers
(ESNs), which correspond to the order in which the records were inserted in the file.
The SFS generates ESNs when records are inserted; ESNs are not part of the
record itself. ESNs cannot be set or modified by administrators or applications.
The records in entry-sequenced files can have fixed- or variable-length fields. When
an existing record of variable length is updated, the size of the new record cannot
exceed the size required by the original record. For example, Figure 8 illustrates
updates to Record 3. The update can occupy space equal to or less than the initial
record allocation. However, any change that results in a larger record size is illegal.
Figure 8. Record updates for an entry-sequenced file
The space allocated to a record in an entry-sequenced file is not reclaimed

automatically when the record is deleted or when a record update makes the record
63
smaller. You can, however, reclaim space in an entry-sequenced file by using the
command. This command is described in Expanding and reorganizing files on
page 67.
You can create an entry-sequenced file using sfsadmin create sequentialfile,
referred in Chapter 13, The sfsadmin command, on page 137
You can create an entry-sequenced file using the create command of CICSSDT, as
shown in Using the CICSSDT command to create SFS files on page 65.
When you create an entry-sequenced file, you must specify the following:
v The name of the new file
v The number of fields per record and a description of each field
v The name of the primary index
v The name of the volume on which the file will be stored
Note that you cannot change any of these characteristics except the name of the
file after you have created it. See General information on page 61 for details on
specifying record fields.
Creating relative files

The records of a relative file are stored in an array of fixed-length slots, which are
identified by relative slot numbers (RSNs). A record can be inserted in the first free
slot in the file, in a certain slot in the file specified by the user (provided that the slot
is free at the time of insertion), or at the end of the file. Relative files are useful for
applications that access records directly by slot number.
The primary index of a relative file is based on the RSN, the number of the slot
occupied by the record. Unlike ESNs, the RSN is part of the record itself (it is the
value of the RSN field).
The records in a relative file are fixed-length slots, with variable-length records.
Each record can have fixed- or variable-length fields. When a record in a relative
file is updated, the new record can be any length, but it cannot exceed the
maximum record size specified when the file was created.
The disk space allocated to a record in a relative file is freed for use when the
record is deleted or when an update makes the record smaller. However, space is
not automatically reused. It can be reused when the SFS inserts a new record into
the empty slot.
You can create a relative file by using the commandsfsadmin create relativefile.
Refer to sectionChapter 13, The sfsadmin command, on page 137.
You can create a relative file using the create command of CICSSDT, as shown in
Using the CICSSDT command to create SFS files on page 65.
When you create a relative file, you must specify the following:
v The name of the primary index
v The name of the field that will contain the RSN
64
When you create a relative file, you must specify the name of the field that will
contain the RSN. This field must be of type unsignedInt32. RSN fields are sorted in
ascending order.
If you want to place a limit on how many records can be in the file in a relative file,
calculate the maximum to be the desired limit plus one.
Creating clustered files

A clustered file stores records in a tree structure. Clustered files are useful for
applications that need to access records based on the value of a specific field or
fields, and not on physical placement of the records. The primary index of a
clustered file is based on any field or combination of fields specified by the user
when the file is created. For example, the fields chosen for the primary index can
be fields most frequently accessed by an application.
The records in clustered files can have fixed- or variable-length fields. When a
record in a clustered file is updated, the new record can be any length, as long as it
does not exceed the maximum record size specified when the file was created. The
disk space allocated to a record is freed for use when the record is deleted or when
the record update makes the record smaller. The SFS automatically reclaims the
freed space.
You can create a clustered file by using the command,sfsadmin create
clusteredfile. Refer to section,Chapter 13, The sfsadmin command, on page 137.
You can create a clustered file by using the create command of CICSSDT, as
shown in Using the CICSSDT command to create SFS files.
When you create a clustered file, you must specify the following:
v The name of the primary index and its key field or fields.
By default, the SFS organizes keys in ascending order and allows duplicate keys in
the primary index of a clustered file. When you create a clustered file, you can
optionally
v Specify that the key values are sorted in descending order.
v Specify that key values in the index are unique.
Using the CICSSDT command to create SFS files

You can create an SFS file using the create command of CICSSDT.
All the file information is prompted for in turn. To aid usability and eliminate creation
errors, CICSSDT ensures that everything that is entered is valid, and defaults to
65
sensible values if nothing is entered. One exception is the record Field Name and
index Field Name that use an empty entry to indicate that no more fields exist. Also,
some fields might not be able to determine a default entry and reprompt for input
after displaying some help. If q! is entered at any prompt, the create is canceled.
The following example shows how to create a clustered SFS file named sfsfile on
SFS server /.:/cics/sfs/SFS1, with the key values sorted in ascending order:
cicssdt -s /.:/cics/sfs/SFS1 -c create sfsfile
[SFS Server Volume Name .....: sfs_SFS_SERV
[File Organisation [E/R/B] ..: B[treeClustered]
[Field 01: Name .............: f1
[Field 01: Type .............:
Error: Invalid field type. Type must be:
unsignedInt16, signedInt16, unsignedInt32,
signedInt32, unsignedInt64, signedInt64,
float, double, string, nlsString,
byteArray, varLenByteArray,
shortVarLenByteArray, timestamp or decimal.
[Field 01: Type .............: byteArray
[Field 01: Size .............: 10
[Field 02: Name .............: f2
[Field 02: Type .............: varLenByteArray
[Field 02: Size .............: 100
[Field 03: Name .............:
[Maximum Number Of Records ..: SFS_NATURAL_RECORD_LIMIT
[Primary Index Name .........: f1
[Is Index Unique ? [Y]/N ....: Y
[Index Field 01: Field Name .: f1
[Index Field 01: Ordering ...: a[scending]
[Index Field 02: Field Name .:
[Number Of Pages To Allocate : 1
For more information about using the CICSSDT command, see the TXSeries for
Multiplatforms Administration Reference.
Copying and renaming files

You can copy an SFS file to a new SFS file, or you can rename the file. Note that
you can remove the data from an SFS file and retain the format for reuse by using
the empty command of CICSSDT. See Emptying and deleting files on page 76 for
details on this command.
Copying a file
You can copy an SFS file by using the command. The complete syntax is
sfsadmin copy file -server server_name source_file target_file
[-targetvolume target_volume] [-indices number_of_indices
{{index_name [-itargetvolume index_target_volume]}...}]
When you copy an SFS file, you must specify the name of the file to be copied
(source_file) and the name of the new file (target_file). The file and all of its indices
are copied.
The following example copies the file MerchandiseOrders to Orders:
%
sfsadmin copy file MerchandiseOrders Orders
By default, this command copies the file and all of its indices to the volume on
which the original file resides.
66
You can optionally do the following:

v Copy the file to a different volume (the -targetvolume option).
v Copy only certain secondary indices of the original file (the -indices option). You
must specify the number of indices to be copied and their names. By default, the
indices are copied to the volume where the primary area of the target file resides.
You can use the -itargetvolume option to direct them to a different volume. If
you want to prevent any secondary indices from being copied to the target file,
specify -indices 0.
In the following example, the file MerchandiseOrders resides on the volume
sfsVol1. The command copies the file MerchandiseOrders to Orders and places
Orders on the volume sfsVol3.
%
sfsadmin copy file MerchandiseOrders Orders -targetvolume sfsVol3
The next command copies the file MerchandiseOrders to Orders. Only one
secondary index (itemIndex) is copied; the index is placed on the volume sfsVol4.
% sfsadmin copy file MerchandiseOrders Orders -indices 1 itemIndex
-itargetvolume sfsVol4
Renaming a file
You can rename an SFS file by using the sfsadmin rename file command. The file
itself is not moved; it remains on the same volume. The complete syntax is
sfsadmin rename file -server server_name file_name new_file_name
In the following example, the file Inventory is renamed Inv:

%
sfsadmin rename file Inventory Inv
Expanding and reorganizing files

Expanding a file allocates more disk space for it. SFS automatically expands the
disk space for a file as necessary. The disk space is increased in increments equal
to the chunk size you specified when you created the physical volume for the file.
(The chunk size is specified in pages.)
You might want to reserve a large amount of space for a file when it is initially
created in order to avoid the performance costs associated with incremental
expansions of the file. This can be desirable, for example, when you expect the file
to grow rapidly to a large size.
v You can explicitly allocate disk space for the primary area of a file when it is first
created by using the -preallocate option of the file creation command.
After a file is created, you can allocate additional disk space for the primary area of
a file by using the sfsadmin expand file command.
In both explicit and automatic allocation, the amount of disk space allocated might
not exactly equal the expansion request because SFS rounds expansion requests
up to the nearest convenient value.
Reorganizing a file reclaims space from deleted records in an entry-sequenced file.
You can reclaim space in an entry-sequenced file by using the sfsadmin reorganize
file command. (Space is reclaimed automatically for deleted records in clustered
and relative files.)
67
The following sections describe the sfsadmin expand file and sfsadmin reorganize
file commands.
Expanding a file
You can allocate additional disk space for the primary area of a file by using the
sfsadmin expand file command. When you expand a file, you must specify the
name of the file and the number of pages of disk space to allocate to the files
primary area. A page is 4096 bytes. The complete syntax of the sfsadmin expand
file command is
sfsadmin expand file -server server_name file_name number_of_pages
The following example allocates 500 additional pages to the file Inventory:
%
sfsadmin expand file Inventory 500
Reorganizing an entry-sequenced file

Space from deleted records in clustered and relative files is reused automatically.
However, space from deleted records in entry-sequenced files is not reused
automatically. You can use the sfsadmin reorganize file command to reclaim the
space. The complete syntax is
sfsadmin reorganize file -server server_name file_name [-indices]
When an entry-sequenced file is reorganized, active secondary indices are not

rebuilt but are instead marked as inactive. You must specify the -indices option to
rebuild active secondary indices.
The command in the following example reclaims space in the entry-sequenced file
MerchandiseOrders and rebuilds its active secondary indices:
%
sfsadmin reorganize file MerchandiseOrders -indices
Displaying file and transaction information

You might need information about files and transactions in an SFS server for
troubleshooting and monitoring purposes. For example, when an SFS server
performs abnormally, or a file or record becomes unavailable to clients, you might
need to obtain any or all of the following:
v A list of all files
v Detailed information about individual files
v A list of open file descriptors (OFDs)
v Detailed information about an individual OFD
v Information about the locks held by individual transactions
v Information about the locks held on a specific file
Listing files
For listing files using sfsadmin list files command, refer to section, Chapter 13,
The sfsadmin command, on page 137.
You can list the files managed by a server by using the list command of CICSSDT.
You can use the l option to get additional information for each file. If CICSSDT
cannot open a file to obtain this additional information, processing continues with
the next file. A search string can also be given to list specific files. If a search string
68
is used, CICSSDT looks for all the filenames that contain the string. No wild card
characters are used, so the search string is taken as entered.
The following example command gives extended information about files managed
by the server /.:/cics/sfs/mysfs, with names containing the string AC1cics:
cicssdt -s /.:/cics/sfs/mysfs -c list l AC1cics
File Name
==================
AC1cicsnlqfile
AC1cicsnrectsqfil
AC1cicsplqfile
AC1cicsrectsqfile
AC1cicstdqlgfile
Organisation
=====================
btreeClustered (KSDS)
Primary Index No. Records

=============== ===========
cicsnlqidx
(empty)
cicsnrectsqidx
(empty)
cicsplqidx
(empty)
cicsrectsqidx
(empty)
cicstdqlgidx
(empty)
Querying a file
To display information related to a file using the sfsadmin query file command,
refer to Chapter 13, The sfsadmin command, on page 137.
You can display detailed information about a specific file by using the info command
of CICSSDT.
This command displays status and storage information about a file, including
v The file name and type of file
v The name, data type, and size of each record field
v
v
v
v
The name and keys of the primary index

The names of secondary indices
The maximum and current number of records in the file
The active Open File Descriptors (OFDs) and locks that are held on the file. This
is particularly useful if you want to see whether a file is still in use or has
unresolved transactions using it.
This information is not transactionally consistent; that is, the data can reflect
incomplete transactions. For example, the number of records displayed can include
records that have been inserted but not yet committed.
The following example displays information about the clustered file
AREG2cicsrectsqfile. The files primary index orders the records by tsqkey.
*cicssdt -s SFSname -c i AREG2cicsrectsqfile
[Information For File: AREG2cicsrectsqfile
]
------------------------------------------------------------------------------[File Organisation
] btreeClustered (KSDS)
[Primary Index Name
] cicsrectsqidx (Unique index)
[Primary Index Field(s)
] tsqkey
[Secondary Index Names
] (None defined)
[Number Of Records In File ] 0
[Number Of Fields Per Record] 2
[Field 001: tsqkey
][byteArray
][Size:
11]
[Field 002: tsqdata
][varLenByteArray
][Size: 32768]
------------------------------------------------------------------------------[OFD: 0014702 Owner: (Not defined)
Access: Shared Mode
]
Type: Transactional
TID: 64356610 RPC Count: 00000003
69
Isolation: Cursor Stability

Op. Timeout: Infinity (Secs)
Open TID: 61145210
Idle Timeout: 300 (Secs)
Label: AREG20504081750
Open Time: Fri Apr 8 17:50:28 2005
-------------------------------------------------------------------------------
Listing open file descriptors

An SFS client must specify an open file descriptor (OFD) specification in order to
open a file. An OFD specification describes how a file is to be opened, the way in
which the file is to be used, and the extent to which other users can share data in
the file. SFS returns an OFD identification number that the server uses to identify
the OFD. There can be one or more OFDs open simultaneously on any one file.
You can display information about the OFDs managed by a server by using the
sfsadmin list ofds command. The complete syntax is
sfsadmin list ofds -server server_name [-brief]
The -brief option displays only the server identification number and file name for
each OFD. The following example displays information about all OFDs managed by
the server /.:/cics/sfs/mysfs. Note that the Inventory file is being accessed by
several OFDs.
%
sfsadmin list ofds -server /.:/cics/sfs/mysfs
Ofd id: 33
File name: Inventory
Owner: (null)
Open time: Mon May 12 11:12:04 1998
Transaction id: 0
Number of rpcs: 139
Access mode: shared access
Authority:
read file
inquire file
Consistency: non-transactional
Isolational level: non-tran accumulate
Operation timeout: 20
Auto close: no
Duplicate detection: no detection
Operational force: no
Label: (null)
Open transaction id: 40
Ofd idle timeout: 60
Ofd idle timeout policy: sfs_destroyOfdOnConflict
Ofd id: 38
Owner: (null)
Transaction id: 65717
Number of rpcs: 1
Authority:
insert file
inquire file
Consistency: transactional
Isolational level: serializability
Auto close: yes
Duplicate detection: current index
Operational force: yes
Label: (null)
70

Ofd idle timeout policy: sfs_preserveOfdOnConflict
Ofd id: 39
File name: Accounts
Owner: (null)
Number of rpcs: 35
Access mode: exclusive access
Authority:
read file
insert file
update file
delete file
inquire file
exclusive file
administer file
Isolational level: cursor stability
Auto close: no
Label: (null)
The following list explains the elements in the output of the sfsadmin list ofds
command:
v ofd id is the identification number used by the server for the OFD.
v File name is the name of the SFS file.
v Owner indicates the owner of the file.
v Open time indicates the time that the file was opened.
v Transaction id refers to the identification number of the transaction associated
with the OFD, if the OFD is transactional. If the OFD is nontransactional, this
identification number is zero.
v Number of rpcs refers to the number of remote procedure calls (RPCs)
completed using this OFD.
v Access mode can be either shared or exclusive. An access mode determines
whether other applications can simultaneously access a file. A shared access
mode allows more than one application to obtain access to a file at the same
time. An exclusive access mode allows only one application to obtain access to a
file at a time.
v Authority lists the actions that can be performed using this OFD. An authority is
a permission to perform an operation on a file. For example, a client might have
permission to perform read and insert operations.
v Consistency refers to the type of consistency for the OFD.
v Isolation level refers to the extent to which data being accessed by the OFD is
protected from concurrent access by other users. An isolation level is the degree
to which operations on a file are isolated from other operations on the same file.
The isolation level determines the locking policy used.
v Operation timeout refers to the maximum time, in seconds, that an operation
using this OFD takes to complete before timing out.
71
v Auto close refers to whether a transactional OFD is automatically closed when

the transaction is resolved. If the OFD is nontransactional, this field is no (that
is, nontransactional OFDs must be closed manually).
v Duplicate detection specifies the degree of duplication detection performed by
the server on a unique index.
v Operational force applies only to nontransactional OFDs and refers to whether
or not the server forces the result of an operation to be permanent after each
operation.
v Label is the user-defined string for the OFD.
v Open transaction id is the identification number of the transaction that holds the
open access mode lock (shared/exclusive).
v Ofd idle timeout is the time, in seconds, that an OFD can be idle while waiting
for an SFS call. After this time period elapses, if an operation using another OFD
requests a lock held by the idle OFD, any transaction associated with the idle
OFD is aborted, the OFD is closed, and the lock is released.
v Ofd idle timeout policy specifies the actions to be taken when the OFD idle
timeout expires.
The sfs_destroyOfdOnConflict policy specifies that the OFD is destroyed and
all transactions associated with it are aborted when these two conditions
occur: the idle timeout has expired and a transaction associated with a
different OFD tries to access its locked records. (This is the default policy.)
The sfs_preserveOfdOnConflict policy specifies that after the idle timeout
expires, the transaction associated with a locked record is aborted but an
attempt is made to preserve the OFD if a transaction associated with a
different OFD tries to access a locked record. For example, if (after the
expiration of the idle timeout) a transaction associated with an OFD holds a
lock on a record and another transaction attempts to get a conflicting lock on
that record, the transaction holding the lock is aborted but the OFD is
preserved and can be reused. However, if (after the expiration of the idle
timeout) the transaction associated with an OFD holds the lock on an entire
file and another transaction attempts to open that file, the transaction holding
the lock is aborted and the associated OFD is destroyed.
Querying an open file descriptor

You can display information about an individual open file descriptor (OFD) by using
the sfsadmin query ofd command. The complete syntax is
sfsadmin query ofd -server server_name server_ofd_number
The server_ofd_number argument specifies the server identification number of the

OFD about which information is requested. For example, the following command
displays information about OFD 33 managed by the server /.:/cics/sfs/mysfs:
%
sfsadmin query ofd -server /.:/cics/sfs/mysfs 33
Ofd id: 33
Owner: (null)
Transaction id: 0
Number of rpcs: 139
Authority:
read file
inquire file
72
Auto close: no
Label: (null)
The elements in the output of the sfsadmin query ofd command are the same as
those of the sfsadmin list ofds command, described in Listing open file descriptors
on page 70.
Displaying transaction information

To help diagnose abnormal server behavior, you might want to list all OFDs and
associated transactions managed by the server and then list the locks held by one
or more transactions. The sfsadmin list ofds command lists OFDs and their
associated transactions. The sfsadmin query tranlock command lists the locks held
by a specified transaction.
The syntax of the sfsadmin query tranlock command is
sfsadmin query tranlock -server server_name tid
You must specify the transaction identification number (the tid argument). In this
example, the sfsadmin list ofds command is used to list all OFDs managed in the
server. The output shows that the Accounts file is being accessed using OFD 41
and that the file is opened in exclusive access mode using transaction 131275.
%
sfsadmin list ofds
Ofd id: 41
File name: Accounts
Owner: (null)
Transaction id: 0
Number of rpcs: 1
Authority:
insert file
inquire file
exclusive file
Auto close: no
Label: (null)
The output from the sfsadmin list ofds command indicates that transaction 131275
holds one locka read lock on the file.
%
sfsadmin query tranlock 131275
Lock 1:
Lock mode: read lock
File name: Accounts.5
Index name: (null)
Key value:
6169 725f 7265 732e 6669 6c65
Accounts
73
The following list explains the elements in the output of the sfsadmin query tranlock
command:
v Lock mode is the type of lock that the transaction holdsfor example, read lock
or write lock.
v File name is the file on which the lock is placed. If the lock is a file lock, the file
name might be followed by a period and an integer. The integer represents a file
lock space. Multiple locks on the same file do not conflict as long as the locks
are in different lock spaces as indicated by different integers in the file name
extension.
v Index name is the name of the index if this is a record-level lock and null if this is
a file-level lock.
v Key value is the value that is locked, represented in raw hexadecimal and in
ASCII.
In the following example, transaction 131319 holds five locks. Note that locks 2 and
4 are record-level locks. The output shows the name of the index (stocknumIndex)
and the value that is locked. In this case, the value does not fall within the range of
printable ASCII characters. Since the characters cannot be printed, they are
displayed as a series of dots.
%
Lock 1:
Lock mode: intention write lock
File name: Inventory.3
Index name: (null)
Key value:
656d 706c 6f79 6565 2e66 696c 65
Inventory
Lock 2:
Lock mode: write lock
Index name: stocknumIndex
Key value:
0000 0002 0000 0002
........
Lock 3:
Lock mode: intention read lock
Index name: (null)
Key value:
656d 706c 6f79 6565 2e66 696c 65
Inventory
Lock 4:
Index name: stocknumIndex
Key value:
0000 0001 0000 0001
........
Lock 5:
Index name: (null)
Key value:
6169 725f 7265 732e 6669 6c65
Accounts
Displaying file locks

You can display information about the locks held on a file by using the sfsadmin
query filelock command. This command displays all file-level and record-level locks
held by each OFD open on the file.
In the following example, several OFDs are accessing the file Inventory in shared
mode. The output shows the number and type of locks held by each OFD.
%
74
sfsadmin query filelock Inventory
Lockers of file: Inventory

ofd id: 1
transaction id: 18
openTid:
14
open lock mode: shared access
file locks:
Lock 1:
lock mode:
intention read lock
consistency: transactional
transaction id: 18
record locks:
lock 1:
lock mode:
read lock
index:
primary
transaction id: 18
key value:
3030 3035
ofd id: 2
transaction id: 0
openTid: 39
file locks:
lock 1:
lock mode:
read lock
consistency: nontransactional
transaction id: 39
record locks:
No locks
ofd id: 3
transaction id: 0
openTid: 57
file locks:
lock 1:
lock mode:
intention read lock
transaction id: 57
record locks:
lock 1:
lock mode:
read lock
index:
primary
transaction id: 57
key value:
3030 3034
0005
0004
The following list explains the elements in the output of the sfsadmin query filelock
command:
v Ofd id is the identification number used by the server for the OFD.
with the OFD, if the OFD is transactional. If it is nontransactional, this
v OpenTid is the identification number of the transaction that holds the open access
mode lock (shared/exclusive).
v Open lock mode can be either shared or exclusive. A shared access mode allows
more than one application to obtain access to a file at the same time. An
exclusive access mode allows only one application to obtain access to a file at a
time.
v For each file lock, the output lists the lock by number (beginning with 1), and
provides the following information. If there are no file locks, the output indicates
no locks.
75
Lock mode is the type of lock that the transaction holdsfor example, read
lock or write lock.
Consistency refers to the type of consistency for the OFD.
Transaction id refers to the identification number of the transaction against
which the lock is held.
v For each record lock, the output lists the lock by number (beginning with 1), and
provides the following information. If there are no record locks, the output
indicates no locks.
lock or write lock.
Index is the name of the index used to locate the record. The value for this
field is either primary or the name of the secondary index.
Key value is the value that is locked, represented in raw hexadecimal and in
ASCII.
Forcing files to close

A file can become unavailable if it is not appropriately closed. For instance, if a
client of an SFS server terminates abnormally, files that were exclusively opened by
the client may remain open, preventing access by other users. You can use the
sfsadmin list ofds command to determine currently open OFDs for a server. Then,
you can force an OFD to close so that the file opened with that OFD can be
accessed by others.
When an OFD is forced to close, any in-progress transaction using that OFD is
aborted. The client application owning the transaction receives a Transaction
Aborted error on the next operation using that OFD, and any further attempts to
use that OFD generate an OFD Invalid error.
Closing a file OFD

The sfsadmin terminate ofd command forces an OFD to close. The command
requires that you specify the identification number of the OFD to be terminated. The
complete syntax is
sfsadmin terminate ofd -server server_name server_ofd_number
The following example forces OFD 43 to close:

%
sfsadmin terminate ofd 43
Emptying and deleting files

If you no longer need the data in a file, you can either remove its contents (leaving
its record format intact) or remove the entire file. For example, if you have an SFS
file that periodically exceeds its record limit, you might want to write out or back up
the disk and retain the format for new data collection. However, after you remove
the contents of a file, you cannot restore the file.
Emptying a file
To remove the contents of a file but retain its format by using the sfsadmin empty
file command, refer to Chapter 13, The sfsadmin command, on page 137.
76
You can remove the contents of a file but retain its format by using the empty
command of CICSSDT. All disk space associated with the file remains allocated,
and the file can be used to enter new records of the same format.
CICSSDT provides two types of record emptying; an exclusive empty and a shared
empty. An exclusive empty attempts to get exclusive access to the file to issue an
empty call. If a shared empty is requested, CICSSDT deletes as many records as it
can, leaving those that are locked. The exclusive empty is recommended because it
guarantees an empty file.
The following example removes the contents from the file Accounts managed by
the server /.:/cics/sfs/mysfs, but retains its indices and structure:
cicssdt -s /.:/cics/sfs/mysfs -c empty Accounts
[Exclusive Empty ? [Y]/N ....: Y
[Empty File "Accounts" ? Y/[N] y
Deleting a file
To delete a file using the sfsadmin destroy file command, refer to Chapter 13,
The sfsadmin command, on page 137.
You can delete a file by using the delete command of CICSSFS. All disk space
associated with the file and its indices is automatically deallocated.
The following example deletes the file Inventory managed by the server
/.:/cics/sfs/mysfs:
cicssdt -s /.:/cics/sfs/mysfs -c delete Inventory
[Delete File "Inventory" ? Y/[N] y
This command times out and fails if the file is still in use.
|
Importing and exporting files
|
|
|
You can use the SFS Import/Export facility to export an SFS file from SFS to a
storage device, import a file from a storage device to SFS, and display information
about an exported file. You can perform the following tasks:
v Store individual SFS files on a file system, disk, or tape device and retrieve them.
v Load data from an external file (for example, an Indexed Sequential Access
Method (ISAM) file) that has been formatted.
v Transfer individual SFS files from one SFS server to another.
|
|
This section describes the sfsadmin import file, sfsadmin export file, and
sfsadmin query export commands.
|
|
|
|
|
|
|
Importing SFS files

The sfsadmin import file command loads into SFS the contents and structure of a
file from a storage device (a file system file, a raw disk partition, or a nonrewinding
77
|
|
tape drive) or from the standard input stream (stdin). The source file to be imported
can be a previously exported SFS file, or it can be a non-SFS file.
|
|
|
|
|
|
The complete syntax for the command is
|
|
|
|
|
When a file is imported, the source argument is the name of the SFS file to be
imported. The-target option is used to name the new file (the name is the same as
source unless you specify otherwise). A source file can be the source of more than
one import operation as long as the target name is different for each import
operation.
|
|
SFS assumes that you are importing from a file system unless you specify a
different device type (the -devicetype option).
|
|
|
|
In the simplest case, you specify only the name of the source file to be imported.
The following example imports the previously exported Inventory file from a file
system to SFS. The name of the resulting SFS file is the same (Inventory):
The following example shows the same file being imported to a different server
|
|
|
(/.:/branch1/server/sfs2):
|
|
|
|
|
|
|
|
|
|
By default, the following actions occur during an import:
|
|
|
|
|
|
|
|
|
You can optionally do the following when importing a file:

v Name specific indices to be copied (or indicate that no indices are to be copied)
by using the -indices option. Any inactive indices must be reconstructed after the
import.
v Specify a larger or smaller cache size to be used (the -cachesize option).
v Specify a larger or smaller checkpoint size to be used (the -checkpointsize
option).
v Indicate that relative files are to be compressed to preserve space (the -pack
option).
|
|
The -cachesize, -checkpointsize, and -pack options are discussed in Improving

import/export performance on page 87.
sfsadmin import file -server server_name [device type {tape|file|disk}]

source [-targettarget] [-targetvolumetarget_volume][-checkpointsize
checkpoint_size][-cachesizecache_size][-continue {resume | force | restart}]
[-pack][nodialog][-indicesnumber_of_indices {{index_name
[-itargetvolumeindex_target_volume]}...}]
sfsadmin import file Inventory
% sfsadmin import file -server /.:/branch1/server/sfs2

Inventory -targetvolume sfs2Vol
v A read lock is placed on the entire source file so that the source and target will
be identical.
v The file is copied using a 1-MB cache.
v A checkpoint file is created with the name target.IE.IMP on the same server as
the target. A checkpoint file is a temporary SFS file created for recovering from
failures. Checkpoints are taken after every 1 MB of data is copied.
v All indices are automatically copied.
v If the target for the new file becomes full, you are prompted for a location to
place the rest of the file.
78
Description of import arguments
|
|
|
|
-server server_name
Specifies the name of the file server. If the -server option is not specified, the
default is the server defined by the environment variable
CICS_TK_SFS_SERVER.
|
|
|
|
[-devicetype {tape | file | disk}]

Specifies the type of device from which the source is being imported. The
device can be file, disk, or tape, where file is a file system, disk is a raw disk
partition, and tape is a non-rewinding tape drive. The default is file.
|
|
|
|
|
|
|
source
Specifies the name of the device to be imported to an SFS file. For file
systems, source is the name of the file. For disks, source is the name of the
raw disk partition. For tapes, source is a non-rewinding tape drive. The
argument source can also be stdin, in which case the -devicetype option is
ignored and input is read from standard input. A source file can be the source of
more than one import operation as long as the target name is different for ea
|
|
|
|
[-target target]
Specifies the name of the SFS file to be created. For file devices, the default is
source without any pathname; for other devices, the target argument must be
specified.
|
|
|
|
[-targetvolume target_volume]
Specifies the name of the volume on which the SFS file and the primary index
are to be placed. The default is the volume that contained the SFS file when it
was originally exported.
|
|
|
|
[-checkpointsize checkpoint_size]
Specifies the number of bytes between updates of the checkpoint file created
by the SFS during the import. If the value of the -checkpointsize option is 0, no
checkpoints are made. The default is one megabyte.
|
|
|
|
[-cachesize cache_size]
Specifies the size of cache in pages. The default is 256 pages (1 megabyte
when the page size is the usual 4K). If the value of the -cachesize option is 0,
no caching is done.
|
|
|
|
|
|
|
|
|
[-continue {resume | force | restart}]

Specifies the action to be taken when resuming an interrupted import. If the
value is resume, the SFS continues the import from the last checkpoint as long
as target has not been modified between the failure of the import and its
continuation. If the value is force, the SFS continues the import from the last
checkpoint even if target has been modified. If the value is restart, the SFS
starts a new import from the beginning of target. This option has no effect if no
checkpoints have been made. By default, a renewed import of the same target
file will fail.
|
|
|
|
|
[-pack]
Specifies that records of relative SFS files be inserted consecutively without
skipping slots. RSN fields are changed accordingly. This option is ignored if
target is not a relative SFS file or if the source to be imported does not contain
RSNs.
|
|
|
|
[-nodialog]
Specifies that no prompts be displayed for the name of another device when
the current device has been completely read; instead, the SFS displays a
message indicating that the device has been read.
79
|
|
|
|
|
|
|
|
|
[-indices number_of_indices {{index_name [-itargetvolume

index_target_volume]}...}]
Specifies the number and names of the secondary indices to be copied to the
new SFS file. (By default, all indices are automatically copied.) Specify the
number of indices to be copied as number_of_indices and each name as
index_name. If the value of number_of_indices is 0, no secondary indices are
copied. By default, secondary indices are copied to the volume on which the
primary index is stored. You can optionally specify a different volume to store
the indices using the -itargetvolume option.
|
|
|
The following command reads the exported file inventory and writes it to an SFS file
named Inventory:
|
|
The -cachesize, -checkpointsize, and -pack options are discussed in Improving

import/export performance on page 87.
sfsadmin import file Inventory
Exporting SFS files
|
|
|
|
The sfsadmin export file command writes the contents and structure of the
specified SFS file to a storage device (a file system file, a raw disk partition, or a
nonrewinding tape drive) or to the standard output stream (stdout). The source file
is exported in SFS record format.
|
|
|
|
|
The complete syntax for this command is
|
|
|
|
When exporting a file, use the source argument for the name of the SFS file to be
exported. The -target option refers to the name of the new file (it is the same as
source unless you specify otherwise). A source file can be the source of only one
export operation at a time.
|
|
SFS assumes that you are exporting to a file system unless you specify a different
device (tape or disk) or stdout.
|
|
|
|
|
|
|
|
|
By default, the following actions occur during an export:

v A read lock is placed on the entire source file so that the source and target will
be identical.
v The file is copied using a 1-MB cache.
v A checkpoint file is created with the name source.IE.EXP on the same server as
the source. A checkpoint file is a temporary SFS file created for recovering from
failures. Checkpoints are taken after every 1 MB of data is copied.
v If the target for the exported file becomes full, you are prompted for a location to
place the rest of the file.
|
|
|
|
|
|
You can optionally do the following when exporting a file:

v Specify that the file is exported in segments larger than 1 MB, or that it is not
segmented at all (the -segmentsize option)
v Allow modifications to the source file while the export is in progress, controlling
consistency or not (the -locktype option)
v Specify a larger or smaller cache size to be used (the -cachesize option)
sfsadmin export file -serverserver_name source[-devicetype {tape | file | disk}]

[-targettarget][-checkpointsizecheckpoint_size][-segmentsizesegment_size]
[-cachesizecache_size][-locktype{filelock | recordlock | nolock}]
[-continue{resume| force | restart}][-norsn][-nodialog]
80
|
|
|
v Specify a larger or smaller checkpoint size to be used (the -checkpointsize

option)
v Prevent RSNs from being written to relative files (the -norsn option)
|
|
|
The -locktype option is discussed in Allowing file modification during exports on

page 86. The -cachesize, -checkpointsize, and -norsn options are discussed in
Improving import/export performance on page 87.
|
|
|
|
In the simplest case, you can specify only the name of the source file to be
exported. For example, the following example exports the file Inventory to the
users current directory.
Description of export arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
|
source
Specifies the name of the SFS file to be exported. A source file can be the
source of only one export operation at a time.
|
|
|
|
[-devicetype {tape |file |disk}]

Specifies the type of device to which the SFS file is being exported. The device
can be file, disk, or tape, where file is a file system, disk is a raw disk partition,
and tape is a non-rewinding tape drive. The default is file.
|
|
|
|
|
|
|
[-target target]
Specifies the name of the device to which the file is being exported. For file
systems, target is the name of the file. For disks, target is the name of the raw
disk partition. For tapes, target is the name of the tape drive. The argument
target can also be stdout, in which case -devicetype is ignored and input is read
from standard output. The default target for file devices is source; there is no
default target for disk and tape devices.
|
|
|
|
|
[-checkpointsize checkpoint_size]
Specifies the number of bytes between updates of the checkpoint file created
by the SFS during export. If checkpoint_size is 0, no checkpoints are made. For
tapes, checkpoint_size must either be segment_size or 0. The default is 1
megabyte.
|
|
|
|
|
|
|
|
|
|
[-segmentsize segment_size]
Specifies the number of bytes in the segments to be exported to file or tape
devices. A segment is a single file created by the SFS export facility on a file
system device. On tape drives, a segment is a portion of tape between two
consecutive filemarkers. (This option does not apply to disk device or the stdout
target. Disks and stdout cannot be segmented.) The size of the segment must
be at least 4 kilobytes. A segment_size of 0 means that the segment size is
equivalent to the size of the file or tape device. When the device is full, the SFS
prompts for the name of another device, unless the -nodialog option is
specified. The default is 1 megabyte.
|
|
|
|
[-cachesize cache_size]
Specifies the size of cache in pages. The default is 256 pages (1 megabyte
when the page size is the usual 4K). If the value of the -cachesize option is 0,
no caching is done.
sfsadmin export file Inventory
81
|
|
|
|
|
|
|
[-locktype {filelock | recordlock | nolock}]

Specifies the type of lock placed on the export file. The default is filelock. The
SFS places a read lock on the entire source file so that the source and target
will be identical. If the value is recordlock, the SFS places a temporary read
lock on each record as it is exported, allowing other records to be modified
during the export. If the value is nolock, the SFS places no locks on the file.
This may allow uncommitted data to be exported.
|
|
|
|
|
|
|
|
|
[-continue {resume | force | restart}]

Specifies the action to be taken when resuming an interrupted export. If the
value is resume, the SFS continues the export from the last checkpoint as long
as source has not been modified between the failure and the continuation of the
export. If the value is force, the SFS continues the export from the last
checkpoint even if source has been modified. If the value is restart, the SFS
starts a new export from the beginning of source. This option has no effect if no
checkpoints have been made. By default, if an export is interrupted, a renewed
export of the same source file will fail.
|
|
|
|
[-norsn]
Specifies that no relative slot numbers (RSNs) be written to the exported file,
although the RSN field is retained in the record. This option is ignored if source
is not a relative SFS file.
|
|
|
|
[-nodialog]
Specifies that no prompts be displayed for the name of another target when the
current target is full; instead, the SFS displays a message indicating that the
target is full.
|
|
|
The -locktype option is discussed in Allowing file modification during exports on

page 86. The -cachesize, -checkpointsize, and -norsn options are discussed in
Improving import/export performance on page 87.
|
|
|
|
In the simplest case, you can specify only the name of the source file to be
exported. For example, the following example exports the file Inventory to the
users current directory.
The Table 10 shows the status codes for file import and export and their description.
Table 10. Status code for file import and export
Status code
Description
|
|
|
SFS_IE_BADLY_DELIMITED_BUFFER
Initial and final buffer

length delimiters do
not match
|
|
|
|
SFS_IE_CHKPT_FILENAME_CONFLICT
Checkpoint file by
the same name
exists for a different
SFS file
|
|
SFS_IE_DEVICE_ERROR
A device error has

been encountered.
|
|
|
SFS_IE_END_OF_MEDIA_ON_READ
Next segment to
read was not found
on the media.
SFS_IE_END_OF_MEDIA_ON_WRITE
The media is full.
|
|
SFS_IE_ERROR_IN_TRAILER
Unable to read the

trailer section
82
sfsadmin export file Inventory
Table 10. Status code for file import and export (continued)
Status code
Description
|
|
|
SFS_IE_ERROR_LOG_ERROR
Error in processing
the error log
operations
|
|
|
SFS_IE_ERROR_LOG_FILENAME_CONFLICT
Error log by the

same name exists for
a different SFS file.
|
|
SFS_IE_ERROR_OBTAINING_EXPORT_ID
Unable to obtain an
export ID
|
|
|
SFS_IE_FILE_MODIFIED
Force needed to
continue the import
or export function
|
|
|
SFS_IE_IMPROPER_EXPORT_FORMAT
Section of export set

is unknown or not in
correct order
|
|
SFS_IE_INVALID_SEGMENT_HEADER
Invalid field or value

in segment header
|
|
SFS_IE_MEDIA_TOO_SMALL_FOR_ METADATA
Need a larger media

to store metadata
|
|
|
|
SFS_IE_OPERATION_IN_PROGRESS
Restart, resume, or
force needed to
continue the import
or export
|
|
|
SFS_IE_TRAILER_NOT_EXPORTED
Cannot export trailer

information because
the media is full
|
|
SFS_IE_UNABLE_TO_ADD_ SECONDARY_INDEX
Cannot add a
secondary index
|
|
SFS_IE_UNABLE_TO_CLOSE_CHKPT_FILE
Cannot close the

checkpoint file
|
|
SFS_IE_UNABLE_TO_CLOSE_DEVICE
Cannot close the

device or file
|
|
SFS_IE_UNABLE_TO_CLOSE_FILE
Cannot close the

SFS file
|
|
|
SFS_IE_UNABLE_TO_COMPARE_KEYS
Cannot compare
keys from the SFS
file
|
|
SFS_IE_UNABLE_TO_CREATE_CHKPT_FILE
Cannot create
checkpoint file
|
|
SFS_IE_UNABLE_TO_CREATE_FILE
Cannot create the

SFS file
|
|
SFS_IE_UNABLE_TO_DELETE_CHKPT
Cannot delete
checkpoints
|
|
SFS_IE_UNABLE_TO_DESTROY_CHKPT_FILE
Cannot destroy the

checkpoint file
|
|
SFS_IE_UNABLE_TO_DESTROY_FILE
Cannot destroy the

SFS file
|
|
|
SFS_IE_UNABLE_TO_DETERMINE_ DATA_REP
Cannot determine
the byte order of
integers
83
Status code
Description
|
|
SFS_IE_UNABLE_TO_EXTRACT_KEY
Cannot extract a key

from the SFS file
|
|
|
SFS_IE_UNABLE_TO_FIND_RSN_FIELD
Cannot find the offset

within a record to the
RSN field
|
|
SFS_IE_UNABLE_TO_GET_ATTRIBUTES
Cannot get the SFS

file attributes
|
|
SFS_IE_UNABLE_TO_GET_ESN
Cannot get the ESN

for a record
|
|
SFS_IE_UNABLE_TO_GET_INFO
Cannot get the SFS

file information
|
|
SFS_IE_UNABLE_TO_GET_RSN
Cannot get the RSN

for a record
|
|
|
SFS_IE_UNABLE_TO_GET_ SECONDARY_INDEX_INFO
Cannot get the

secondary index
information
|
|
SFS_IE_UNABLE_TO_GET_SFS_DUPLICATE
Call to
sfs_IsDuplicate failed
|
|
SFS_IE_UNABLE_TO_INSERT_CHKPT
Cannot insert
checkpoints
|
|
SFS_IE_UNABLE_TO_INSERT_INTO_FILE
Cannot insert records

into the SFS file
|
|
SFS_IE_UNABLE_TO_LOCK_FILE
Cannot lock the SFS

file
|
|
SFS_IE_UNABLE_TO_OPEN_CHKPT_FILE
Cannot open the

checkpoint file
|
|
SFS_IE_UNABLE_TO_OPEN_DEVICE
Cannot open the

device or file
|
|
SFS_IE_UNABLE_TO_OPEN_FILE
Cannot open the

SFS file
|
|
SFS_IE_UNABLE_TO_POSITION_DEVICE
Cannot find the

device position
|
|
SFS_IE_UNABLE_TO_READ_CHKPT_FILE
Cannot read
checkpoints
|
|
SFS_IE_UNABLE_TO_READ_FILE
Cannot read records

from the SFS file
|
|
SFS_IE_UNABLE_TO_SET_ATTRIBUTE
Cannot set the SFS

file attributes
|
|
SFS_IE_UNABLE_TO_SET_RANGE_ON_CHKPT_FILE
Cannot set the range

on the checkpoint file
|
|
SFS_IE_UNABLE_TO_SET_RANGE_ON_SFS_FILE

on the SFS file
|
|
SFS_IE_UNABLE_TO_UPDATE_CHKPT
Cannot update
checkpoints
|
|
SFS_IE_UNABLE_TO_SET_RANGE_ON_SFS_FILE

on the SFS file
84
Status code
Description
|
|
|
|
SFS_IE_VERSION_UNKNOWN
Version number in
export set is not
recognized
Segmenting a file during export
|
|
|
|
|
Because SFS files are often quite large, SFS divides them into a series of 1-MB
segments on the target device to make them more manageable. A segment is a
single file created by the SFS export facility on a file system device. On tape drives,
a segment is a portion of tape between two consecutive file markers. Disks and
stdout cannot be segmented.
|
|
|
|
|
|
|
|
Each exported file name consists of the target file name with an appended 8-digit
positive number. For example, the exported file in the previous example might
appear as three 1-MB files named Inventory.00000000, Inventory.00000001, and
Inventory.00000002. The number increases for each successive file. Breaking the
file into segments can be useful if you have limited space on your storage device.
For instance, if the file system to which you are exporting is not sufficiently large to
store the entire file at once, you can move an exported segment from the file
system to tape in stages as new segments are being exported.
|
|
|
|
|
Although the 8-digit file extension is a part of the file system name (and therefore
used with operating system commands), it is not part of the SFS file name. Do not
specify the appended number with subsequent sfsadmin commands. For example,
to query the exported file in the above example, specify sfsadmin query export
Inventory.
|
|
|
|
|
|
If the file to be exported is not large and you have no need to divide the exported
file into segments, consider making the segment size equivalent to the size of the
file or tape device. (Disk segments are always the same size as the disk.) The
following example illustrates how to do this by specifying a segment size of 0
(zero):
|
|
|
|
|
|
You might want to increase segment size in order to increase the speed of the
export. For example, suppose you are exporting a 50-MB file. By default, the file will
be divided into 1-MB segments. In this case, you might want to increase the
segment size to 10 MBs to save export time. The following example initiates such
an export:
|
|
|
|
|
|
|
|
|
sfsadmin export file Inventory -segmentsize 0
sfsadmin export file Inventory -segmentsize 10240k
Using UNIX pipes to transfer SFS files

Because you can specify stdout as the target of an export and stdin as the source
of an import, you can use UNIX pipes to transfer a file between SFS servers
without creating an intermediate export file. The following command transfers the
file Inventory from server /.:/branch1/server/sfs1 to server /.:/branch1/server/
sfs3:
% sfsadmin export file -server /.:/branch1/server/sfs1 Inventory
-target stdout | sfsadmin import file -server /.:/branch1/server/sfs3 stdin
-target Inventory -targetvolume sfs2Vol
85
Allowing file modification during exports

By default, SFS places a read lock on the entire source file so that the source and
target will be identical. You might, however, want to allow the source file to be
updated while the export is in progress. You can allow modifications and still control
the consistency of the target file by specifying the type of lock to be placed on the
source file. File locks are indicated by the -locktype option of the export command.
You can use the option to do the following:
v Place a temporary read lock on each record as it is exported (recordlock),
allowing other records to be modified during the export operation. This allows the
source and target files to differ. The target file might not have the latest version of
some records, but the data in the target file is guaranteed to be committed data
at the time the data is created. This type of lock is useful when an application
needs a consistent snapshot of the records in a file.
v Specify that no locks are placed on the source file (nolock), which can allow
uncommitted data to be exported.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following example places a temporary read lock on each record of the
Inventory file as it is exported:
|
|
|
|
sfsadmin export file Inventory -locktype recordlock
Recovering from a failed import or export
|
|
|
|
|
A file import or export operation can stop because to client or server failures, device
failures, or operator errors. When a file import or export stops unexpectedly, you
can continue the operation by reissuing the original command with the appropriate
-continue option. This option allows you to resume the import or export or to restart
the process from the beginning.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When an import or export operation fails, SFS issues an error message indicating
where the failure occurred and where the operation will resume. The following is an
example of the error output displayed:
|
|
|
If you want to restart the import or export from the beginning, specify restart as the
argument to the -continue option. Any import or export in progress is ignored and
the existing (partial) SFS file is removed.
|
|
|
If you have not modified the file while the import or export was stopped, you can
continue the import or export by specifying resume as the argument to the
-continue option.
1 W Call to cie_Import failed with status

ENC-sfs-0076: A communication error occurred.
(0x54048c27) : sfs_admin
Status Information:
Version number: 0
Export id: 002EBDB4-F474-1B84-81BE-C037CF450000
Number of tries: 1
In progress: no
End position:
Directory number: 0
File number: 1
File offset: 6834
Restart position:
Directory number: 0
File number: 1
File offset: 5104
86
|
|
|
|
Finally, you can continue an import or export from the position where it ended by
specifying force as the argument to the -continue option. The force argument
continues the import or export even though data was possibly modified while the
operation was stopped.
|
|
|
|
|
|
|
|
|
Note: A user who attempts an export or import has A (administer) permission on

the checkpoint file that is created. To successfully resume a failed export or
import (using the -continue option), either the original user must perform the
export/import or the DCE ACL associated with the checkpoint file must be
changed so that a new user has A (administer) permission on the
checkpoint file. To successfully restart a failed export or import, either the
original user must perform the export/import (using the -continue option), or
the checkpoint file must be deleted so that a new user can restart the
export/import.
|
|
|
|
|
SFS resumes an import or export after the last checkpoint taken. When it resumes,
if SFS cannot determine whether or not a record has been transferred, a permanent
error log file named target.IE.IMP.log for imports and source.IE.EXP.log for exports
is created. The error log file is identical in structure to the SFS file being exported
or imported, except that secondary indices are not created.
|
|
|
|
|
|
Some records might not be exported if (and only if) all the following conditions are
met:
v The last checkpoint was taken within a sequence of duplicate keys.
v Between the failure and continuation, records within this same sequence of
duplicates are deleted.
v The export is continued with the force option.
|
|
|
|
This situation can be avoided by not allowing modifications to the SFS file between
the failure and continuation. Because SFS cannot always determine whether a file
has been modified, it might create and populate an error log file even when no
changes have taken place. Such an error log file can simply be ignored.
|
|
|
|
|
If these conditions are satisfied, SFS might be unable to determine whether some
records have already been placed in the target file. Such records are inserted into
the error log file. The error log file can then be imported along with the source file.
After both imports are complete, you can manually merge the two and eliminate
redundant entries.
|
|
|
|
Similarly, some records might be imported twice if (and only if) the following
conditions are met:
v The last checkpoint is taken within a sequence of duplicate keys
v The import is continued with the force option
|
|
|
|
|
In such a situation, SFS can possibly be unable to determine how many of the
records with duplicate keys have been imported. All records between the last
checkpoint and the next checkpoint will be inserted into the error log. Check the
target SFS file manually to see that none of the records in the error log are
repeated in the SFS file.
|
|
|
|
Improving import/export performance

You can increase the speed of an import or export by increasing the size of the
cache. You can reduce the time needed to recover from a failure by reducing the
amount of data transferred between checkpoints. You can also preserve space on
87
|
|
the target device by compressing relative files during an import, and preventing
RSNs from being written during an export.
Increasing cache size
|
|
|
|
SFS uses caching to improve the efficiency of imports and exports. When a file is
cached, part of its records are stored in a temporary buffer and transferred
(read/inserted) as a group in order to reduce RPC overhead. If caching fails, the
import or export continues without caching and a warning is posted.
|
|
|
|
|
|
|
The default cache size is 256 pages. The size of a page is 4096 bytes. This can be
altered using the -cachesize option of the import or export command. You can
determine the appropriate cache size to use by considering available memory and
record size. The more records that a cache can hold, the lower the RPC overhead
when transferring them. Significant gains usually occur with a small cache and
improve only slightly with larger cache sizes. Specifying 0 (zero) turns caching off.
This can be desirable when memory is at a premium.
Increasing checkpoint size
|
|
|
|
|
|
|
|
|
|
Both importing and exporting provide checkpointing to allow recovery from

interruptions caused by system or device failures, or by reaching the end of media.
A checkpoint file is a temporary SFS file created for use in recovering from failures.
By default, a temporary checkpoint file containing the state of the import or export
operation is created and periodically updated. When importing or exporting is
resumed after an interruption, the SFS reads the contents of the checkpoint file and
continues from that point. The number of bytes between updates of the checkpoint
file--the size of a checkpoint--determines the length of time that SFS takes to
resume the operation after failure and the number of error log entries that you might
need to examine.
|
|
|
|
|
|
|
By default, the checkpoint size is 1 MB. You can change this default with the
-checkpointsize option. A small checkpoint size can result in a shorter recovery
time if the procedure fails. For example, suppose you are exporting a 50-MB file. To
reduce the time required to resume after an interruption, you might want to specify
a smaller checkpoint size than the 1-MB default. The following command specifies a
checkpoint size of 500 KB:
Compressing relative files
|
|
|
To save space on the target device when exporting relative files, you can use the
-norsn option to prevent relative slot numbers (RSNs) from being written to the
exported file. The RSN field is retained in the record.
|
|
You can save space on SFS when importing a file by using the -pack option to
compress deleted slots. SFS automatically generate a new RSNs.
88
sfsadmin export file Inventory -checkpointsize 500k
Chapter 9. Obtaining SFS volume and server information

The largest unit of storage for an SFS server is a CICS Toolkit volume.
Administrators need to periodically check the status of volumes and obtain
information about server attributes. This section describes the sfsadmin and
tkadmin commands for performing these tasks.
You can obtain the following information about an SFS server and its volumes:
v Names of volumes associated with a server. Use the tkadmin list lvols command.
v Disk space used and allocated for a volume and its areas. Use the sfsadmin
query lvol command.
v Attributes of a server, including its log volume and log file name, buffer pool size,
and checkpoint interval. Use the sfsadmin query server command.
The following sections contain complete syntax and examples for these commands.
Note that all sfsadmin and tkadmin commands require that you specify a server
name. If the server name has been defined by the environment variable
CICS_TK_SFS_SERVER, you can omit the -server option on the command line.
Listing volumes
You can list all volumes associated with an SFS server by using the tkadmin list
lvols command. The complete syntax is
tkadmin list lvols -server server_name
The following command displays the volumes associated with the server
/.:/cics/sfs/mysfs:
%
tkadmin list lvols -server /.:/cics/sfs/mysfs
Volumes:
sfsVol1
sfsVol2
sfsVol3
Displaying volume status

You can determine the status of a volume associated with an SFS server by using
the sfsadmin query lvol command. The complete syntax is
sfsadmin query lvol
-server server_name volume_name
The sfsadmin query lvol command displays

v The total number of pages on the volume
v The number of pages used
v The number of pages free
v For each area associated with a file or index, the number of pages allocated and
used
The size of a page is 4096 bytes.
The following command displays information about the volume sfsVol2:
%
sfsadmin query lvol sfsVol2
89
Total pages: 4320

Pages used: 193
Pages free: 4127
Areas:
Area name: telshopFile.stockNumIndex
Pages allocated: 8
Pages used: 1
Area name: telshopFile.productNameIndex
Pages allocated: 8
Pages used: 1
Displaying server information

You can display information about a server by using the sfsadmin query server
command. The complete syntax is
%
sfsadmin query server -server server_name
The command displays the following attributes for a server:

v Collating language. This is the language used in the collation of nlsString fields
in records.
v Log volume and log file name. This is the name of the volume and file to which
log information is written.
v Buffer pool size. This is the size of the memory buffer, in pages, used for disk
input/output (I/O).
v Transactional remote procedure call (TRPC) and minimum authentication level.
v Checkpoint interval information. The checkpoint interval is the time, in seconds,
between writes to recoverable media. The checkpoint interval and the maximum
and minimum number of log records are displayed.
v Default idle timeout. The idle timeout specifies the time, in seconds, that an open
file descriptor (OFD) can be idle while waiting for an SFS call.
The following command displays information about the server /.:/cics/sfs/mysfs:
%
sfsadmin query server -server /.:/cics/sfs/mysfs
Collating language: C
Log file name: SfsLogVol/sfslogfile
Buffer pool size: 1000
TRPC authentication level: 2
Minimum authentication level: 2
Checkpoint Interval Info:
Interval time in seconds: 60
Minimum number of log records: 5000
Maximum number of log records: 100000
Default idle timeout: 60
90
Chapter 10. Improving the performance of the SFS server

This chapter describes how to adjust performance parameters in SFS servers.
Tuning an SFS server

Many factors can affect the performance of an SFS server. In addition to platform
and environment considerations, the following can impact server performance:
v Chunk size
v Buffer pool size
v Thread pool sizes
v Checkpoint interval
Note that many of the above server attributes have default values. The default
values can be changed in the Structured File Server Definitions (SSD).
This section describes how chunk size impacts disk space usage and performance
and how to choose chunk size. It also describes the default settings for the other
server attributes listed above.
Specifying chunk size for physical volumes

When you create a physical volume to back an SFS logical volume, you must
specify the chunk size for the physical volume. Chunk size is an allocation unit used
by the SFS. Chunk size must be specified in units of pages, and it must be a power
of 2. Note that page refers to the CICS page size4096 bytes. Chunk size is
important to the SFS because the chunk size specified for a volume is the
increment by which the SFS allocates disk space when a file or index is expanded.
Chunk size can impact the following:
v How efficiently disk space is used
v The amount of system overhead incurred when allocating space
If a chunk size is large compared to the size of a disk, the SFS may not make
maximum use of available disk space when storing files or indices on the volume.
Small chunk sizes typically allow better use of disk space. However, with small
chunk sizes, the allocation of disk space can occur more often than necessary (for
example, when a file requiring a large amount of disk space grows rapidly). Every
incremental allocation of disk space represents system overhead. If file space
requirements are known in advance, you can avoid frequent space allocation by
preallocating disk space when the file or index is created (with the -preallocate
option of the file or index creation command).
Typically, neither of these costsunused disk space or system overheadis
substantial. It is recommended that you set the initial chunk size to 64 pages; you
can alter chunk size on subsequent volumes if needed. You specify chunk size as
an argument to the tkadmin create pvol command.
Specifying buffer pool size

The buffer pool size is the amount of main memory used as a cache for accessing
recently used portions of CICS Toolkit volumes. A larger buffer pool generally
reduces file system disk I/O but requires more virtual memory. Using too small a
91
buffer pool may result in excessive SFS disk I/O. Using too large a buffer pool may
result in paging or swapping, which usually has a more detrimental effect on
performance.
The buffer pool size is expressed in blocks of 1024 bytes. The default buffer pool
size is 1000 kilobytes. You can modify the default buffer pool size in the Structured
File Server Definitions (SSD).
Specifying thread pool sizes

A thread pool size determines the number of concurrent operations that can run.
You can specify the sizes of the thread pools to be used by an SFS server. There
are two thread pools: processing and emergency. The processing pool is used for
normal processing and administrative operations. The emergency pool is used for
operations that query and free resources. Examples of operations that query and
free resources are the sfs_AbortOperation, sfs_CloseServerOfd,
sfs_ListServerOfds, sfs_ListTransactionLocks, and sfs_GetServerOfdInfo
functions.
You can modify the default thread pool sizes by using the -P option of thesfs
command. When using the -P option, the thread_pool_sizes argument is specified
as a single value or two colon-separated values (processing:emergency). If a single
value is specified, that value indicates the size of the processing pool. If no
processing size is specified, the processing calls will be handled by the default
thread pool. The size of the default thread pool is determined by the value of
CICS_TK_TPOOL_SIZE. If that variable is not defined, the default is 5. If no
emergency size is specified, the default value is 0.
Specifying checkpoint interval

The checkpoint interval is the interval of time between checkpoints made by an SFS
server. Frequent checkpointing can reduce restart time but decreases overall
performance.
You can modify the default checkpoint interval in the Structured File Server
Definitions (SSD).
Using Fast Local Transport (Open Systems)

For improved performance, SFS servers automatically take advantage of the Fast
Local Transport (FLT) mechanism when a server and client reside on the same
machine. FLT offers faster transport than the RPC mechanism.
The following sections describe FLT for servers running on Open Systems. On
Windows, the local RPC mechanism is automatically used when a server and client
reside on the same machine.
Using FLT (SFS servers)

Fast Local Transport (FLT) is a method of client/server communication used when a
server is local (that is, when a server resides on the same machine as the client).
When an SFS server and client reside on the same machine, the SFS automatically
uses the FLT mechanism for many operations. FLT offers two methods of transport:
pipe-based and shared-memory-based. Both offer faster transport than the RPC.
Pipe-based transport uses UNIX-domain sockets or named pipes.
Shared-memory-based transport uses shared memory and process-blocking
92
semaphores. Although shared-memory-based transport is faster than pipe-based

transport, it offers a lower level of security and imposes some restrictions on the
client application.
By default, the pipe-based method is enabled for SFS servers and clients. You must
enable the shared-memory-based method by setting an environment variable. When
a client and server are on the same machine, SFS first determines whether
shared-memory-based FLT is enabled. If shared-memory-based FLT is enabled it is
used. If shared-memory-based FLT is disabled or if a shared-memory connection is
lost, SFS attempts to use pipe-based transport. If pipe-based transport is disabled,
RPC is used. The following sections describe each FLT method.
Using UNIX pipe-based transport

Depending on your operating system, FLT uses either UNIX-domain sockets or
named pipes (FIFO) for pipe-based transport. UNIX-domain sockets and named
pipes are automatically created and stored in the /tmp directory. The UNIX-domain
socket name is /tmp/EPSpid for servers and /tmp/EPCpid for clients. The named
pipe files are stored in /tmp/EFSpid/fifo for servers and/tmp/EFCpid/fifo for clients.
Normally, a UNIX-domain socket is removed automatically when a process exits. If
a process exits abnormally, the socket should be manually removed with the UNIX
rm command.
By default, the pipe-based FLT method is enabled for SFS servers and clients. The
following environment variables control resource usage when pipe-based FLT is
being used. In general, we recommend using the default values.
CICS_TK_FLT_PIPE_DIR
The directory used to store UNIX-domain sockets and named pipes (for
FIFO transport). We recommend that this directory not be on a network
file system. The server must have permission to create and remove files in
the directory, and clients must have lookup permission to the directory. You
may want each server to use a separate directory in which only that server
can create and remove files. The default directory is /tmp.
CICS_TK_FLT_SERVER_MAX_FDS
This is the maximum number of UNIX file descriptors that the server can
use to connect to FLT clients concurrently. Setting this variable to 0 disables
FLT connections. The default is 20 less than the file descriptor limit set
when the operating system is configured.
Note: We recommend that the limit on file descriptors be set to 128 for all
UNIX platforms. The limit on file descriptors is determined by the
UNIX system administrator when a machine is configured; the limit
and the method of setting this limit vary by platform. For example, on
Solaris systems, the file descriptor limit is 64 by default (at most 44
file descriptors are available for FLT requests; the descriptors unused
by FLT are available for other operations, such as communications
and file I/O). Because file descriptors are a limited resource, you can
set CICS_TK_FLT_SERVER_MAX_FDS to a smaller value if you
expect the server to handle many operations that require file
descriptors (such as accepting many RPC connections via the
TCP/IP protocol).
CICS_TK_FLT_CLIENT_MAX_FDS
This controls whether the client can make FLT requests. If the value is set
to 0, the client is unable to make FLT requests. A nonzero value (the
93
default) enables FLT requests. The client can use any number of open file
descriptors up to the limit set for the operating system
CICS_TK_FLT_INACTIVE_TIMEOUT
This is the number of seconds since the server sent a reply to a given client
before the server can disconnect the client and reuse its resources (namely,
the clients UNIX file descriptor for the pipe-based transport, or its shared
memory and semaphore for the shared-memory-based transport). Smaller
timeouts may reduce system performance because of the overhead of
reestablishing broken connections. Larger timeouts may prevent active
clients from using FLT. The default value is 300 seconds. Note that for the
shared-memory-based transport a server may disconnect clients at any time
if it detects a corruption of the shared memory.
CICS_TK_FLT_REPLY_TIMEOUT
This is the maximum number of seconds the server waits for a clients reply
pipe to become empty (if the pipe is full when a reply is to be sent). Smaller
timeouts may cause the server to discard a reply (resulting in a
communication error in the client) under heavy system load. Larger
timeouts may tie up threads in the FLT request pool for long periods. The
default value is 15 seconds.
CICS_TK_FLT_INITIAL_THREADS
This is the initial number of threads in the FLT request thread pool. The
number must be less than the value of CICS_TK_FLT_MAX_THREADS.
The default value is 1.
CICS_TK_FLT_MAX_THREADS
This is the maximum number of threads in the FLT request thread pool. If
all threads are busy when the server receives an FLT request, the server
returns the request to the client with instructions to repeat the request via
RPC. The default value is 30. You can disable pipe-based FLT for a server
by setting the environment variable CICS_TK_FLT_SERVER_MAX_FDS to
0.
Using shared-memory-based transport

The shared-memory-based transport uses shared memory and process-blocking
semaphores. This method is suitable for SFS applications that do not require the
SFS client library to be thread-safe. When shared-memory-based transport is used,
the entire client process blocks when the client has an SFS request outstanding.
Although shared-memory-based transport offers performance benefits comparable
to pipe-based transport, it does not provide the level of security guaranteed by RPC
or pipe-based transport. For example, it does not encrypt messages or do any form
of authentication. Shared-memory-based transport provides only minimal protection
against malicious attacks by using UNIX access control mechanisms on the shared
memory segment and semaphores. It does, however, provide reasonable protection
against inadvertent scribbling by optionally detaching and reattaching the shared
memory segment from the client process when user code is being executed. The
environment variables CICS_TK_FLT_SMS_PROT_MODE and
CICS_TK_FLT_SMS_SERVER_OPTIONS control these mechanisms
Shared-memory-based transport must be enabled on both the client and the server
by setting the CICS_TK_FLT_SMS_SERVER_ENABLE and
CICS_TK_FLT_SMS_CLIENT_ENABLE variables to 1. The following environment
variables control resource usage for shared-memory-based transport:
94
CICS_TK_FLT_SMS_SERVER_ENABLE
Enables clients to connect to a server using shared-memory-based
transport. The default value is zero, meaning that shared-memory-based
transport is disabled. (Set by server.)
CICS_TK_FLT_SMS_CLIENT_ENABLE
Enables servers to connect to a client using shared-memory-based
transport. The default value is zero, meaning that shared-memory-based
transport is disabled. (Set by client.)
CICS_TK_FLT_SMS_MAX_CONNECTIONS
This is the maximum number of clients that can be connected to an SFS
server at one time using shared-memory-based transport. The default value
is 16.
CICS_TK_FLT_SMS_MSG_SIZE_MAX
This is the maximum size of messages sent to and received from a server
via shared-memory-based transport. The default value is 8192 bytes. In the
case of a client communicating with multiple servers using shared memory,
the maximum size of the message that can be sent to any of the servers is
the smallest value of CICS_TK_FLT_SMS_MSG_SIZE_MAX among the
servers.
This is the number of seconds since the server sent a reply to a given client
before the server can disconnect the client and reuse its resources (namely,
the clients UNIX file descriptor for the pipe-based transport, or its shared
memory and semaphore for the shared-memory-based transport). Smaller
timeouts may reduce system performance because of the overhead of
reestablishing broken connections. Larger timeouts may prevent active
clients from using FLT. The default value is 300 seconds. Note that for the
shared-memory-based transport a server may disconnect clients at any time
if it detects a corruption of the shared memory.
CICS_TK_FLT_SMS_PROT_MODE
This specifies which processes can access the shared memory segment
(using UNIX file-system-style access mode bits). The only meaningful
settings in this context are 666 (allow all processes to read or write the
segment); 660 (allow only processes in the same group as the server
process to access the segment); and 600 (allow only processes owned by
the same user as the server to access the segment). The default value is
660 (octal).
CICS_TK_FLT_SMS_SERVER_OPTIONS
This specifies whether the FLT client detaches shared memory before
returning to an application and/or whether a watch dog process unblocks
clients and deletes shared resources when a server crashes. A value of 1
directs the FLT client to detach shared memory before returning to the
application. A value of 2 directs the server to spawn a watch dog process to
detect server crashes. When a server crashes, the watch dog process
unblocks clients waiting for semaphores and deletes the shared resources
owned by the stopped server. A value of 3 specifies that both options are to
be used. The default value is 2.
95
96
Chapter 11. Monitoring and maintaining a gateway server

Monitoring and maintaining a gateway server consists of periodically querying
conversation statistics or listing the active conversations and transactions.
Transactions that have been active for an abnormally long period of time can be
forced to an outcome by canceling resynchronizations or forcing the exchange of
log identifier names.
Note: The CICS_PPC_GWY_SERVER environment variable is used as the default
for the -server option if a gateway server name is not specified on the
ppcadmin command line. Most of the examples in this chapter assume that
this environment variable is set to the name of the gateway server; the
-server option is not used.
Determining conversation status

This section explains how to list active conversations at the gateway server and
query the gateway server for more information about its active conversations.
Each connection between a CICS region and a mainframe LU consists of two
conversations at the gateway serverthe conversation between the CICS region
and the gateway server and the conversation between the gateway server and the
mainframe LU. The ppcadmin commands return information only about
conversations between a gateway server and a mainframe.
List conversations
To display a list of all active conversations between the gateway server and the
mainframe LU, use the ppcadmin list convs command. Since this command lists the
active conversation at the instant the command is executed at the gateway server,
there is no guarantee that a conversation is still active after this command has
completed. The complete syntax follows:
ppcadmin list convs -server server_name
This command displays the following information about each active conversation:
v Conversation identifier
v Logical unit of work identifier
v Transaction identifier (local tid)
v Global transaction identifier
v Transaction program name
v The allocator and acceptor of the conversation. The arrow signifies the allocator
> acceptor relationship.
For example, the following command displays the active conversations at a gateway
server:
%
ppcadmin list convs
Command executed at: Fri Oct 22 12:31:08 1993

total convs: 2
convId: 543ab278
Logical Unit of Work Id:NETWORK1.LUALFRED:12bf45679abc:2a
Transaction Id: 15
Global tid:
0000000d0112010128afc9666352cdb274080009
TP name:
SUBMIT
Executive LU:
ORDENTRY --> SNA Partner LU: SNALU01
97
convId:
Logical Unit of
Transaction Id:
Global tid:
TP name:
Executive LU:
543ab279
Work Id:NETWORK1.LPINV:22bf45679abc:1a
32
0000010d0244010135efc955246311b264070009
QUERY
ORDENTRY <-- SNA Partner LU:LPIN
See ppcadmin list convs on page 119 for a detailed description of command
output.
Query conversations
To display information about a conversation, use the ppcadmin query conv
command, where the convid argument is a hexadecimal number identifying a
conversation. (Use the ppcadmin list convs command to list all conversation
identifiers.) The complete syntax of the ppcadmin query conv command follows:
ppcadmin query conv -server server_name convid
This command displays the following information about the conversation:

v Conversation parameters
Logical unit of work identifier
Transaction identifier (local tid)
Global transaction identifier
TP name (TPN)
Synchronization level
Conversation type
Conversation state
Last syncpoint state
Conversation correlator
Session identifier
v Peer information
The allocator and acceptor of the conversation. The arrow signifies the
allocator > acceptor relationship.
Perceived peer (tran) state
v SNA information
SNA mode name
SNA security type
SNA user identifier
v Conversation statistics from the time the gateway server was last started
Bytes sent
Bytes received
Error count
Number of syncpoints
Number of backouts
For example, the following command queries the conversation 543ab278:
%
ppcadmin query conv 543ab278

convId: 543ab278
Conversation Parameters:
----------------------Logical Unit of Work Id:NETWORK1.LUALFRED:12bf45679abc:2a
98
Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
TP name:
TRAN002FOO
SyncLevel:
PPC_SYNCLEVEL_SYNCPOINT
Conversation Type:
PPC_CONVERSATION_MAPPED
Conversation State:
PPC_STATE_SEND
Last Syncpoint State:
PPC_STATE_SEND
This is a SNA Conversation.
Conversation Correlator: 1710026500000008
Session Id:
f000000000000005
Peer Information:
---------------Executive LU: ORDENTRY --> SNA Partner LU: SNALU001
Local Tran State: PPC_TRAN_STATE_PREPARED
Perceived Peer (Tran) State: PPC_TRAN_STATE_ACTIVE
SNA Parameters:
-------------SNA Mode Name:
ORDERMODE
SNA Security Type: PPC_SECURITY_PROGRAM
SNA User Id:
GatewayUser
Conversation Statistics:
----------------------Bytes Sent:
100
Bytes Received:
85
Error Count:
0
Number of Syncpoints 42
Number of Backouts:
0
See ppcadmin query conv on page 126 for a detailed description of command
output.
Determining LUW status

A logical unit of work (LUW) is a set of autonomous changes to a set of protected
resources that move them from one consistent state to another in such a way that
the unit of work appears atomic. This set of changes is the work that occurs
between two syncpoints or synchronization points; this work must be executed
together for correctness. If a failure occurs during the LUW, all the changes that are
made are undone and the state is restored to that at the start of the LUW. An LUW
is the Systems Network Architecture (SNA) equivalent of an CICS Toolkit
transaction; however, several transactions can correspond to the same LUW.
An LUW identifier is unique across the SNA network, just as a Toolkit global
transaction identifier (global tid) is unique throughout the CICS Toolkit Server. A
Toolkit transaction identifier (tid) is local to the gateway server (there is no analogue
in the SNA terminology).
You can list the transactions or LUWs active at the gateway server and query the
gateway server for more information about individual LUWs.
List transactions
To display a list of the transaction identifiers of all active transactions at the gateway
server, use the ppcadmin list transactions command. There is no guarantee that a
transaction is still active after this command has completed. The complete syntax is
ppcadmin list transactions -server server_name
This command displays the following information about each active transaction:
99

For example, the following command displays the transaction identifiers for the
active transactions at a gateway server:
%
ppcadmin list transactions

Total transactions: 3
Transaction Id: 15
Global tid: 0000000d0112010128afc9666352cdb274080009
Transaction Id: 32
Global tid: 0000010d0244010135efc955246311b264070009
Logical Unit of Work Id:NETWORK3.LUNANCY1:12bf45679abc:12
Transaction Id: 35
Global tid: 0000020b0145012135bcc955246311d264880009
Logical Unit of Work Id:NETWORK5.LUDEBBIE:12bf45679abc:1
See ppcadmin list transactions on page 124 for a detailed description of command
output.
List LUWs
To display a list of the LUW identifiers of all transactions that are active at the
gateway server, use the ppcadmin list luws command. There is no guarantee that a
transaction is still active after this command has completed. The complete syntax is
ppcadmin list luws -server server_name
This command displays the following information about each active transaction:
For example, the following command displays the LUWs and their associated CICS
Toolkit transaction identifiers for the active transactions at a gateway server:
%
ppcadmin list luws

Total LUWs: 3
Transaction Id: 15
Logical Unit of Work Id:NETWORK3.LUNANCY1:12bf45679abc:12
Transaction Id: 32
Global tid: 0000010d0244010135efc955246311b264070009
Logical Unit of Work Id:NETWORK5.LUDEBBY4:12bf45679abc:1
Transaction Id: 35
Global tid: 0000020b0145012135bcc955246311d264880009
Query an LUW
To display information about a specific active LUW, use the ppcadmin query luw
command. The LUW identifier must be specified to identify the logical unit of work.
(The ppcadmin list luws command displays the LUW identifiers of all active
transactions at the gateway server.) The complete syntax of the ppcadmin query
luw command follows:
100
ppcadmin query luw -server server_name LUW_Id
This command displays the following information about active transactions identified
with the specified LUW. Note that there can be multiple CICS Toolkit transactions
associated with one LUW.
v Total number of transactions
v Number of associated conversations
v Conversation identifier
v Executive LU name
v SNA partner LU alias
v Conversation correlator
Session identifier
Local transaction state
Perceived peer transaction state
Description of the transaction state at the gateway server and the perceived
transaction state at the partner.
v
v
v
v
For example, the following command displays information about the transactions
identified with the NETWORK1.LUALFRED:12bf45679abc:2a LUW:
%
ppcadmin query luw
NETWORK1.LUALFRED:12bf45679abc:2a

Total transactions:
2
Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
Number of conversations associated with this transaction:1
convId:
543ab278
Executive LU:
ORDENTRY
SNA Partner LU: SNALU02
Session Id:
f000000000000005
Local Tran State:
PPC_TRAN_STATE_BO_REQUIRED
Peer Tran State:
PPC_TRAN_STATE_ABORTED
This site is about to abort the transaction.
Peer has sent a Backout and is waiting for Backout response.
Transaction Id:
35
Global tid:
0000020b0145012135bcc955246311d264880009
Number of conversations associated with this transaction:1
convId:
573ab478
Executive LU:
EXECLU02
Session Id:
f000000000000002
Local Tran State:
PPC_TRAN_STATE_PREPARED
Peer Tran State:
PPC_TRAN_STATE_PREPARING
Transaction is prepared and awaiting resolution at this site.
(Not finished.)
A prepare has been sent to the peer. This site has
resynchronization responsibility towards the peer.
See ppcadmin query luw on page 131 for a detailed description of command
output.
101
Determining resynchronization status and canceling

resynchronizations
Like a CICS Toolkit transaction, an LUW can be committed, moving resources to
the next synchronization point, or backed out, restoring resources to the last
synchronization point (this is similar to aborting a CICS Toolkit transaction). If a
failure occurs during syncpoint processing, the LU 6.2 sites must perform
resynchronization (resync) processing to ensure resources are in consistent states.
Like other LU 6.2 sites, the gateway server handles resynchronization automatically.
Resynchronization occurs whenever a synclevel syncpoint conversation fails during
syncpoint processing. Failures may be caused by a system, LU, or communications
failure. When syncpoint processing is interrupted, resynchronization processing is
begun. When communications between the LU pair are again possible,
resynchronization processing will finish. LUW state information is logged by both
sites to be used if a site fails and must be restarted.
Resynchronization occurs over a special conversation called a resynchronization
conversation, which is allocated by one of the peerseither the gateway server or
the system where the partner LU resides. The peer that has resynchronization
responsibility allocates the resynchronization conversation. Resynchronization
progresses in the following three stages:
1. The partners exchange their log names to verify that both partners are using the
correct log. (For more information about exchanging log names, see
Determining log exchange status on page 108.)
2. After the partners have determined that they are using the correct log, they
compare and adjust their LUW states. This ensures that resources are in
consistent states. If resources are in inconsistent states, the system
administrator is notified of the damage, as described in Damage reporting
during resynchronization on page 110. (Inconsistent states should occur only if
an operator has forced the outcome of a transaction at one of the sites during
the outage.)
3. When resynchronization processing is complete, any locked resources are freed
and the log for the LUW is updated.
After a resynchronization completes successfully, the LUW is finished and the
conversations are gone. New LUWs and conversations may be set up.
If a resynchronization cannot complete successfully, all resources continue to be
held. CICS Toolkit transactions and SNA LUWs may be blocked. Occasionally, a
blocked transaction or resource prevents the system from functioning normally. In
these rare cases, you can take further action. Although forcing the outcome of a
transaction can possibly cause heuristic damage by leaving resources in
inconsistent states, it also unblocks all transactions that are waiting for the
resynchronization to complete, allowing transaction processing to proceed.
Because the gateway server itself has no resources that can become blocked
(except communications resources between LU pairs), consider unblocking
resources at other sites before taking any action at the gateway server. Before
taking any action to unblock resources, you must understand the structure of the
transaction, the nature of the application, and the actions likely to be taken at other
sites. It may be advantageous to manually coordinate actions at different sites.
Under certain conditions, CICS Toolkit transactions and SNA LUWs can become
blocked at a gateway server for reasons other than failures during syncpoint
102
processing. For example, blocked transactions and LUWs can occur when an
application or system on either side of the gateway server does not respond. The
ppcadmin destroy conv command can be used to address such situations. You can
attempt to destroy a conversation associated with a blocked transaction before
taking other actions such as canceling a resynchronization.
As part of canceling a resynchronization, each CICS Toolkit transaction must be
resolved (committed or aborted) and then finished. When a gateway server has
resynchronization responsibility, the gateway server automatically resolves and
finishes transactions when the resynchronization is canceled. When a gateway
server does not have resynchronization responsibility, the CICS Toolkit transactions
are not resolved as part of canceling the resynchronization. In this case, you must
explicitly finish the transaction at the gateway server after a resynchronization has
been canceled. (Table 12 on page 107 shows when a gateway server has
resynchronization responsibility.)
You can determine the status of any resynchronization by using the ppcadmin list
resyncs and ppcadmin query resync commands. You can cancel a
resynchronization by using the ppcadmin cancel resync and ppcadmin force
transaction commands.
List resynchronizations
To display information about the LUWs that have pending resynchronizations at the
gateway server, use the ppcadmin list resyncs command. The complete syntax is:
ppcadmin list resyncs -server server_name
This command displays the following:

v Number of transactions with pending resynchronizations
v Information about each transaction with a pending resynchronization:
LUW identifier
Local transaction identifier (tid)
Conversation identifier
CICS LU alias
SNA partner LU alias
SNA conversation correlator
SNA session identifier
For example, the following command displays information about pending
resynchronizations:
%
ppcadmin list resyncs

Number of transactions with pending resynchronizations:1
Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
convId:
543ab278
Executive LU:
ORDENTRY
SNA Partner LU:
SNALU02
Session Id:
f000000000000005
See ppcadmin list resyncs on page 122 for a detailed description of command
output.
103
Query resynchronizations
To display information about pending resynchronizations between a CICS region
and mainframe LU pair, use the ppcadmin query resync command. Both the CICS
application LU and the mainframe LU must be specified to identify the subset of all
pending resynchronizations. This command displays only the resynchronizations
pending between the specified LUs. There can be other resynchronizations pending
between other pairs of LUs. (Use the ppcadmin list resyncs command to obtain a
list of all pending resynchronizations at the gateway server.) The complete syntax of
the ppcadmin query resync command follows:
%
ppcadmin query resync -server server_nameExecutive_LU SNA_Partner_LU
This command displays the following information about pending resynchronizations

between the specified LU pair:
v If the exchange of log names has completed
v
v
v
v
Number of transactions with pending resynchronizations

CICS region LU alias
SNA partner LU alias
For each transaction with a pending resynchronization, the following information
is displayed:
LUW identifier
Local transaction identifier (tid)
Conversation identifier
SNA conversation correlator
SNA session identifier

SNA mode name
Local tran state
Perceived peer tran state
Description of tran states
For example, the following command displays information about the

resynchronizations pending for conversations between the CICS region LU
ORDENTRY and the mainframe LU SNALU01:
%
ppcadmin query resync ORDENTRY SNALU01

Exchange Log Name Complete: NO
Number of transactions with pending resynchronizations: 1
Executive LU: ORDENTRY
Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
convId:
543ab278
Session Id:
f000000000000005
SNA Mode Name:
BLANKMOD
Local Tran State:
Peer Tran State:
(Not finished.)
See ppcadmin query resync on page 133 for a detailed description of command
output.
104
Destroy conversations
If a transaction appears to be blocked at the gateway server and an associated
resynchronization does not exist, you can use the ppcadmin destroy conv command
to cause a communications failure that may result in a resynchronization.
A blocked transaction with no associated resynchronization typically occurs when an
application neither receives nor responds to a syncpoint indication. In such cases,
the ppcadmin destroy conv command causes a resynchronization that often
completes immediately and unblocks the transaction. If the resynchronization does
not complete immediately, it becomes a pending resynchronization. If the
resynchronization does not complete immediately and there is still no pending
resynchronization, but the transaction remains blocked, this means that the
transaction is not blocked at the gateway server. You can take the necessary steps
to unblock the transaction at one of the other sites.
Note: Only synclevel syncpoint (SL2) conversations can be associated with
blocked transactions.
The argument to the ppcadmin destroy conv command is the conversation identifier
that is obtained by using the ppcadmin list convs command. The complete syntax of
the ppcadmin destroy conv command follows:
ppcadmin destroy conv -server server_name Conversation_Id
Note: Destroying a conversation will never, by itself, damage a transaction.
Determine whether to destroy a conversation

Before destroying a conversation, obtain the conversation identifier by listing the
conversations that are being handled at the gateway server. Then, determine the
conversation state by querying the conversation that you think you need to destroy.
Table 11 shows the ppcadmin commands that you can use to determine whether to
destroy a conversation.
Table 11. Determining whether to destroy a conversation
Conversation Information
Command
Conversations being handled at the gateway

server
ppcadmin list convs
State of a conversation at the gateway

server
ppcadmin query conv
State of transactions at the gateway server
ppcadmin query luw
All pending or incomplete resynchronizations ppcadmin list resyncs

Status of transactions that are awaiting
resolution
ppcadmin query resync
You may need to review several fields when determining whether to destroy a
conversation. You can use the LUW or the local or global transaction identifier of
the conversation to determine which conversations are associated with the blocked
transaction. The LU names, TPN, conversation correlator, and session identifier are
also useful in selecting conversations to destroy. You can attempt to destroy all
conversations associated with a blocked transaction before taking other actions
such as canceling a resynchronization.
The command in the following example determines the state of conversation
543ab278:
105

convId: 543ab278
----------------------Logical Unit of Work Id: NETWORK1.LUALFRED:12bf45679abc:2a
Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
TP name:
TRAN002FOO
SyncLevel:
Conversation Type:
Conversation State:
PPC_STATE_RECEIVE
PPC_STATE_RECEIVE
Session Id:
f000000000000005
Peer Information:
---------------Executive LU: ORDENTRY <-- SNA Partner LU: SNALU001
Local Tran State: PPC_TRAN_STATE_ACTIVE
SNA Parameters:
ORDERMODE
SNA User Id:
GatewayUser
----------------------Bytes Sent:
100
Bytes Received:
85
Error Count:
0
Number of Syncpoints: 42
Number of Backouts:
0
Destroy a conversation
Destroy the conversation. The following command destroys the specified
conversation:
%
ppcadmin destroy conv 543ab278
Cancel resynchronizations
Before canceling a resynchronization, attempt to force the exchange of log names
with the ppcadmin force xln command. By doing this, you attempt to force the first
phase of resynchronization, which may enable the completion of resynchronization,
making the cancellation of the resynchronization unnecessary. (See Determining
log exchange status on page 108 for more information.)
To cancel a pending resynchronization, use the ppcadmin cancel resync command.
Specify both partners in the conversation: the CICS region LU and the mainframe
LU. (Use the ppcadmin list resyncs or ppcadmin query resync commands to
determine the LU names of the conversation partners.) The complete syntax of the
ppcadmin cancel resync command follows:
ppcadmin cancel resync -server server_name Executive_LU SNA_Partner_LU
There may be more than one pending resynchronization associated with a given LU
pair. The ppcadmin cancel resync command cancels all associated pending
resynchronizations.
106
CAUTION:
Canceling a resynchronization may cause heuristic damage, leaving
resources in inconsistent states.
Note that the ppcadmin cancel resync command does not guarantee that the
resynchronization will be canceled, since the resynchronization may have already
succeeded. When the gateway server is responsible for allocating the
resynchronization conversation (has resync responsibility), it normally retries until
the conversation is allocated and the resynchronization work is finished. A
resynchronization is tried at least once before it is canceled.
Determine whether gateway server has resync responsibility

Before canceling the resynchronization, query the pending resynchronizations and
determine whether the gateway server has resynchronization responsibility. As
shown in Table 12, if the ppcadmin query resync command returns a Perceived
Peer (tran) State of PPC_TRAN_STATE_PENDING, the gateway does not have
resynchronization responsibility. If the gateway server does not have
resynchronization responsibility, record the transaction identifier of the pending
resynchronization; you will need this information later.
Table 12. Determining resync responsibility from transaction states
Local or Perceived Peer Transaction
States
Resync Responsibility
Local Tran State:

PPC_TRAN_STATE_IMPLIED_FORGET_
PENDING
Gateway
Perceived Peer (tran) State:

Gateway

Gateway

PPC_TRAN_STATE_PENDING
Mainframe
The following command allows you to determine whether the gateway server has
resynchronization responsibility:
%

Logical Unit of Work Id: NETWORK1.LUALFRED:12bf45679abc:2a
Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
convId:
543ab278
Session Id:
f000000000000005
SNA Mode Name:
BLANKMOD
Local Tran State:
Peer Tran State:
(Not finished.)
107
Cancel resynchronization
Cancel the resynchronization. The following command notifies the gateway server
to cancel all pending resynchronizations between the CICS region LU ORDENTRY
and the mainframe LU SNALU01. (Remember, a potential for damage is introduced
when canceling a resynchronization.)
%
ppcadmin cancel resync ORDENTRY SNALU01
Finish transaction (if gateway server does not have resync

responsibility)
If the ppcadmin query resync command returns a Perceived Peer (tran) State of
PPC_TRAN_STATE_PENDING, you must explicitly finish the CICS Toolkit
transaction. Because the ppcadmin cancel resync command returns immediately
(before the cancellation actually completes), you must query the resynchronization
periodically to determine when the resynchronization is no longer pending. When
the resynchronization is no longer pending, use the tkadmin list transactions
command to determine the state of one or more transactions associated with the
canceled resynchronization.
If a transaction is not in the prepared state, use the tkadmin abort transaction
command to abort the transaction and the tkadmin force transaction command with
the -finish option to finish it.
%
tkadmin list transactions
15432 active
%
tkadmin abort transaction 15432
tkadmin force transaction 15432 -finish
If a transaction is prepared, you must force its outcome. If you wish to abort the
prepared transactions (for example, you know the transaction has aborted at
another site), use the tkadmin force transaction command. (This command aborts
the transaction by default.)
%
65536 prepared
%
tkadmin force transaction 65536
If you wish to commit one or more prepared transactions, use the -commitdesired
option for the tkadmin force transaction command.
%
tkadmin force transaction 65536 -commitdesired
After you have forced the transaction to an outcome (either commit or abort), use
the tkadmin force transaction command with the -finish option to finish it. This
erases the log records of the transaction so the gateway server does not attempt to
do the resynchronization under any circumstances.
%
Determining log exchange status

Log identifier names are initially exchanged when the first synclevel syncpoint (SL2)
conversation is initiated between an LU pair. Log identifier names are again
exchanged during the first stage of resynchronization processing, to verify that both
partners are using the same log after the failure that they were using before the
failure. You can display the status of log identifier name exchanges between the LU
pairs that have participated in a synclevel syncpoint conversation. These LU pairs
108
consist of an LU managed by the gateway server and a mainframe LU configured

to communicate with the gateway server LU. The exchange is either complete or
incomplete.
The exchange will be complete for partners (gateway server LU and mainframe LU)
that have participated in a synclevel syncpoint conversation since the gateway
server has started, or that have completed the first stage of resynchronization
processing by successfully exchanging log identifier names. The exchange will not
be complete if the partners have not initiated a conversation after a session has
failed or after the gateway server has stopped and restarted, or if a
resynchronization is pending and the partners have not yet exchanged their log
names.
Forcing a remote LU to exchange its log identifier name with the gateway server LU
is similar to pinging a server. Exchanging log identifier names checks the SL2
connectivity between a pair of LUs. When all the SNA sessions between a pair of
LUs go down, the synclevel syncpoint connectivity between them can be checked
outside the context of pending resynchronizations. Also, if a pending
resynchronization is taking abnormally long, you can attempt to force the exchange
of log identifier names (the first stage of the resynchronization protocol), which may
allow the resynchronization to finish.
List log identifier name exchange status

To display the status of exchanging log identifier names for the LU pairs that have
participated in a synclevel syncpoint conversation, use the ppcadmin list xlns
command. The exchange is either complete or incomplete. The complete syntax of
the ppcadmin list xlns command follows:
ppcadmin list xlns -server server_name
For example, the following command displays the status of the log identifier name
exchanges at a gateway server:
%
ppcadmin list xlns

Number of LU pairs: 2
Executive LU:
EXECLU01
Log Identifier Name Exchange Complete: YES
Executive LU:
EXECLU02
Log Identifier Name Exchange Complete: NO
Query log identifier name exchange status

To determine whether a pair of CICS region and mainframe LUs have exchanged
log identifier names, use the ppcadmin query xln command. The exchange is either
complete or incomplete.
Specify both partners in the conversation. Use the ppcadmin list xlns or ppcadmin
list resyncs commands to determine the LU names of the conversation partners that
you wish to query. The complete syntax of the ppcadmin query xln command
follows:
%
ppcadmin query xln -server server_name Executive_LU SNA_Partner_LU
The command in the following example displays the status of the log identifier name
exchange between the CICS region LU ORDENTRY and the mainframe LU
SNALU01 at a gateway server:
109
ppcadmin query xln ORDENTRY SNALU01

Executive LU:
EXECLU01
Force log identifier name exchange

To force a pair of LUs to exchange their log identifier names, use the ppcadmin
force xln command. Specify both partners in the conversation: the CICS region LU
and the mainframe LU. Use the ppcadmin list xlns or ppcadmin list resyncs
commands to determine the LU names of the conversation partners. The complete
syntax of the ppcadmin force xln command follows:
ppcadmin force xln -server server_name [-mode Mode_Name] Executive_LU
SNA_Partner_LU
This command does not return until the exchange is complete or the command
fails.
Unlike the ppcadmin cancel resync command, the ppcadmin force xln command
does not result in a potential for heuristic damage. It is recommended that you
attempt to force the exchange of log names by using the ppcadmin force xln
command before canceling a resynchronization. By doing this, you attempt to force
the first phase of resynchronization, which may enable the completion of
resynchronization, making its cancellation unnecessary.
The command in the following example notifies the gateway server to force the
CICS region LU ORDENTRY and the mainframe LU SNALU01 to exchange their
log identifier names. The default mode SNASVCMG is used.
%
ppcadmin force xln ORDENTRY SNALU01
Damage reporting during resynchronization

If an error occurs during resynchronization processing, you will be notified via an
audit message. The PPC Services audit messages concerning resynchronization
damage and errors correspond to the SNA resynchronization operator messages,
documented in the System Network Architecture LU 6.2 Reference: Peer Protocols.
Table 13 lists the PPC Services audit messages used to report a heuristic decision
or heuristic damage. If you receive one of these audit messages, look up the
corresponding resynchronization operator message in the System Network
Architecture LU 6.2 Reference: Peer Protocols to determine the action you should
take.
Table 13. PPC Services audit messages concerning resynchronization damage and errors
PPC Services Audit Message
SNA Resync Operator Message Id
A heuristic decision (Forced outcome) {abort 1

| commit} has been made. Resources in
associated LUs may be in inconsistent states
with respect to local resources.
Resources in the associated LUs previously
reported to be exposed to state
inconsistency with respect to local resources
have been found to be synchronized.
110
Table 13. PPC Services audit messages concerning resynchronization damage and
errors (continued)
PPC Services Audit Message
SNA Resync Operator Message Id
Resources in associated LUs previously

3
reported to be exposed to state
inconsistency with respect to local resources
have been found to be out of
synchronization. This logical unit of work has
been DAMAGED.
Protocol failure in resynchronization logic
during attempted resynchronization for tid:
tid, luwid: luwid. The local luwid state is
luwid_state, the partner state is luwid_state.
Resources in associated LUs that may have 8

been waiting for resynchronization with
respect to local resources have been found
to be out of synchronization. Local resources
were not involved in a heuristic decision.
Some remote resources were involved in a
heuristic decision. This logical unit of work
has been DAMAGED.
111
112

The ppcadmin commands are used to administer peer-to-peer communications
through the gateway server. The ppcadmin commands can be grouped by task, as
shown in the following list:
v Destroying a conversation
ppcadmin destroy conv on page 116
v Canceling resynchronizations
ppcadmin cancel resync
v Forcing log identifier exchanges
ppcadmin force xln on page 118
v Displaying information
ppcadmin list convs on page 119
ppcadmin list luws on page 121
ppcadmin list resyncs on page 122
ppcadmin list transactions on page 124
ppcadmin list xlns on page 125
ppcadmin
ppcadmin
ppcadmin
ppcadmin
query
query
query
query
conv on page 126

luw on page 131
resync on page 133
xln on page 135
ppcadmin cancel resync

Purpose
Cancels all pending resynchronizations between the specified LU pair.
Synopsis
ppcadmin cancel resync -server server_name Executive_LU SNA_Partner_LU
Arguments
-server server_name
Specifies the name of the gateway server. If the -server option is not specified,
the default is the server defined by the environment variable
CICS_PPC_GWY_SERVER.
Executive_LU
Specifies the name of the CICS region Logical Unit (LU) participating in the
incomplete transaction.
SNA_Partner_LU
Specifies the name of the mainframe Logical Unit (LU) participating in the
incomplete transaction.
Description
The ppcadmin cancel resync command cancels all resynchronizations that are
pending between the specified pair of LUs. To cancel a resynchronization, you must
specify both partners in the conversation: the CICS region LU and the mainframe
113
LU. Use the ppcadmin list resyncs or ppcadmin query resync commands to
determine the LU names of the conversation partners.
A resynchronization occurs as the result of a session outage during syncpoint
processing. If syncpoint processing is interrupted, a resynchronization conversation
is allocated by one of the conversation peers (the gateway server or its partner) to
determine the state of the LUW (transaction) at each participant and to make sure
resources are in consistent states.
This command can be used to free resources that are blocked while waiting for a
resynchronization to complete. If a resynchronization cannot complete successfully,
resources are held and distributed CICS transactions and Systems Network
Architecture (SNA) Logical Units of Work (LUWs) may be blocked. If a blocked
transaction or resource prevents the system from functioning normally, you may
choose to cancel the resynchronization. Although canceling a resynchronization can
cause heuristic damage, it also enables transaction processing to proceed.
Because the gateway server itself has no resources to unblock (except
communication resources between LU pairs), you may wish to consider unblocking
resources at other sites before canceling a resynchronization at the gateway server.
However, before taking any action to unblock resources, you should understand the
structure of the transaction, the nature of the application, and the actions likely to
be taken at other sites. It may be advantageous to manually coordinate actions at
different sites.
Canceling a resynchronization with this command may require that you explicitly
finish the transactions at the gateway server. (Finishing a transaction erases the log
records of the transaction so the gateway server does not attempt to redo the
canceled resynchronization under any circumstances.) As part of canceling a
resynchronization, each distributed CICS transaction must be resolved (committed
or aborted) and then finished.
Gateway servers that allocated the resynchronization conversation have
resynchronization responsibility; these servers automatically resolve and finish
transactions when resynchronizations are canceled. For gateway servers that do
not have resynchronization responsibility, the distributed CICS transactions are not
resolved as part of canceling the resynchronization. In this case, you must explicitly
finish the transactions at the gateway server after a resynchronization has been
canceled.
Before canceling a resynchronization, query all pending resynchronizations. If the
ppcadmin query resync command returns a Perceived Peer (tran) State of
PPC_TRAN_STATE_PENDING, the gateway server does not have resync responsibility
and you must explicitly finish the distributed CICS transaction. Record the
transaction identifiers of the pending resynchronization; you will need this
information later.
Allocation of the resynchronization conversation is attempted until it succeeds; that
is, the allocation is retried until the conversation is allocated and the
resynchronization work is finished. A resynchronization is tried at least once before
it is canceled. Therefore, executing the ppcadmin cancel resync command does not
guarantee that the resynchronization will be canceled, as the resynchronization may
succeed on the first try.
We suggest that you attempt to force the exchange of log names before canceling
a resynchronization, with the ppcadmin force xln command. This command attempts
114
to perform the first phase of resynchronization, and may enable the

resynchronization to complete, without canceling and possibly causing damage.
After canceling the resynchronization, if the gateway server does not have
resynchronization responsibility, you must finish the transaction on the CICS side.
Because the ppcadmin cancel resync command returns immediately (before the
cancellation completes), continue to query the resynchronization to determine when
the cancellation is no longer pending, either because the cancellation succeeded or
the resynchronization succeeded.
When the resynchronization is no longer pending (that is, the cancellation is
complete), use the tkadmin list transactions command to determine the state of the
transaction(s) associated with the canceled resynchronization.
v If a transaction is not in the prepared state, use the tkadmin abort transaction
command to abort the transaction and the tkadmin force transaction -finish
command to finish it.
v If a transaction is prepared, you must force its outcome.
If you wish to abort a prepared transaction (for example, you know the
transaction has aborted at another site), use the tkadmin force transaction
command, which aborts the transaction by default.
If you wish to commit a prepared transaction, use the -commitdesired option
of the tkadmin force transaction command.
After you have forced the transaction to an outcome, use the tkadmin force
transaction -finish command to finish it.
Cautions
Canceling a resynchronization may cause heuristic damage, leaving resources in
inconsistent states.
Examples
When canceling a resynchronization, first determine if the gateway server has
resynchronization responsibility. In this example, the gateway server does not have
resynchronization responsibility.
Then cancel the resynchronization(s). The command in the following example
notifies the gateway server to cancel all pending resynchronizations between the
CICS region LU, ORDENTRY, and the mainframe LU, SNALU01.
Since the gateway server does not have resynchronization responsibility, you must
finish the transaction on the CICS side. After the cancellation is complete,
determine the state of the transaction(s) associated with the canceled
resynchronization and finish it. In this example, the transaction is not prepared; so it
is aborted and then finished.
%
...
Transaction Id:
15432
...
Local Tran State:
Perceived Peer (tran) State: PPC_TRAN_STATE_PENDING
(Not finished.)
A prepare has been sent by the peer. The peer has resynchronization
responsibility towards this site.
115
Note that the gateway server does not have resynchronization responsibility so you
must explicitly finish transaction 15432.
%
ppcadmin cancel resync ORDENTRY SNALU01

%
15432 active
%
Related information
v
v
v
v
ppcadmin force xln on page 118

ppcadmin list resyncs on page 122
ppcadmin query resync on page 133
tkadmin force transaction on page 195
ppcadmin destroy conv

Purpose
Destroys an SNA conversation at the specified gateway server.
Synopsis
ppcadmin destroy conv -server server_name Conversation_Id
Arguments
-server server_name
Conversation_Id
Specifies the hexadecimal number identifying the conversation to be destroyed.
(This identifier can be obtained by using the ppcadmin list convs command.)
Description
The ppcadmin destroy conv command destroys the specified conversation between
a gateway server LU and a mainframe LU by unbinding the associated session.
When you use this command to unbind the session at the PPC gateway server,
each side of the application is notified of the resulting communications failure, and
the conversation is destroyed on both sides.
Under certain conditions, this command provides a way to free resources that are
blocked instead of using the tkadmin force transaction command to force the
transaction to finish. This is useful because forcing a transaction can damage the
transaction by causing it to abort or remain incomplete.
If a transaction is blocked because of a communications outage, there will be a
resynchronization waiting to complete. If there is not a communications outage, the
transaction is blocked waiting for the application or resource manager to respond at
a remote system. Destroying the conversation will unblock the transaction.
Destroying the conversation typically triggers a resynchronization. When the
resynchronization completes, the transaction is unblocked. The outcome of the
transaction depends on how far the transaction has progressed when the ppcadmin
destroy conv command is issued.
116
A conversation may need to be destroyed for the following reasons:

v Blocked transactions Although blocked transactions with neither
communications failures nor failures of a remote system are unlikely, they are
possible because all participants in a distributed PPC transactionLogical Unit of
Work (LUW)must agree before committing the transaction. If a transaction
involving the PPC must wait for a response from a remote application program or
resource manager, the transaction can become blocked, and you may need to
destroy the conversation.
v Blocked non-transactional conversations When the resources consumed
by a non-transactional application must be freed for use by other applications,
destroying the conversation performs operations such as the following:
Breaks communication between application programs that are consuming
system resources
Breaks communication between application programs that are inactive but
have consumed a communications resource session
Allows a normal (non-forced) shutdown of a gateway server to complete
Triggers the applications to establish new conversations that may go through
another gateway server for various reasons (including load sharing)
The ppcadmin destroy conv command creates a communications failure; if a
communications failure has occurred already, destroying the conversation has no
effect. Therefore, when a communications failure has not occurred already during
the two-phase commit and you issue the ppcadmin destroy conv command, the
command unbinds the session at the PPC gateway server and creates (or waits for
the other side to create) a resynchronization conversation. A resynchronization
conversation is a conversation that is created by an LU 6.2 transaction manager to
exchange information to ensure that the LUW states are consistent. When the
resynchronization is complete, locked resources are freed, and the log for the LUW
is updated.
The following ppcadmin commands can be used to display state information to help
determine whether destroying the conversation is an appropriate measure:
v To find conversations being handled at the gateway server, use the ppcadmin list
convs command.
v To determine the state of a conversation at the gateway server, use the
ppcadmin query conv command.
v To determine the state of transactions at the gateway server, use the ppcadmin
query luw command.
v To query the status of transactions that are awaiting resolution, use the ppcadmin
query resync command.
v To list all pending or incomplete resynchronizations, use the ppcadmin list
resyncs command.
If there is a transaction that is blocked in the PPC gateway server and there are no
associated resynchronizations waiting to complete, this means that the application
is in the middle of processing a command on the Systems Network Architecture
(SNA) conversation, and a communications failure is reported immediately when
you issue the ppcadmin destroy conv command. If the application is not in the
middle of processing a command on the SNA conversation and you issue the
ppcadmin destroy conv command, the failure is reported as a session outage when
the next command is processed on the SNA conversation.
117
The ppcadmin destroy conv command provides an alternative to using the

administrative capabilities in the local or remote SNA services to destroy the
conversation. This is useful when the PPC gateway server administrator is denied
access to the local SNA administrative application or to administrative privileges on
or access to the remote side. Typically, the ppcadmin destroy conv command is
also more convenient than the other alternatives.
Multiple conversations may be associated with a single transaction. To make sure
you are destroying the correct conversation and to make sure the necessary steps
are taken on both sides, you may need to coordinate your actions with the
administrator of the SNA host.
Because the ppcadmin destroy conv command returns immediately (before the
conversation is destroyed), you can continue to query the transaction to determine
whether additional measures (such as forcing the transaction to finish or canceling
the resynchronization) are required after the conversation is destroyed.
If the specified gateway server or SNA conversation identifier is not valid, or if there
is a remote procedure call (RPC) communications failure, the ppcadmin destroy
conv command fails and displays a message.
This command requires support from the underlying SNA services.
Examples
The following command destroys the conversation 543ab278:
%
ppcadmin destroy conv 543ab278
Related information
v
v
v
v
v
ppcadmin
ppcadmin
ppcadmin
ppcadmin
ppcadmin
list convs on page 119

list luws on page 121
list resyncs on page 122
list transactions on page 124
query conv on page 126
ppcadmin force xln

Purpose
Forces a log identifier exchange between the specified LU pair.
Synopsis
ppcadmin force xln -server server_name [-mode Mode_Name]
Executive_LU SNA_Partner_LU
Arguments
-server server_name
[-mode Mode_Name]
Specifies the mode that is used by the Systems Network Architecture (SNA)
118
service to allocate the resynchronization conversation to the remote

resynchronization transaction program. If this option is not specified, the default
mode name, SNASVCMG, is used.
Executive_LU
Specifies the name of the CICS region Logical Unit (LU).
SNA_Partner_LU
Specifies the name of the mainframe LU.
Description
The ppcadmin force xln command forces a log name exchange between the
specified pair of LUs. (Use the ppcadmin list xlns or ppcadmin list resyncs
commands to determine the LU names of the conversation partners.)
Forcing a remote LU to exchange its log identifier name with the gateway server is
similar to pinging a server. Exchanging log identifier names checks the synclevel 2
connectivity between a pair of LUs. When all the SNA sessions between a pair of
LUs go down, the synclevel syncpoint connectivity between them can be checked
outside the context of pending resynchronizations by using this command.
This command is also useful when a pending resynchronization is taking abnormally
long. Unlike the ppcadmin cancel resync command, the ppcadmin force xln
command does not introduce the potential for heuristic damage. Before canceling a
resynchronization, you should attempt to force the first phase of resynchronization
with the ppcadmin force xln command. This may allow the completion of
resynchronization, making its cancellation unnecessary.
This command does not return until the exchange is complete or the command
fails. If this command fails, it returns a return code and the gateway server sends
an audit message describing the reason for the failure.
Examples
The following example notifies the gateway server to force the CICS region LU,
ORDENTRY, and the mainframe LU, SNALU01, to exchange their log identifier
names. The default mode, SNASVCMG, is used for the resynchronization
conversation.
%
ppcadmin force xln ORDENTRY SNALU01
Related information
v
v
v
v
ppcadmin
ppcadmin
ppcadmin
ppcadmin
list resyncs on page 122

query resync on page 133
list xlns on page 125
query xln on page 135
ppcadmin list convs

Purpose
Displays a list of all active conversations.
Synopsis
ppcadmin list convs -server server_name
119
Arguments
-server server_name
Description
The ppcadmin list convs command lists the active conversations at the gateway
server. There is no guarantee that a conversation is still active after this command
has completed.
Each conversation between a CICS region and a mainframe Logical Unit (LU)
consists of two conversations at the gateway server: one between the CICS region
and the gateway server, and one between the gateway server and the mainframe
LU. This command returns information about gateway server-mainframe
conversations only.
Examples
The following command displays the active conversations at the gateway server:
%
ppcadmin list convs

total convs: 2
convId: 543ab278
Transaction Id: 15
TP name:
SUBMIT
Executive LU:
ORDENTRY --> SNA Partner LU: SNALU01
convId: 543ab279
Logical Unit of Work Id: NETWORK1.LPINV:22bf45679abc:1a
Transaction Id: 32
Global tid: 0000010d0244010135efc955246311b264070009
TP name:
QUERY
Executive LU:
ORDENTRY <-- SNA Partner LU: LPINV
Output
The following list describes the output of the ppcadmin list convs command:
v Total convs lists the number of active conversations at the gateway server.
v convId specifies the hexadecimal number identifying the conversation. For each
conversation, the following information is listed:
Logical Unit of Work Id (LUWID) specifies the Systems Network
Architecture (SNA) Logical Unit of Work (LUW). If any of the conversations
exist to SNA mainframes, the transactions on those mainframes will have this
LUW. The LUWID identifies the site that allocated the first conversation and
the unit of work. It is the SNA equivalent of a global transaction identifier. The
first component is the network-qualified LU name, the second component is
the LUW instance identifier, and the third component is the LUW sequence
number. Note that the LUW instance identifier and LUW sequence number are
hexadecimal byte streams, following mainframe conventions. If the
conversation is synclevel none or synclevel confirm, the string (null) is
returned.
120
Transaction Id is the local transaction identifier, or tid. It identifies a

transaction at this server.
Global tid is the global transaction identifier. It identifies a transaction
uniquely at any participating server.
TP name is the name of the transaction program active at the conversation.
Executive LU specifies the allocator and acceptor of the conversation. The
arrow signifies the allocator > acceptor relationship, that is, the partner
preceding the arrow allocated the conversation, and the partner to which the
arrow is pointing accepted the conversation.
If there are no active conversations at the gateway server, a message is displayed
stating that the number of active conversations is zero.
Related information
v
v
v
v
ppcadmin
ppcadmin
ppcadmin
ppcadmin
list luws
query conv on page 126
query luw on page 131
ppcadmin list luws

Purpose
Displays a list of the LUWs and their associated transaction identifiers for all
transactions active at the gateway server.
Synopsis
ppcadmin list luws -server server_name
Arguments
-server server_name
Description
The ppcadmin list luws command displays a list of the Logical Units of Work
(LUWs) for all transactions active at the gateway server. There is no guarantee that
a transaction is still active after this command has completed.
An alternative command that lists an equivalent output is the ppcadmin list
transactions command.
Examples
The following command lists all the LUWs and their associated transaction
identifiers for the transactions active at the gateway server:
%
ppcadmin list luws

Total LUWs: 3
Transaction Id: 15
121

Logical Unit of Work Id: NETWORK3.LUNANCY1:12bf45679abc:12
Transaction Id: 32
Global tid: 0000010d0244010135efc955246311b264070009
Logical Unit of Work Id: NETWORK5.LUDEBBY4:12bf45679abc:1
Transaction Id: 35
Global tid: 0000020b0145012135bcc955246311d264880009
Output
The following list describes the output of the ppcadmin list luws command:
v Total LUWs lists the number of LUWs active at the gateway server.
v Logical Unit of Work Id (LUWID) specifies the Systems Network Architecture
(SNA) LUW. If any of the conversations exist to SNA mainframes, the
transactions on those mainframes will have this LUW. The LUWID identifies the
site that allocated the first conversation and the unit of work. It is the SNA
equivalent of a global transaction identifier. The first component is the
network-qualified Logical Unit (LU) name, the second component is the LUW
instance identifier, and the third component is the LUW sequence number. Note
that the LUW instance identifier and LUW sequence number are hexadecimal
byte streams following mainframe conventions.
v Transaction Id is the local transaction identifier, or tid. It identifies a transaction
at this server.
v Global tid is the global transaction identifier. It identifies a transaction uniquely
at any participating server.
If there are no active LUWs at the gateway server, a message is displayed stating
that the number of active LUWs is zero.
Related information
v ppcadmin list transactions on page 124
v ppcadmin query luw on page 131

Purpose
Displays information about LUWs that have pending resynchronizations.
Synopsis
ppcadmin list resyncs -server server_name
Arguments
-server server_name
Description
The ppcadmin list resyncs command displays information about Logical Units of
Work (LUWs) that have pending resynchronizations.
122
Examples
The following command displays information about pending resynchronizations:
%

Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
convId:
543ab278
Executive LU:
ORDENTRY
SNA Partner LU:
SNALU02
Session Id:
f000000000000005
Output
The following list describes the output of the ppcadmin list resyncs command:
v Number of transactions with pending resynchronizations specifies the
number of LUWs with pending resynchronizations between the specified CICS
region-mainframe Logical Unit (LU) pair.
v Logical Unit of Work Id (LUWID) specifies the Systems Network Architecture
(SNA) LUW. If any of the conversations exist to SNA mainframes, the
transactions on those mainframes will have this LUW. The LUWID identifies the
site that allocated the first conversation and the unit of work. It is the SNA
equivalent of a global transaction identifier. The first component is the
network-qualified LU name, the second component is the LUW instance identifier,
and the third component is the LUW sequence number. Note that the LUW
instance identifier and LUW sequence number are hexadecimal byte streams,
following mainframe conventions.
v Transaction Id specifies the local transaction identifier, or tid. It identifies a
v Global tid is the global transaction identifier. It identifies a transaction uniquely
at any participating server.
v convId specifies the conversation identifier.
v Executive LU specifies the LU name for the CICS region application.
v SNA Partner LU specifies the LU alias for the mainframe LU.
v Conversation Correlator uniquely identifies a conversation across a pair of LUs.
This is used during the compare states phase of resynchronization.
When there is a loopback from the mainframe, multiple conversations connect
Transaction Programs (TPs) with the same LUWs in different LUs, but
resynchronization happens independently for each conversation. The
resynchronization TP uses the conversation correlator to identify uniquely the
branch of the transaction tree for which it is conducting resynchronization.
The conversation correlator is assigned to a conversation by the conversation
allocator. Since the correlators are assigned independently in different LUs, they
are qualified by their LU names. This LU name is used to uniquely qualify the
conversation correlator used during resynchronization.
v Session Id specifies a unique identifier of the session that is used by the two
communicating LUs.
If there are no resynchronizations pending at the gateway server, a message is
displayed stating that the number of transactions with pending resynchronizations is
zero.
123
Related information
v ppcadmin query resync on page 133

Purpose
Displays a list of all the transactions active at the gateway server and their
associated LUWs.
Synopsis
ppcadmin list transactions -server server_name
Arguments
-server server_name
Description
The ppcadmin list transactions command displays a list of all transactions active at
the gateway server and their associated Logical Units of Work (LUWs). There is no
guarantee that a transaction is still active after this command has completed.
An alternative command that supplies equivalent output is the ppcadmin list luws
command.
Examples
The following command lists all transactions active at the gateway server:
%

Total transactions: 3
Transaction Id: 15
Transaction Id: 32
Global tid: 0000010d0244010135efc955246311b264070009
Logical Unit of Work Id: NETWORK3.LUNANCY1:12bf45679abc:12
Transaction Id: 35
Global tid: 0000020b0145012135bcc955246311d264880009
Logical Unit of Work Id: NETWORK5.LUDEBBIE:12bf45679abc:1
Output
The following list describes the output of the ppcadmin list transactions command:
v Total transactions lists the number of transactions active at the gateway server.
v Transaction Id is the local transaction identifier, or tid. It identifies a transaction
at this server.
Global tid specifies the global transaction identifier. It identifies a transaction
124

Architecture (SNA) LUW. If any of the conversations exist to SNA mainframes,
the transactions on those mainframes will have this LUW. The LUWID
identifies the site that allocated the first conversation and the unit of work. It is
the SNA equivalent of a global transaction identifier. The first component is
the network-qualified Logical Unit (LU) name, the second component is the
LUW instance identifier, and the third component is the LUW sequence
hexadecimal byte streams, following mainframe conventions.
If there are no active transactions at the gateway server, a message is displayed
stating that the number of active transactions is zero.
Related information
v ppcadmin list luws on page 121
v ppcadmin query luw on page 131
ppcadmin list xlns

Purpose
Displays the status of the exchange of log identifier names between LU pairs that
have participated in SL2 conversations.
Synopsis
ppcadmin list xlns -server server_name
Arguments
-server server_name
Description
The ppcadmin list xlns command displays the status of log identifier name
exchanges between one or more Logical Unit (LU) pairs (LUs managed by the
gateway server and their remote LU partner) that have participated in a synclevel
syncpoint conversation. The exchange is either complete or incomplete.
The exchange will be complete for partners (gateway LU and mainframe LU) that
have participated in one or more synclevel syncpoint (SL2) conversations since the
gateway server started, or that have completed the first stage of resynchronization
processing, successfully exchanging log identifier names. The exchange will not be
complete if the partners have not initiated a conversation after a session has failed
or after the gateway server has stopped and restarted, or, if a resynchronization is
pending and the partners have not yet exchanged their log names.
If no synclevel syncpoint conversations have been allocated through the gateway
server, no LUs have exchanged log identifier names. A message stating that the
number of LU pairs is zero is displayed in this case.
125
Examples
The following command displays information about the status of all log identifier
name exchanges at the server:
%
ppcadmin list xlns

Number of LU pairs: 2
Executive LU:
EXECLU01
Executive LU:
EXECLU02
Log Identifier Name Exchange Complete: NO
Related information
v ppcadmin list resyncs on page 122
v ppcadmin query xln on page 135
ppcadmin query conv

Purpose
Displays information about the specified conversation.
Synopsis
ppcadmin query conv -server server_name convid
Arguments
-server server_name
convid
Specifies the hexadecimal number identifying the conversation. Information will
be displayed about this conversation. (This identifier is available through the
ppcadmin list convs command.)
Description
The ppcadmin query conv command displays information about the specified
conversation between the gateway server and a mainframe Logical Unit (LU).
Examples
The following command queries the conversation 543ab278:
%

convId: 543ab278
----------------------Logical Unit of Work Id: NETWORK1.LUALFRED:LUALFRED:12bf45679abc:2a
126
Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
TP name:
TRAN002FOO
SyncLevel:
Conversation Type:
Conversation State:
PPC_STATE_SEND
PPC_STATE_SEND
Session Id:
f000000000000005
Peer Information:
---------------Executive LU: ORDENTRY --> SNA Partner LU: SNALU001
Local Tran State: PPC_TRAN_STATE_PREPARED
SNA Parameters:
ORDERMODE
SNA User Id:
GatewayUser
----------------------Bytes Sent:
100
Bytes Received:
85
Error Count:
0
Number of Syncpoints: 42
Number of Backouts:
0
Output
The following list describes the output of the ppcadmin query conv command:
v convId specifies the hexadecimal number identifying the conversation about
which information is being displayed.
v Conversation Parameters specify the following information about the
conversation:
Architecture (SNA) Logical Unit of Work (LUW). If any of the conversations
exist to SNA mainframes, the transactions on those mainframes will have this
LUW. The LUWID identifies the site that allocated the first conversation and
the unit of work. It is the SNA equivalent of a global transaction identifier. The
first component is the network-qualified LU name, the second component is
the LUW instance identifier, and the third component is the LUW sequence
hexadecimal byte streams, following mainframe conventions. If the
conversation is synclevel none or synclevel confirm, the string (null) is
returned.
Transaction Id is the local transaction identifier, or tid. It identifies a
TP name is the name of transaction program to which the conversation is
allocated.
SyncLevel specifies the level of synchronization for a conversation, one of the
following:
- PPC_NONE
127
- PPC_CONFIRM
- PPC_SYNCPOINT
Conversation Type specifies one of the following types of conversations:
- PPC_BASIC specifies that the conversation is a basic conversation and that
the data is passed into and out of PPC Services without a notion of record
boundaries.
- PPC_MAPPED specifies that the conversation is a mapped conversation and
that all data is formed of logical records.
Conversation State specifies one of the following as the current state of the
conversation. For more information, refer to the state transaction table in the
Systems Application Architecture Common Programming Interface
Communications Reference.
- PPC_RESET, which is the state of a conversation when it has been created
but not yet allocated, or when it has been deallocated but the conversation
identifier has not yet been destroyed.
- PPC_SEND, which is the state in which an application can do send data,
confirm, deallocate, prepare to receive, send error, backout, or syncpoint
requests.
- PPC_RECEIVE, which is the state in which an application can do receive,
deallocate (abend), send error, request to send, or backout requests.
- PPC_DEFER_RECEIVE, which is the state in which the application can do
syncpoint (synclevel 2 conversations), confirm (synclevel 0 or 1
conversations), or flush (synclevel 0, 1, or 2 conversations) requests. If one
of these operations is successful, the conversation enters receive state.
Note that if the operation is unsuccessful, the conversation may be in some
other state.
- PPC_DEFER_DEALLOCATE, which is the state in which the application can do
syncpoint (synclevel 1 or 2 conversations) requests. If the syncpoint is
successful, the conversation is deallocated and enters reset state. If the
operation is unsuccessful, the conversation may be in some other state.
- PPC_CONFIRM, which is the state in which the application can do confirm,
deallocate (abend), or send error requests. If confirm is successful, the
conversation remains in receive state.
- PPC_CONFIRM_SEND, which is the state in which the application can do
confirm, deallocate (abend), or send error requests. If confirm is successful,
the conversation enters send state.
- PPC_CONFIRM_DEALLOCATE, which is the state in which the application can do
confirm, deallocate (abend), or send error requests. If confirm is successful,
the conversation enters deallocate state. The application should deallocate
the conversation locally.
- PPC_SYNCPOINT, which is the state in which an application can respond to a
syncpoint request.
- PPC_SYNCPOINT_SEND, which is the state in which an application can respond
to a syncpoint request and then enter send state if the syncpoint is
successful.
- PPC_SYNCPOINT_DEALLOCATE, which is the state in which an application can
respond to a syncpoint request and then deallocate the conversation locally
if the syncpoint is successful.
- PPC_DEALLOCATE, which is the state in which an application should
deallocate the conversation using the PPC_DEALLOCATE_LOCAL option.
128
- PPC_BO_REQUIRED, which is the state in which the remote application has

requested a backout, but the local application has not yet backed out.
Last Syncpoint State specifies the state of the conversation at the time of
the previous syncpoint (the most recent syncpoint prior to commencement of
the current logical unit of work). See the conversation states described for
Conversation State.
The next field under Conversation Parameters specifies that the conversation
is an SNA conversation.
Conversation Correlator uniquely identifies a conversation across a pair of
LUs. This is used during the Compare States phase of resynchronization.
TPs with the same LUWs in different LUs, but resynchronization happens
independently for each conversation. The resynchronization TP uses the
conversation correlator to identify uniquely the branch of the transaction tree
for which it is conducting resynchronization.
allocator. Since the correlators are assigned independently in different LUs,
they are qualified by their LU names. This LU name is used to uniquely
qualify the conversation correlator used during resynchronization.
Session Id specifies a unique identifier of the session that is used by the two
communicating LUs.
v Peer Information specifies the following information about the peers for this
conversation:
The first field specifies the allocator and acceptor of the conversation. The
arrow signifies the allocator > acceptor relationship, that is, the partner
preceding the arrow allocated the conversation, and the partner to which the
arrow is pointing accepted the conversation.
Local Tran State specifies the transaction state of the conversation on the
gateway server. If the peer is not in one of these states, no state information
is displayed. This can be one of the following:
- PPC_TRAN_STATE_ACTIVE: Transaction is currently active at the peer. (Not
yet resolved.)
- PPC_TRAN_STATE_PREPARING: A prepare has been sent to the peer. This site
has resynchronization responsibility towards the peer.
- PPC_TRAN_STATE_PREPARED: Peer is prepared and awaiting resolution of the
transaction. This site has resynchronization responsibility towards the peer.
- PPC_TRAN_STATE_FINISHED: Transaction has finished at the peer.
- PPC_TRAN_STATE_ABORTED: Peer has sent a backout and is waiting for
backout response.
- PPC_TRAN_STATE_NONE: The application at the peer has not yet participated
in the transaction.
- PPC_TRAN_STATE_PENDING: A prepare has been sent by the peer. The peer
has resynchronization responsibility towards this site.
- PPC_TRAN_STATE_COMMITTED: Transaction has committed at the peer. (Not
finished.)
- PPC_TRAN_STATE_IMPLIED_FORGET_PENDING: Transaction has committed at
the peer, and an implied forget message is expected from the peer. (Not
finished.)
129
Perceived Peer (Tran) State specifies the transaction state of the

conversation the gateway server perceives its peer to be in. If the peer is not
in one of these states, no state information is displayed. This can be one of
the following:
- PPC_TRAN_STATE_ACTIVE: Transaction is currently active at the peer. (Not
yet resolved.)
- PPC_TRAN_STATE_PREPARING: A prepare has been sent to the peer. This site
backout response.
in the transaction.
finished.)
- PPC_TRAN_STATE_IMPLIED_FORGET_PENDING: Transaction has committed at
the peer, and an implied forget message is expected from the peer. (Not
finished.)
v SNA Parameters specify the following information about the parameters for this
conversation specific to the SNA communication package:
SNA Mode Name specifies the name of the mode used to define the
characteristic of this conversations session.
SNA Security Type specifies the security level required by the SNA partner.
The administrator for the SNA partner determines the type of security required
for the applications (transaction programs) at its LU.
SNA User Id specifies the identity of the user invoking the SNA application.
The administrator for the SNA partner usually determines the users who can
access the SNA partner.
v Conversation Statistics specify the following statistics about this conversation:
Bytes Sent specifies the number of bytes sent by the gateway server.
Bytes Received specifies the number of bytes received by the gateway server.
Error Count specifies the number of errors logged for this conversation.
Number of Syncpoints specifies the number of successful syncpoints on this
conversation.
Number of Backouts specifies the number of successful backouts on this
conversation.
Related information
v
v
v
v
130
ppcadmin
ppcadmin
ppcadmin
ppcadmin
list convs on page 119

list luws on page 121
query luw on page 131
ppcadmin query luw

Purpose
Displays information about the specified LUW.
Synopsis
ppcadmin query luw -server server_name LUW_Id
Arguments
-server server_name
LUW_Id
Specifies the Logical Unit of Work Identifier (LUWID) identifying the transaction
about which information is to be displayed. (This identifier is available through
the ppcadmin list luws command.)
Description
The ppcadmin query luw command displays information about the specified Logical
Unit of Work (LUW). The ppcadmin list luws command displays the LUW_Id of all
active LUWs (transactions) at the gateway server.
Examples
The following command displays information about the transactions identified with
the NETWORK1.LUALFRED:12bf45679abc:2a LUW:
%
ppcadmin query luw NETWORK1.LUALFRED:12bf45679abc:2a

Logical Unit of Work Id:
Total transactions:
NETWORK1.LUALFRED:12bf45679abc:2a
2
Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
convId:
543ab278
Executive LU:
ORDENTRY
Session Id:
f000000000000005
Peer has sent a Backout and is waiting for Backout response.
Transaction Id:
35
Global tid:
0000020b0145012135bcc955246311d264880009
convId:
573ab478
Executive LU:
EXECLU02
Conversation Correlator: 34 74 04 81 06 00 00 05
Session Id:
f0 00 00 00 00 00 00 02
Transaction is prepared and awaiting resolution at this site. (Not finished.)
A prepare has been sent to the peer. This site has resynchronization
responsibility towards the peer.
131
Output
The following list describes the output of the ppcadmin query luw command:
v Transaction Id specifies the local transaction identifier, or tid. It identifies a
v Global tid specifies the global transaction identifier. It identifies a transaction
v convId specifies the conversation identifier.
v Executive LU specifies the Logical Unit (LU) name for the CICS region
application.
v Conversation Correlator uniquely identifies a conversation across all LUs. This
is used during the Compare States phase of resynchronization.
Transaction Programs (TPs) with the same LUWs in different LUs, but
resynchronization happens independently for each conversation. The
resynchronization TP uses the conversation correlator to identify uniquely the
branch of the transaction tree for which it is conducting resynchronization.
allocator. Since the correlators are assigned independently in different LUs, they
are qualified by their LU names. This LU name is used to uniquely qualify the
conversation correlator used during resynchronization.
v Session Id specifies a unique identifier of the session that is used by the two
communicating LUs.
v The final field lists a description of the state of the local transaction at the
gateway and the transaction state the gateway server perceives the peer to be
in, based on messages received by the peer. (See ppcadmin query resync on
page 133 for a description of transaction states and perceived peer transaction
states.) The description for the local transaction state is one of the following:
Transaction is currently active at this site. (Not yet resolved.)
Transaction is in the process of preparing at this site. This site is awaiting
prepare responses from agent sites.
Transaction has finished at this site.
The application at this site has not yet participated in the transaction.
Transaction has committed at this site. (Not finished.)
This site is ready to abort the transaction.
An Implied Forget Message is pending from the last agent initiator. This site
has resynchronization responsibility towards the last agent initiator.
The description of the perceived peer transaction state is one of the following. If
the peer is not in a known state, nothing is displayed for the peers transaction
state.
Transaction is currently active at the peer. (Not yet resolved.)
Peer is prepared and awaiting resolution of the transaction. This site has
Transaction has finished at the peer.
132
Peer has sent a backout and is waiting for backout response.

The application at the peer has not yet participated in the transaction.
A prepare has been sent by the peer. The peer has resynchronization
responsibility towards this site.
Transaction has committed at the peer. (Not finished.)
Related information
v ppcadmin list luws on page 121
v ppcadmin list transactions on page 124
ppcadmin query resync

Purpose
Displays information about pending resynchronizations between the specified LUs.
Synopsis
ppcadmin query resync -server server_name Executive_LU SNA_Partner_LU
Arguments
-server server_name
Executive_LU
Specifies the name of the CICS region Logical Unit (LU) participating in the
incomplete transaction. (This CICS region LU is available via the ppcadmin list
resyncs command.)
SNA_Partner_LU
Specifies the name of the mainframe LU participating in the incomplete
transaction. (This mainframe LU is also available via the ppcadmin list resyncs
command.)
Description
The ppcadmin query resync command displays information about Logical Units of
Work (LUWs) that have pending resynchronizations between the specified pair of
logical units. Both the CICS region LU and the mainframe LU must be specified to
identify the subset of all interrupted transactions. This command only displays the
resynchronizations pending between the specified LUs. There can be other pending
resynchronizations pending between other pairs of LUs. Use the ppcadmin list
resyncs command to obtain a list of all pending resynchronizations at the gateway
server.
Examples
The following command displays information about the resynchronization pending
for a transaction between the CICS region LU ORDENTRY and the mainframe LU
SNALU01:
%

133

Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
convId:
543ab278
Session Id:
f000000000000005
SNA Mode Name:
BLANKMOD
Local Tran State:
Peer Tran State:
Output
The following list describes the output of the ppcadmin query resync command:
v Exchange Log Name Complete specifies if the partners have completed
exchanging the log name required for the resynchronization.
v Number of transactions with pending resynchronizations specifies the
number of transactions with pending resynchronizations between the specified
CICS region-mainframe LU pair.
v Executive LU specifies the LU name for the CICS region application.
v For each transaction with a pending resynchronization, the following information
is displayed:
Architecture (SNA) LUW. If any of the conversations exist to SNA mainframes,
the transactions on those mainframes will have this LUW. The LUWID
identifies the site that allocated the first conversation and the unit of work. It is
the SNA equivalent of a global transaction identifier. The first component is
the network-qualified LU name, the second component is the LUW instance
identifier, and the third component is the LUW sequence number. Note that
the LUW instance identifier and LUW sequence number are hexadecimal byte
streams, following mainframe conventions.
Transaction Id specifies the local transaction identifier, or tid. It identifies a
convId specifies the conversation identifier.
Conversation Correlator uniquely identifies a conversation across all LUs.
This is used during the Compare States phase of resynchronization.
TPs with the same LUWs in different LUs, but resynchronization happens
independently for each conversation. The resynchronization TP uses the
conversation correlator to uniquely identify the branch of the transaction tree
for which it is conducting resynchronization.
allocator. Since the correlators are assigned independently in different LUs,
they are qualified by their LU names. This LU name is used to uniquely
qualify the conversation correlator used during resynchronization.
Session Id specifies a unique identifier of the session that is used by the two
communicating LUs.
134
SNA Mode Name specifies the mode used for this conversation.
Local Tran State specifies the transaction state the gateway server is in. This
can be one of the following:
- PPC_TRAN_STATE_ACTIVE: Transaction is currently active at this site. (Not yet
resolved.)
- PPC_TRAN_STATE_PENDING: Transaction is in the process of preparing at this
site. This site is awaiting prepare responses from agent sites.
- PPC_TRAN_STATE_PREPARED: Transaction is prepared and awaiting resolution
at this site. (Not finished.)
- PPC_TRAN_STATE_FINISHED: Transaction has finished at this site.
- PPC_TRAN_STATE_ABORTED: This site is about to abort the transaction.
- PPC_TRAN_STATE_NONE: The application at this site has not yet participated in
the transaction.
- PPC_TRAN_STATE_COMMITTED: Transaction has committed at this site. (Not
finished)
- PPC_TRAN_STATE_BO_REQUIRED: This site is ready to abort the transaction.
- PPC_TRAN_STATE_IMPLIED_FORGET_PENDING: An Implied Forget Message is
pending from the last agent initiator. This site has resynchronization
responsibility towards the last agent initiator.
Peer Tran State specifies the transaction state of the conversation the
gateway server perceives its peer to be in. If the peer is not in one of these
states, no state information is displayed. This can be one of the following:
- PPC_TRAN_STATE_ACTIVE: Transaction is currently active at the peer. (Not yet
resolved.)
- PPC_TRAN_STATE_PENDING: A prepare has been sent to the peer. This site
backout response.
in the transaction.
finished.)
The final field lists a description of the state of the local transaction at the
gateway and the transaction state the gateway server perceives the peer to
be in, based on messages received by the peer. (See above for a description
of transaction states and perceived peer transaction states.)
Related information
ppcadmin query xln

Purpose
Displays the status of the exchange of log identifier names between the specified
LU pair.
135
Synopsis
ppcadmin query xln -server server_name Executive_LU SNA_Partner_LU
Arguments
-server server_name
Executive_LU
Specifies the name of the CICS region Logical Unit (LU). (This CICS region LU
is available via the ppcadmin list xlns command.)
SNA_Partner_LU
Specifies the name of the mainframe LU. (This mainframe LU is also available
via the ppcadmin list xlns command.)
Description
The ppcadmin query xln command displays the status of the exchange of log
identifier names between a specified pair of LUs: the LU managed by the gateway
server and the mainframe LU. The exchange is either complete or incomplete.
The exchange will be complete for partners (gateway LU and mainframe LU) that
have participated in synclevel syncpoint (SL2) conversation since the gateway
server started, or that have completed the first stage of resynchronization
processing, successfully exchanging log identifier names. The exchange will not be
complete if the partners have not initiated a conversation after a session has failed
or after the gateway server has stopped and restarted, or, if a resynchronization is
pending and the partners have not yet exchanged their log names.
If the LU pair have not participated in a synclevel syncpoint conversation, they have
not exchanged log identifier names. A message stating that the number of LU pairs
is zero is displayed in this case.
Examples
The following command displays the status of the log identifier name exchange
between the CICS region LU, ORDENTRY, and the mainframe LU, SNALU01:
%
ppcadmin query xln ORDENTRY SNALU01

Executive LU:
EXECLU01
Related information
v ppcadmin list xlns on page 125
136

The sfsadmin commands are used to administer an SFS server. The sfsadmin
commands can be grouped by task, as shown in the following list:
v Managing and displaying information about servers
sfsadmin list ofds on page 151
sfsadmin query ofd on page 154
sfsadmin query server on page 157
sfsadmin list lvols on page 158
sfsadmin query lvols on page 159
sfsadmin enable server on page 158
sfsadmin acquire lvol on page 160
sfsadmin release lvols on page 162
sfsadmin add lvol on page 163
v Getting information on files
sfsadmin query filelock on page 164
sfsadmin query tranlock on page 166
sfsadmin create clusteredfile on page 141
sfsadmin create relativefile on page 143
sfsadmin create sequentialfile on page 145
sfsadmin list files on page 146
sfsadmin destroy file on page 147
sfsadmin empty file on page 148
sfsadmin query file on page 149
sfsadmin rename file on page 140
sfsadmin export file on page 149
sfsadmin import file on page 149
sfsadmin query export on page 157
v Performing other operations on files
sfsadmin copy file on page 138
sfsadmin expand file on page 139
sfsadmin rename file on page 140
sfsadmin reorganize file on page 140
sfsadmin terminate ofd on page 156
v Creating, deleting, and performing other operations on indices
sfsadmin add index on page 168
sfsadmin delete index on page 170
sfsadmin deactivate index on page 171
sfsadmin rebuild index on page 172
sfsadmin query index on page 173
sfsadmin expand index on page 175
sfsadmin rename index on page 174
sfsadmin reorganize file on page 140
137
sfsadmin copy file

Purpose
Copies the specified file and all of its indices.
Synopsis
sfsadmin copy file -server server_name source_file target_file
[-indices number_of_indices {{index_name [-itargetvolume index_target_volume]}...}]
Arguments
-server server_name
CICS_TK_SFS_SERVER.
source_file
Specifies the name of the file to be copied to target_file.
target_file
Specifies the name of the file to be created by copying source_file.
Specifies the name of the volume on which the new file will reside. If the
-targetvolume option is not specified, the file is copied to the volume on which
the original file (source_file) resides.
[-indices number_of_indices {{index_name [-itargetvolume
index_target_volume]}...}]
Specifies the number and names of the secondary indices to be copied to the
new file. (By default, the primary index and all secondary indices of a file are
automatically copied to the volume where the primary area of the target file
resides.) Specify the number of indices to be copied as number_of_indices and
their names as index_name. If number_of_indices is 0, no secondary indices
are copied.
You can optionally specify the volume to which a secondary index is copied
using the -itargetvolume option. If the -itargetvolume option is not specified,
the index is copied to the volume where the primary area of the target file
resides.
Description
The sfsadmin copy file command creates a copy of the specified file with identical
file, record, and primary index characteristics. The issuer of the copy command
receives all permissions on the created file. The new file, which has the same
contents as the original source file, is managed by the same file server as that
source file. By default, the file and all of its indices are copied to the volume on
which the original file resides. To copy the file to a different volume, specify the
-targetvolume option. To selectively copy a secondary index, specify the -indices
option.
Examples
In the following example, MerchandiseOrders resides on sfsVol1. The command
copies the file MerchandiseOrders to Orders, and places Orders on the volume
sfsVol3.
138
sfsadmin copy file MerchandiseOrders Orders -targetvolume sfsVol3
The next command copies the file MerchandiseOrders to Orders. Only one
secondary index (itemIndex) is copied; the index is placed on the volume sfsVol4.
% sfsadmin copy file MerchandiseOrders Orders -indices 1 itemIndex /
-itargetvolume sfsVol4
Related information
v sfsadmin expand file
v sfsadmin rename file on page 140
v sfsadmin reorganize file on page 140
sfsadmin expand file

Purpose
Allocates more disk space for the primary area of the specified file
Synopsis
sfsadmin expand file -server server_name file_name number_of_pages
Arguments
-server server_name
CICS_TK_SFS_SERVER.
file_name
Specifies the name of the file to be expanded.
number_of_pages
Specifies the number of pages of disk space to be added. The size of a page is
4096 bytes.
Description
The command allocates more disk space to the primary area of the specified file.
Disk space to be allocated is expressed in pages. Note that the amount of disk
space allocated may not exactly equal the expansion request. This is because the
SFS rounds expansion requests up to the nearest convenient value.
Examples
The following command allocates 500 additional pages of disk space to the file
Inventory:
%
sfsadmin expand file Inventory 500
Related information
v sfsadmin copy file on page 138
139
sfsadmin rename file

Purpose
Renames the specified file.
Synopsis
sfsadmin rename file -server server_name file_name new_file_name
Arguments
-server server_name
CICS_TK_SFS_SERVER.
file_name
Specifies the name of the file to be renamed.
new_file_name
Specifies the new name of the file.
Description
The sfsadmin rename file command replaces an existing file name with a new file
name. The physical location of the file remains the same.
Examples
The following command renames the file Inventory to Inv:
%
sfsadmin rename file Inventory Inv
Privilege Required
CICS_TK SFS administer (A) and exclusive open (E) permissions on the file.
Related information
v
v
v
v
v
v
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
copy file on page 138

destroy file on page 147
empty file on page 148
expand file on page 139
list files on page 146
query file on page 149
sfsadmin reorganize file

Purpose
Reorganizes the records of an entry-sequenced (sequential) file in order to reclaim
space.
Synopsis
sfsadmin reorganize file -server server_name file_name [-indices]
140
Arguments
-server server_name
CICS_TK_SFS_SERVER.
file_name
Specifies the name of the file to be reorganized.
[-indices]
Rebuilds the active secondary indices. If the -indices option is not specified,
the secondary indices are marked inactive.
Description
The command reorganizes the primary area of an entry-sequenced file, and if the
-indices option is specified, rebuilds all active secondary indices. An
entry-sequenced file does not automatically reclaim space when its records are
modified or deleted. The file must be reorganized in order to reclaim space. The
records are assigned new entry sequence numbers (ESNs).
Examples
The following command reclaims space in the entry-sequenced file
MerchandiseOrders and rebuilds its active secondary indices:
%
sfsadmin reorganize file MerchandiseOrders -indices
Related information
v sfsadmin expand file on page 139
|
sfsadmin create clusteredfile
Purpose
Creates a new clustered file.
|
|
|
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
Specifies the name of the file to be created.
|
|
|
|
number_of_fields {{field_name field_type_etcetera}...}

Specifies the record format of the file. Specify the number of fields per record
as number_of_fields. For each field, specify the name of the field as field_name
and its type as field_type_etcetera. Possible field types include: unsignedInt16,
sfsadmin create clusteredfile -server server_name file_name

primary_index [-unique] number_of_index_fields {{field_name [-descending]}...}
volume [-preallocate number_of_pages] [-recordlimit number_of_records]
141
signedInt16, unsignedInt32, signedInt32, unsignedInt64, signedInt64, float,

double, timestamp, decimal field_size, string field_size, byteArray field_size,
varLenByteArray field_size, shortVarLenByteArray field_size, nlsString
field_size. Where noted, you must specify field_size. When specifying record
fields, you must specify fixed-length fields before variable-length fields. When
strings of the type nlsString are used as index fields, the collating sequence is
determined by the value of the -c option on the sfs command line. If that option
is not specified, any field of nlsString type is treated as an invalid type.
|
|
|
|
|
|
|
|
|
|
primary_index
Specifies the name of the primary index of the new clustered file.
|
|
|
[-unique]
Specifies that key values for this index must be unique. If the -unique option is
not specified, duplicate key values are allowed for the index.
|
|
|
|
|
|
number_of_index_fields {{field_name [-descending]}...}

Specifies the number of fields in the new index and their names. Specify the
number of fields in the index as number_of_index_fields. For each field, specify
the name of the field as field_name. The option -descending specifies that the
field will be sorted in descending order. If the -descending option is not
specified, fields are sorted in ascending order.
|
|
volume
Specifies the name of the volume for the newly created file.
|
|
|
|
[-preallocate number_of_pages]
Specifies the number of pages to be reserved for the file. The size of a page is
4096 bytes. If the -preallocate option is not specified, the value of
number_of_pages is 0.
|
|
|
[-recordlimit number_of_records]
Specifies the limit on the number of records the file can contain. If -recordlimit
is not specified, the record limit for clustered files is 264-10.
Description
|
|
|
|
|
The sfsadmin create clusteredfile command creates a clustered file. Clustered

files are useful for applications that need to access records based on the value of a
specific field or fields, and not on physical placement of the records. The primary
index of a clustered file is based on any field or combination of fields specified by
the user when the file is created.
|
|
|
|
|
|
The records in clustered files can have fixed- or variable-length fields. When a
record in a clustered file is updated, the new record can be any length, as long as it
does not exceed the maximum record size specified when the file was created. The
disk space allocated to a record is freed for use when the record is deleted or when
the record update makes the record smaller. The SFS automatically reclaims the
freed space.
|
|
|
|
|
characters and must follow these rules: v
v File names cannot contain the slash (/) character, and must be less than or equal
to 254 characters.
142
Examples
|
|
|
|
|
|
|
|
|
|
The command in the following example creates a clustered file named Accounts,
with records that contain the fields customerName, accountNum, creditRating,
and accountBalance. The file has a primary index (accountIndex) with one key
field (accountNum). The file is created on volume sfsVol1.
Privilege Required
CICS_TK SFS create (C) permission on the server.
|
|
|
Related Information
|
|
% sfsadmin create clusteredfile Accounts 4 \

customerName string 64 \
accountNum unsignedInt32 \
creditRating unsignedInt32 \
accountBalance signedInt32 \
accountIndex 1 accountNum sfsVol1
v sfsadmin create relativefile

v sfsadmin create sequentialfile on page 145
sfsadmin create relativefile
Purpose
Creates a new relative file.
|
|
|
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
|
|
|
|
|
|
|
|
|
|
|
|

and its type as field_type_etcetera. Possible field types include: unsignedInt16,
signedInt16, unsignedInt32, signedInt32, unsignedInt64, signedInt64, float,
double, timestamp, decimal field_size, string field_size, byteArray field_size,
varLenByteArray field_size, shortVarLenByteArray field_size, nlsString
field_size. Where noted, you must specify field_size. When specifying record
fields, you must specify fixed-length fields before variable-length fields. When
strings of the type nlsString are used as index fields, the collating sequence is
determined by the value of the -c option on the sfs command line. If that option
is not specified, any field of nlsString type is treated as an invalid type.
|
|
primary_index
Specifies the name of the primary index of the new relative file.
sfsadmin create relativefile -server server_name file_name

primary_index rsn_field_name volume_name [-preallocate number_of_pages]
143
|
|
|
rsn_field_name
Specifies the name of the field containing the relative slot number (RSN) of the
record. This field must be of type unsignedInt32.
|
|
volume_name
|
|
|
|
|
|
|
|
|
Specifies the limit on the number of records the file can contain. If -recordlimit
is not specified, the record limit for clustered files is 232-10.
Description
|
|
|
|
|
The sfsadmin create relativefile command creates a relative file. Relative files are
useful for applications that access records directly by slot number. The primary
index of a relative file is based on the RSN, the number of the slot occupied by the
record. Unlike entry sequence numbers (ESNs), the RSN is part of the record itself
(it is the value of the RSN field).
|
|
|
|
The records in a relative file are fixed-length slots, with variable-length records.
Each record can have fixed- or variable-length fields. When a record in a relative
file is updated, the new record can be any length as long as it does not exceed the
maximum record size specified when the file was created.
|
|
|
|
The disk space allocated to a record in a relative file is freed for use when the
record is deleted or when an update makes the record smaller. However, space is
not automatically reused. It can be reused when the SFS inserts a new record into
the empty slot.
|
|
|
|
|
to 254 characters.
Examples
|
|
|
|
|
|
|
|
|
|
|
|
The command in the following example creates a relative file named Inventory with
records that contain the fields productName, quantity, price, stockNum,
vendorName, and comments. The primary index of this file is stockIndex, and the
value of the stockNum field will be used as the RSN. The file is created on volume
sfsVol3.
% sfsadmin create relativefile Inventory 6 \
productName string 20 \
quantity unsignedInt32 \
price unsignedInt32 \
stockNum unsignedInt32 \
vendorName string 16 \
comments varLenByteArray 50 stockIndex stockNum sfsVol3
144
Privilege Required
CICS_TK SFS create (C) permission on the server
|
|
|
Related Information
|
|
v sfsadmin create clusteredfile on page 141

v sfsadmin create sequentialfile
sfsadmin create sequentialfile
Purpose
Creates a new sequential file.
|
|
|
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
|
|
|
|
|
|
|
|
|
|
|
|
|

(which can be up to 32 characters long) and its type as field_type_etcetera.
Possible field types include: unsignedInt16, signedInt16, unsignedInt32,
signedInt32, unsignedInt64, signedInt64, float, double, timestamp, decimal
field_size, string field_size, byteArray field_size, varLenByteArray field_size,
shortVarLenByteArray field_size, nlsString field_size. Where noted, you must
specify field_size. When specifying record fields, you must specify fixed-length
fields before variable-length fields. When strings of the type nlsString are used
as index fields, the collating sequence is determined by the value of the -c
option on the sfs command line. If that option is not specified, any field of
nlsString type is treated as an invalid type.
|
|
primary_index
Specifies the name of the primary index of the new sequential file.
|
|
volume_name
|
|
|
|
|
|
|
Specifies the limit on the number of records that can be inserted in the file. If
-recordlimit is not specified, the record limit for sequential files is 236-10.
sfsadmin create sequentialfile -server server_name file_name

primary_index volume_name
[-preallocate number_of_pages] [-recordlimit number_of_records]
145
Description
|
|
|
|
|
The sfsadmin create sequentialfile command creates a file whose records are
organized sequentially. The records in an SFS entry-sequenced file are stored in
the order in which they were inserted in the file; new records are always appended
to the end of the file. Entry-sequenced files are useful for keeping time-sequenced
event records, such as log files or audit trails.
|
|
|
|
The primary index of an entry-sequenced file is based on entry sequence numbers

(ESNs), which correspond to the order in which the records were inserted in the file.
The SFS generates ESNs when records are inserted; they are not part of the
record itself. ESNs cannot be set or modified by administrators or applications.
|
|
|
The records in entry-sequenced files can have fixed- or variable-length fields. When
an existing record of variable length is updated, the size of the new record cannot
exceed the size required by the original record.
|
|
|
|
|
to 254 characters.
Examples
|
|
|
|
|
|
|
|
|
|
The command in the following example creates an entry-sequenced file named

MerchandiseOrders with records that contain the fields customerName,
orderNum, date, itemNum, and quantity. The primary index is ordersIndex. The
file is created on volume sfsVol2.
Privilege Required
CICS_TK SFS create (C) permission on the server
|
|
Related Information
% sfsadmin create sequentialfile MerchandiseOrders 5 \

customerName string 64 \
orderNum unsignedInt32 \
date timestamp \
itemNum unsignedInt32 \
quantity unsignedInt32 ordersIndex sfsVol2
v sfsadmin create relativefile on page 143

v sfsadmin create clusteredfile on page 141
|
|
|
sfsadmin list files
Purpose
Displays the names of all files managed by a specified server.
|
|
Synopsis
sfsadmin list files -server server_name
146
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
Description
|
|
The sfsadmin list files command displays the names of all files managed by a
specified server.
Examples
|
|
|
|
|
The following command displays the names of all files managed by the server:
Privilege Required
CICS_TK SFS query (Q)permission on the server.
|
|
|
|
Related Information
|
|
|
|
|
% sfsadmin list files

Files:
Inventory
Accounts
v
v
v
v
v
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin

destroy file
empty file on page 148
query file on page 149
sfsadmin destroy file
Purpose
Removes the specified file and its indices.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
Specifies the name of the file to be removed.
Description
|
|
|
The sfsadmin destroy file command removes the specified file and its indices. All
disk space allocated to the file and its associated indices is reallocated. The file is
deleted and cannot be restored.
sfsadmin destroy file -server server_name file_name
147
Examples
|
|
The following command removes the file Inventory:
Privilege Required
|
|
|
|
|
|
Related Information
|
|
sfsadmin destroy file Inventory

v sfsadmin empty file
v sfsadmin query file on page 149
sfsadmin empty file
Purpose
Removes the contents of the specified file, leaving the record format intact.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
Specifies the name of the file to be emptied.
|
|
|
|
[-deallocate]
Deallocates the storage currently reserved for the files primary and secondary
areas. If the -deallocate option is not specified, the reserved space for the file
remains allocated.
Description
|
|
|
The sfsadmin empty filecommand removes contents of the specified file, leaving
its record format intact. The original contents cannot be restored. The file can be
used to enter new records of the same format.
Examples
|
|
The following command removes the contents of the file Accounts:
Privilege Required
CICS_TK SFS administer (A) and exclusive open (E) permissions on file.
sfsadmin empty file -server server_name file_name [-deallocate]
148
sfsadmin empty file Accounts
|
|
|
|
|
|
|
|
|
|
|
|
Related Information
v
v
v
v
v
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin

destroy file on page 147
query file
rename file on page 140
sfsadmin export file

Refer to section Importing and exporting files on page 77
sfsadmin import file

sfsadmin query file
Purpose
Displays status and storage information about a file.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
Specifies the name of the file about which information is requested.
Description
|
|
|
|
|
The sfsadmin query file command displays status and storage information about a
file, including;
v The file name and type of file
v The name, data type, and size of each record field
v The names and keys of the primary index
v The names of the secondary indices
v The maximum and current number of records in the file
|
|
|
This information is not consistent throughout the transaction; that is, the data may
reflect incomplete transactions. For example, the number of records displayed may
include records that have been inserted but not yet committed.
Examples
|
|
|
The following command displays information about the relative file Inventory. The
files primary index orders the records by stock number. The file has one secondary
index named productNameIndex.
|
|
sfsadmin query file -server server_name file_name
149
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
% sfsadmin query file

File organization: relative
Record fields:
Name: stockNum, Type: unsignedInt32
Name: quantity, Type: unsignedInt32
Name: price, Type: unsignedInt32
Name: productName, Type: string, Size: 20
Name: vendorName, Type: string, Size: 16
Name: comments, Type: varLenByteArray, Size: 50
Primary index name: stockNumIndex
Index fields:
Name: stockNum, Ordering: ascending
Volume: sfsDataVol, Allocated pages: 8, Utilized pages: 1
Max number of records: 500
Number of records: 300
File state: file OK
Creation time: Tue Dec 7 11:33:05 1993
Last read time: Tue Dec 7 11:33:05 1993
Last write time: Tue Dec 7 11:34:22 1993
Last administer time: Tue Dec 7 11:33:06 1993
Secondary indices:
productNameIndex
Output
The following list explains the output of the sfsadmin query file command:
v File name lists the name of the file about which information is being displayed.
v File organization specifies the type of the file.
v For each record field, the output provides the following information.
Name specifies the name of the record field.
Type specifies the field type. See sfsadmin create clusteredfile for a
complete list of possible field types.
|
|
|
|
|
|
|
|
|
|
v
v
|
|
|
|
|
|
v
v
|
|
|
|
|
|
|
|
|
v
v
v
v
v
v
v
v
|
|
150
Size specifies the length of the field in bytes, if this information is not implicit
in the field type.
Primary index name lists the name of the files primary index.
For each index field, the output provides the following information.
Name specifies the name of the index field.
Ordering specifies the method of sorting applied to the field. Possible values
are ascending and descending.
Volume lists the volume on which the file resides.
Allocated pages specifies the number of pages allocated on the volume for the
file.
Utilized pages lists the number of pages currently used by the file.
Max number of records lists the maximum number of records the file can hold.
Number of records specifies the number of records the file currently holds.
File state indicates the state of the file. Possible values are file OK and file
damaged. If the file is damaged, depending on whether the primary or secondary
indices are damaged, you may or may not be able to recover the file.
Creation time specifies the date and time when the file was created.
Last read time specifies when data was last read from the file.
Last write time specifies when data was last written to the file.
Last administer time specifies when an administrative command was last
executed on the file.
|
|
v Secondary indices lists the names of any secondary indices associated with the
file.
Privilege Required
CICS_TK SFS query (Q) permission on the file.
|
|
|
|
|
Related Information
|
|

v sfsadmin destroy file on page 147
v sfsadmin empty file on page 148
v sfsadmin list files on page 146
sfsadmin list ofds

Purpose
Displays information about open file descriptors (OFDs) managed by the specified
server.
Synopsis
sfsadmin list ofds -server server_name [-brief]
Arguments
-server server_name
CICS_TK_SFS_SERVER.
[-brief]
Requests an abbreviated display of OFD information.
Description
The command displays information about the open file descriptors (OFDs) managed
by a server. The -brief option displays only the server identification number for each
OFD and the file name.
Examples
The following command displays information about the OFDs managed by the
server /.:/cics/sfs/mysfs. Note that the Inventory file is being accessed by several
OFDs.
%
sfsadmin list ofds -server /.:/cics/sfs/mysfs
Ofd id: 33
Owner: (null)
Open time: Mon Oct 18 11:12:04 1993
Transaction id: 0
Number of rpcs: 139
Authority:
read file
151
inquire file
Auto close: no
Label: (null)
Ofd id: 38
Owner: (null)
Number of rpcs: 1
Authority:
insert file
inquire file
Isolational level: serializability
Auto close: yes
Duplicate detection: current index
Label: (null)
Ofd id: 39
File name: Accounts
Owner: (null)
Number of rpcs: 35
Authority:
read file
insert file
update file
delete file
inquire file
exclusive file
administer file
Isolational level: cursor stability
Auto close: no
Label: (null)
Ofd idle timeout policy: sfs_preserveOfdOnConflict
Output
The following list explains the elements in the output of the command:
v
v
v
v
152
Ofd id is the identification number used by the server for the OFD.
File name is the name of the SFS file.
Owner indicates the owner of the file.
Open time indicates the time that the file was opened.

v Number of rpcs refers to the number of RPCs completed using this OFD.
file at a time.
a permission to perform an operation on a file. For example, a client may have
v Isolation level refers to the extent to which data being accessed by the OFD
is protected from concurrent access by other users. An isolation level is the
degree to which operations on a file are isolated from other operations on the
same file. The isolation level determines the locking policy used.
using this OFD will take to complete before timing out.
v Auto close refers to whether or not a transactional OFD will be automatically
closed when the transaction is resolved. If the OFD is nontransactional, this field
will be no (nontransactional OFDs must be closed manually).
v Duplicate detection specifies the level at which the server detects duplicate
keys in non-unique indexes.
v Operational force applies only to nontransactional OFDs and refers to whether
operation.
v Label is the user-defined string for the OFD.
v Open transaction id is the identification number of the transaction that holds the
v Ofd idle timeout is the time, in seconds, that an OFD may be permitted to be
idle while waiting for an SFS call. If this time period has elapsed, and another
OFD requests a lock held by the idle OFD, the transaction associated with the
idle OFD is terminated, closing the OFD and releasing the lock.
v Ofd idle timeout policy specifies the actions to be taken when the OFD idle
timeout expires.
With the sfs_destroyOfdOnConflict policy, the OFD is destroyed and all
transactions associated with it are aborted when these two conditions occur:
the idle timeout has expired and a transaction associated with a different OFD
tries to access its locked records. (This is the default policy.)
With the sfs_preserveOfdOnConflict policy, after the idle timeout expires, the
transaction associated with a locked record is aborted but an attempt is made
to preserve the OFD if a transaction associated with a different OFD tries to
access a locked record. For example, if (after the expiration of the idle
timeout) a transaction associated with an OFD holds a lock on a record and
another transaction attempts to get a conflicting lock on that record, the
transaction holding the lock is aborted but the OFD is preserved and can be
reused. However, if (after the expiration of the idle timeout) the transaction
associated with an OFD holds the lock on an entire file and another
transaction attempts to open that file, the transaction holding the lock is
aborted and the associated OFD is destroyed.
153
Related information
v sfsadmin query ofd
v sfsadmin terminate ofd on page 156
sfsadmin query ofd

Purpose
Displays information about the specified open file descriptor (OFD) managed by the
specified server.
Synopsis
sfsadmin query ofd -server server_name server_ofd_number
Arguments
-server server_name
CICS_TK_SFS_SERVER.
server_ofd_number
Specifies the server identification number of the open file descriptor (OFD)
about which information is requested.
Description
The command displays information about the specified open file descriptor (OFD)
managed by a server.
Examples
The following command displays information about OFD 33 managed by the server
/.:/cics/sfs/mysfs:
%
sfsadmin query ofd -server /.:/cics/sfs/mysfs 33
Ofd id: 33
Owner: (null)
Transaction id: 0
Number of rpcs: 139
Authority:
read file
inquire file
Auto close: no
Label: (null)
154
Output
v File name is the name of the SFS file.
v Owner indicates the owner of the file.
v Open time indicates the time that the file was opened.
v Number of rpcs refers to the number of RPCs completed using this OFD.
file at a time.
a permission to perform an operation on a file. For example, a client may have
v Isolation level refers to the extent to which data being accessed by the OFD
is protected from concurrent access by other users. An isolation level is the
degree to which operations on a file are isolated from other operations on the
same file. The isolation level determines the locking policy used.
using this OFD will take to complete before timing out.
v
v
v
v
v
v
Auto close refers to whether or not a transactional OFD will be automatically

closed when the transaction is resolved. If the OFD is nontransactional, this field
will be no (nontransactional OFDs must be closed manually).
Duplicate detection specifies the level at which the server detects duplicate
keys in non-unique indexes.
Operational force applies only to nontransactional OFDs and refers to whether
operation.
Label is the user-defined string for the OFD.
Open transaction id is the identification number of the transaction that holds the
Ofd idle timeout is the time, in seconds, that an OFD may be permitted to be
idle while waiting for an SFS call. If this time period has elapsed, and another
OFD requests a lock held by the idle OFD, the transaction associated with the
idle OFD is terminated, closing the OFD and releasing the lock.
Ofd idle timeout policy specifies the actions to be taken when the OFD idle
timeout expires.
With the sfs_destroyOfdOnConflict policy, the OFD is destroyed and all
transactions associated with it are aborted when these two conditions occur:
the idle timeout has expired and a transaction associated with a different OFD
tries to access its locked records. (This is the default policy.)
With the sfs_preserveOfdOnConflict policy, after the idle timeout expires, the
transaction associated with a locked record is aborted but an attempt is made
to preserve the OFD if a transaction associated with a different OFD tries to
access a locked record. For example, if (after the expiration of the idle
155
timeout) a transaction associated with an OFD holds a lock on a record and

another transaction attempts to get a conflicting lock on that record, the
transaction holding the lock is aborted but the OFD is preserved and can be
reused. However, if (after the expiration of the idle timeout) the transaction
associated with an OFD holds the lock on an entire file and another
transaction attempts to open that file, the transaction holding the lock is
aborted and the associated OFD is destroyed.
Related information
v sfsadmin list ofds on page 151
v sfsadmin terminate ofd
sfsadmin terminate ofd

Purpose
Closes the specified open file descriptor.
Synopsis
sfsadmin terminate ofd -server server_name server_ofd_number
Arguments
-server server_name
CICS_TK_SFS_SERVER.
server_ofd_number
Specifies the integer that identifies the open file descriptor (OFD) associated
with the file to be closed. This number can be obtained by using the command.
Description
A file may become unavailable if it is not appropriately closed. For instance, if a
client of an SFS server terminates abnormally, files that were exclusively opened by
the client may remain open, preventing access by other users. You can use the
command to determine currently open OFDs for a server. Then, you can force an
OFD to close so that the file opened with that OFD can be accessed by others. The
command forces an OFD to close.
When an OFD is forced to close, any in-progress transaction using that OFD will be
aborted. The client application owning the transaction will receive a Transaction
Aborted error on the next operation using that OFD and any further attempts to use
that OFD will generate an OFD Invalid error.
Examples
The following command forces OFD 3 to close:
%
sfsadmin terminate ofd 3
Related information
v sfsadmin query ofd on page 154
v sfsadmin query tranlock on page 166
v sfsadmin list ofds on page 151
156
|
|
sfsadmin query export

sfsadmin query server

Purpose
Displays information about the specified server.
Synopsis
sfsadmin query server -server server_name
Arguments
-server server_name
CICS_TK_SFS_SERVER.
Description
The command displays the settings for a server.
Examples
The following command displays information about the server:
%
sfsadmin query server
Collating language: C
Log file name: SfsLogVol/sfslogfile
Buffer pool size: 1000
TRPC authentication level: 2
Minimum authentication level: 2
Checkpoint Interval Info:
Interval time in seconds: 60
Minimum number of log records: 5000
Maximum number of log records: 100000
Default idle timeout: 60
Output
v Collating language. This is the language used in the collation of nlsString fields
in records.
v Log file name. This is the name of the file to which log information is written.
This file name is specified when the server is started.
v Buffer pool size. This is the size of the memory buffer, in pages, used for disk
I/O.
v TRPC authentication level. This is the authentication level required by the
server to accept transactional remote procedure calls from clients.
v Minimum authentication level. This is the authentication level required by the
server to accept any calls from clients.
v Checkpoint interval information. The checkpoint interval is the time between
writes to recoverable media. The checkpoint interval and the maximum and
minimum number of log records are displayed.
157
v Default idle timeout. The idle timeout is the time, in seconds, that an OFD
may be permitted to be idle while waiting for an SFS call.
|
sfsadmin enable server
Purpose
Enables a server for full operation.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
Specifies the server affected by the command. If the server name is not
specified in the command line, it is retrieved from an environment variable,
CICS_TK_SFS_SERVER.
Description
|
|
|
The sfsadmin enable server command enables a server for full operation,
meaning that the server initialization is complete and the server can register its
interface.
Examples
|
|
The following command enables the server /.:/branch1/server/sfs1:
Privilege Required
CICS_TK Monitor administer (a) permission to the node manager.
CICS_TK RQS administer (a) permission to the RQS server.
Related Information
|
|
v sfsadmin list lvols

v sfsadmin query server on page 157
|
|
sfsadmin enable server -server server_name
sfsadmin enable server -server /.:/branch1/server/sfs1
sfsadmin list lvols
Purpose
Displays the names of all volumes associated with the server.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
sfsadmin list lvols -server server_name
158
Description
|
|
The sfsadmin list lvols command displays the names of all the volumes
associated with the server.
Examples
|
|
|
|
|
|
|
The following command displays the names of all volumes associated with the
server:
Privilege Required
CICS_TK SFS query (Q) permission on the server.
|
|
Related Information
|
|
|
% sfsadmin list lvols

Volumes:
sfsVol1
sfsVol2
sfsVol3
v sfsadmin add lvol on page 163

v sfsadmin query lvols
sfsadmin query lvols
Purpose
Displays information about the specified volume .
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
volume_name
Specifies the name of the volume about which information is being requested.
Description
|
|
|
|
|
|
The sfsadmin query lvol command displays;

v The total number of pages on the volume.
v The number of pages used.
v The number of pages free.
v For each area associated with a file or index, the number of pages allocated and
used.
The size of a page is 4096 bytes.
sfsadmin query lvol -server server_name volume_name
159
Examples
|
|
|
|
|
|
|
|
|
|
|
|
The following command displays information about the volume sfsVol2:
Privilege Required
CICS_TK SFS query (Q) permission on the server.
|
|
|
Related Information
|
|
sfsadmin query lvol sfsVol2
Total pages: 4320

Pages used: 193
Pages free: 4127
Areas:
Area name: telshopFile.stockNumIndex
Pages allocated: 8
Pages used: 1
Area name: telshopFile.productNameIndex
Pages allocated: 8
Pages used: 1

v sfsadmin list lvols on page 158
sfsadmin acquire lvol
Purpose
Acquires a previously initialized volume.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
volume_name
Specifies the name of the volume that is to be acquired.
Description
|
|
|
|
|
|
The sfsadmin acquire lvol command acquires a previously released volume into
an SFS server. The volume must have been released from an SFS server (by using
the sfsadmin release lvol command). Acquiring a volume creates information
about the volume, maintained by the SFS server. The user data on the volume is
unchanged. After the volume has been acquired, SFS operations on the volume are
permitted.
|
|
|
|
Before the server acquires this volume, the volume must be mapped, using the
CICS_TK Volume Service, to the physical storage containing the data (either the
actual volume that was released by another server or a copy of that volume). The
commands that you use depend on which platform you are using.
sfsadmin acquire lvol -server server_name volume_name
160
|
|
|
AIX with AIX logical volume management

If the machine has mapped log volumes, map the logical volume by issuing
the tkadmin map lvol command.
|
|
|
|
Other platforms or AIX with CICS_TK logical volume management

Do the following to map the logical volume:
1. Initialize the Volume Service disk with the tkadmin init disk command
(if a different server is acquiring the volume).
|
|
|
2. Create a physical volume by using the tkadmin create pvol command

(if a different server is acquiring the volume).
3. Create a logical volume by using the tkadmin create lvol command.
4. Make the logical volume accessible for input and output by using the
tkadmin enable lvol command.
|
|
|
|
Note that these steps are identical to those you must follow prior to invoking the
sfsadmin add volume command.
|
|
|
If a previously released volume is acquired again by an SFS server and the same
physical storage that backed the volume contains the data, you must re-map the
volume onto the physical storage.
|
|
|
|
If the SFS server from which the volume is being acquired is executing on a
different machine, the user is responsible for copying the data over to the physical
storage accessible from the local machine. The two machines must use the same
operating system.
|
|
|
|
|
|
A name clash between files on the acquired volume and other existing files
managed by the server causes the function to fail. Any intervening failures during
the execution of this function should result in the volume being restored to its state
prior to the acquire. If the user needs to recover from future media failures, a new
volume backup should be performed. Previous volume backups can be used to
restore the volume only to the state at the time when the volume was released.
Examples
|
|
|
The following examples show how to map and acquire SFS logical volumes. Note
that the server name can also be specified through the CICS_TK_SERVER
environment variable.
|
|
|
|
Mapping logical volumes (AIX with logical volume management)

The following command maps the logical volume sfsVol1 on the server
/.:/branch1/server/sfs1:
|
|
|
|
|
|
|
|
Mapping logical volumes (Other platforms or AIX with CICS_TK logical volume
management)
The following commands map the logical volume sfsVol1 on the server;
|
|
|
|
Acquiring logical volumes

The following command associates the logical volume sfsVol1 with the server
% tkadmin map lvol -server /.:/branch1/server/sfs1 sfsVol1 64
% tkadmin init disk -server /.:/branch1/server/sfs1 /dev/rsd1e
% tkadmin create pvol -server /.:/branch1/server/sfs1 sfsPvol1 16 1 /dev/rsd1e 0
% tkadmin create lvol -server /.:/branch1/server/sfs1 sfsVol1 sfsPvol1
% tkadmin enable lvol -server /.:/branch1/server/sfs1 sfsVol1
sfsadmin acquire lvol -server /.:/branch1/server/sfs1 sfsVol1

161
Privilege Required
CICS_TK SFS administer (A) permission on the server.
|
|
|
|
|
|
Related Information
v sfsadmin list lvols on page 158
v sfsadmin query lvols on page 159
v sfsadmin release lvols
v tkadmin init disk on page 196
v tkadmin create pvol on page 182
v tkadmin create lvol on page 181
v tkadmin map lvol on page 204
|
|
|
|
tkadmin enable lvol on page 190
|
|
sfsadmin release lvols
Purpose
Releases a specified volume.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
volume_name
Specifies the name of the volume to be released.
Description
|
|
|
The sfsadmin release lvol command releases a volume. It informs an SFS server
that the specified volume will be modified by another SFS server. No further access
to the volume in the server is allowed.
|
|
|
The command fails if there are any open files on the volume. It flushes all modified
buffers belonging to the volume to disk. These actions ensure that no recovery work
on the volume is required on subsequent server restarts.
|
|
|
|
|
|
Disk layout information pertaining to the volume (maintained by the CICS_TK

Volume Service) is unchanged by releasing the volume. The restart information
associated with the volume is extracted from the log and stored in the volume itself.
This enables the application that subsequently acquires this volume to access this
information. Any failures during the execution of this function result in the volume
being restored to its state prior to the release.
|
|
|
Upon successful release of the volume, the volumes mapping to its physical
volume(s) is severed, and it is renamed original_name.rel.time_of_release. The
time_of_release is the number of seconds from (00:00:00) 01 January 1970 GMT.
sfsadmin release lvol -server server_name volume_name
162
|
|
|
|
This volume can be used to restore the volume from backup, if necessary.
Releasing volumes that contain portions of SFS files (For example a volume which
contains the primary area of a file that has an index area on another volume) is not
allowed.
Examples
|
|
|
The following command releases the logical volume sfsVol1 from the server
Privilege Required
CICS_TK SFS administer (A) permission on the server.
|
|
|
|
|
Related Information
|
|
|
|
|
|
v
v
v
v
v
v
v
v
sfsadmin release lvol -server /.:/branch1/server/sfs1 sfsVol1
sfsadmin acquire lvol on page 160

tkadmin init disk on page 196
tkadmin create pvol on page 182
tkadmin create lvol on page 181
tkadmin map lvol on page 204
sfsadmin add lvol
Purpose
Adds the specified volume to the specified server .
|
|
Synopsis
Arguments
|
|
|
-server server_name
default is the server defined by the environment variable CICS_SFS_SERVER.
|
|
volume_name
Specifies the name of the volume to be added.
Description
|
|
The sfsadmin add lvol command associates a logical volume with the specified
SFS server. The volume must have been previously created and enabled.
Examples
|
|
|
|
The following command associates the logical volume sfsVol1 with the server
sfsadmin add lvol -server server_name volume_name
sfsadmin add lvol -server /.:/branch1/server/sfs1 sfsVol1
163
Privilege Required
CICS SFS administer (A) permission on the server.
|
|
|
|
|
|
Related Information
v
v
v
v
v
v
v
|
|

sfsadmin query filelock

Purpose
Displays information about the locks held on a file.
Synopsis
sfsadmin query filelock -server server_name file_name
-server server_name
CICS_TK_SFS_SERVER.
file_name
Specifies the name of the file for which lock information is requested.
Description
The command displays detailed information about file- and record-level locks held
by each OFD opened on the specified file.
Examples
In the following example, several OFDs are accessing the file Inventory in shared
mode. The output shows the number and type of locks held by each OFD.
%
sfsadmin query filelock Inventory
Lockers of file: Inventory

ofd id: 1
transaction id: 18
openTid:
14
file locks:
Lock 1:
lock mode:
intention read lock
transaction id: 18
record locks:
lock 1:
lock mode:
read lock
index:
primary
transaction id: 18
key value:
164
3030 3035
ofd id: 2
transaction id: 0
openTid: 39
file locks:
lock 1:
lock mode:
read lock
transaction id: 39
record locks:
No locks
ofd id: 3
transaction id: 0
openTid: 57
file locks:
lock 1:
lock mode:
intention read lock
transaction id: 57
record locks:
lock 1:
lock mode:
read lock
index:
primary
transaction id: 57
key value:
3030 3034
0005
0004
Output
The following list explains the output of the command:
with the OFD, if the OFD is transactional. If it is nontransactional, this
v OpenTid is the identification number of the transaction that holds the open access
mode lock (shared/exclusive).
v Open lock mode can be either shared or exclusive. A shared access mode allows
more than one application to obtain access to a file at the same time. An
exclusive access mode allows only one application to obtain access to a file at a
time.
v For each file lock, the output lists the lock by number (beginning with 1), and
provides the following information. If there are no file locks, the output indicates
no locks.
lock or write lock.
v For each record lock, the output lists the lock by number (beginning with 1), and
provides the following information. If there are no record locks, the output
indicates no locks.
lock or write lock.
165
Index is the name of the index used to locate the record. The value for this
field is either primary or the name of the secondary index.
Key value is the value that is locked, represented in raw hexadecimal and in
ASCII.
Related information
v
v
v
v
v
sfsadmin query tranlock

tkadmin abort transaction on page 178
tkadmin list transactions on page 202
sfsadmin query tranlock

Purpose
Displays information about locks held by a specified transaction.
Synopsis
sfsadmin query tranlock -server server_name tid
Arguments
-server server_name
CICS_TK_SFS_SERVER.
tid Specifies the transaction identification number (an integer).
Description
The command displays information about all locks held by the specified transaction.
(The command displays the transaction identifier of each transactional OFD in the
file system.)
Examples
In the following example, the command shows that the Accounts file is being
accessed using OFD 41. The file is opened in exclusive access mode using
transaction 131275. The command is used to display locks held by transaction
131275.
%
sfsadmin list ofds
Ofd id: 41
File name: Accounts
Owner: (null)
Transaction id: 0
Number of rpcs: 1
Authority:
insert file
inquire file
exclusive file
166
Auto close: no
Label: (null)
%
Lock 1:
Index name: (null)
Key value:
6169 725f 7265 732e 6669 6c65
Accounts
In the next example, transaction 131319 holds 5 locks. Note that locks 2 and 4 are
record-level locks. The output shows the name of the index (stockNumIndex), and
the value that is locked. In this case, the value does not fall within the range of
printable ASCII characters. Since the characters cannot be printed, they are
displayed as a series of dots.
% sfsadmin query tranlock 131319
Lock 1:
Lock mode: intention write lock
Index name: (null)
Key value:
656d 706c 6f79 6565 2e66 696c 65
Inventory
Lock 2:
Index name: stockNumIndex
Key value:
0000 0002 0000 0002
........
Lock 3:
Lock mode: intention read lock
Index name: (null)
Key value:
656d 706c 6f79 6565 2e66 696c 65
Inventory
Lock 4:
Index name: stockNumIndex
Key value:
0000 0001 0000 0001
........
Lock 5:
Index name: (null)
Key value:
6169 725f 7265 732e 6669 6c65
Accounts
Output
v Lock mode is the type of lock that the transaction holdsfor example, read lock
or write lock.
v File name is the file on which the lock is placed. If the lock is a file lock, the file
name may be followed by a period and an integer. The integer represents a file
167
lock space. Multiple locks on the same file do not conflict as long as the locks
are in different lock spaces as indicated by different integers in the file name
extension.
v Index name is the name of the index if this is a record-level lock and null if this is
a file-level lock.
v Key value is the value that is locked, represented in raw hexadecimal and in
ASCII.
Related information
v
v
v
v
v
v
|
sfsadmin list ofds on page 151

sfsadmin query ofd on page 154
tkadmin abort transaction on page 178
sfsadmin add index
Purpose
Adds a secondary index to the specified file.
|
|
|
|
|
|
|
|
|
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
Specifies the name of the file to which the index will be added.
|
|
index_field_name
Specifies the name of the new index.
|
|
|
|
|
|
number_of_index_fields {{field_name [-descending ]}...}

Specifies the number of fields in the new index and their names. Specify the
number of fields in the index as number_of_index_fields. For each field, specify
the name of the field as field_name. The option -descending specifies that the
field will be sorted in descending order. If -descending is not specified, field
values are sorted in ascending order.
|
|
|
[-unique]
Specifies that key values for this index must be unique. If the -unique option is
not specified, duplicate key values are allowed for the index.
|
|
[-inactive]
Specifies that the index will be inactive until it is rebuilt with the sfsadmin
sfsadmin add index -server

server_name file_name index_field_name
{{field_name [-descending]}...}
[-unique] [-inactive]
[-volume volume_name]
[-alternaterecord number_of_fields
{{field_name field_type_etcetera}...}]
[-excludedkey number_of_fields
{{field_name field_value}...}]
168
|
|
rebuild index command. An inactive index cannot be used to retrieve records

in the file. If the -inactive option is not specified, the index is active.
|
|
|
|
[-volume volume_name ]
Specifies the name of the volume on which the new index will reside. If the
-volume option is not specified, the index will reside on the same volume as
the primary area of the file.
|
|
|
|
Specifies the number of pages to be reserved for the index. The size of a page
is 4096 bytes. If the -preallocate option is not specified, the default value of
number_of_pages is zero.
|
|
|
|
|
|
|
|
|
|
[-alternaterecord number_of_fields {{field_name field_type_etcetera}...}]

Names the alternate record specification from which to derive the index key
fields. This option allows the secondary index to use record structures that are
different from the primary record that was specified when the file was created.
Only fields of type byteArray in the primary record specification can be
reinterpreted. The individual field lengths must add up to the length of the byte
array. Other field types in the alternate record specification should map to fields
in the primary record specification of the same type and offsets. When adding
an index for files not originally created in SFS, only fields of type byteArray in
the primary record specification can be used as index fields.
|
|
|
|
|
|
|
|
|
|
|
Specify the number of key fields in the alternate record specification as

number_of_fields. For each key field, specify the name of the field as
field_name and the type of the field as field_type_etcetera. Possible field types
include: unsignedInt16, signedInt16, unsignedInt32, signedInt32,
unsignedInt64, signedInt64, float, double, timestamp, decimal field_size,
stringfield_size, byteArray field_size, varLenByteArray field_size,
shortVarLenByteArray field_size, nlsString field_size. Where noted, you must
specify field_size. When strings of the type nlsString are used as index fields,
the collating sequence is determined by the value of the -c option on the sfs
command line. If that option is not specified, any field of nlsString type is
treated as an invalid type.
|
|
|
|
|
|
|
[-excludedkey number_of_fields {{field_name field_value}...}]

Specifies the key value to be excluded from the new index. Records with this
key value will not be inserted into the index and will not be accessible through
the secondary index. Specify the number of field values to be excluded as
number_of_fields, the name of the field to be excluded as field_name, and its
value as field_value. If the -excludedkey option is not specified, all key values
are included in the index.
Description
|
|
|
|
|
|
|
The sfsadmin add index command creates a secondary index for a file and stores
it on the volume where the files primary area resides (but in a separate area called
the secondary area). By default the index is active and duplicate key values are
allowed. A file can have zero or more secondary indices. Because each secondary
index is stored in an area separate from the primary area that it references,
secondary indices can be stored on different volumes and used to access the
primary area simultaneously.
|
|
|
|
to 254 characters.
169
Examples
|
|
|
The following command adds a secondary index named zipCodeIndex to the file
Accounts. The zipCodeIndex index contains one key: the zipCode field.
Privilege Required
|
|
CICS_TK SFS administer (A), exclusive open (E), and query (Q) permissions on
the file.
|
|
|
Related Information
v
v
v
v
v
v
|
|
|
|
|
sfsadmin add index Accounts zipCodeIndex 1 zipCode
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
create clusteredfile on page 141

create relativefile on page 143
create sequentialfile on page 145
deactivate index on page 171
delete index
expand index on page 175
v sfsadmin query index on page 173

v sfsadmin rebuild index on page 172
v sfsadmin rename index on page 174
|
|
|
|
sfsadmin delete index
Purpose
Removes the specified secondary index of the specified file.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
Specifies the name of the file containing the index to be removed.
|
|
index_name
Specifies the name of the secondary index to be removed.
Description
|
|
The sfsadmin delete index command removes the specified secondary index of a
file. All disk space allocated to the index is reallocated.
Examples
|
|
The following command removes the index productNameIndex from the file
Inventory:
sfsadmin delete index -server server_name file_name index_name
170
Privilege Required
|
|
Related Information
|
|
|
|
|
|
|
|
sfsadmin delete index Inventory productNameIndex
v sfsadmin add index on page 168

v sfsadmin deactivate index
v
v
v
v
v
sfsadmin
sfsadmin
sfsadmin
sfsadmin

query index on page 173
rebuild index on page 172
rename index on page 174
sfsadmin deactivate index
Purpose
Deactivates a secondary index.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
|
file_name
Specifies the name of the file containing the secondary index that is to be
deactivated.
|
|
index_name
Specifies the name of the secondary index that is to be deactivated.
|
|
|
|
[-deallocate]
Deallocates the storage currently reserved for the specified index. If the
-deallocate option is not specified, reserved space for the index remains
allocated.
Description
|
|
|
|
|
|
The sfsadmin deactivate index command stops all updates to the specified
secondary index so that modifications to records in the file are no longer reflected in
the index. The records in the file are no longer accessible through the inactive
index. Deactivated indices can improve performance since the SFS does not apply
record updates to an inactive index. The index can be reactivated with the
sfsadmin rebuild index command.
sfsadmin deactivate index -server server_name file_name index_name [-deallocate]
171
Examples
|
|
|
|
The following command deactivates the secondary index zipCodeIndex in the file
Accounts, releasing the disk space reserved for it so that other files can use the
space.
Privilege Required
|
|
|
|
Related Information
v sfsadmin add index on page 168

v sfsadmin delete index on page 170
v
v
v
v
|
|
|
|
|
sfsadmin deactivate index Accounts zipCodeIndex -deallocate
sfsadmin
sfsadmin
sfsadmin
sfsadmin

rebuild index
sfsadmin rebuild index
Purpose
Rebuilds the specified secondary index.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
Specifies the name of the file containing the index to be rebuilt.
|
|
index_name
Specifies the name of the secondary index to be rebuilt.
Description
|
|
|
|
|
The sfsadmin rebuild index command activates the specified secondary index.
The index is updated to reflect changes to records made since the index was last
deactivated. After an index is rebuilt, records are accessible through the rebuilt
index. This command reverses the effect of the sfsadmin deactivate index
command.
Examples
|
|
The following command rebuilds the index zipCodeIndex:
sfsadmin rebuild index -server server_name file_name index_name
172
sfsadmin rebuild index Accounts zipCodeIndex
Privilege Required
|
|
|
|
|
|
Related Information
|
|
|
v
v
v
v
v
v
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
add index on page 168

delete index on page 170
query index
sfsadmin query index
Purpose
Displays information about the secondary index of a specified file.
|
|
Synopsis
Arguments
|
|
|
|
-server server_name
CICS_TK_SFS_SERVER.
|
|
file_name
Specifies the name of the file containing the secondary index.
|
|
|
index_name
Specifies the name of the secondary index about which information is being
requested.
Description
|
|
|
|
|
The sfsadmin query index displays storage and status information about the
specified secondary index. This information includes the index name, whether the
index is active or inactive, whether duplicate key values are allowed, key fields for
the index, the volume on which the index resides, disk space allocated and used,
and number of entries.
Examples
|
|
|
|
|
|
|
|
|
|
|
The following command displays information about the secondary index

productNameIndex in the file Inventory:
sfsadmin query index -server server_name file_name index_name
% sfsadmin query index Inventory productNameIndex

Index name: productNameIndex
Active: yes, Unique: yes
Index fields:
Name: productName, Ordering: ascending
Volume: sfsDataVol, Allocated pages: 8, Utilized pages: 1
Number of entries: 187
Btree level: 4
Number of leaves: 32
173
Output
|
|
|
The following list explains the output of the sfsadmin query index command:
v Index name lists the name of the index about which information is being
displayed.
v Active specifies whether the field is currently active (yes) or inactive (no).
v Unique specifies whether key values for the index are unique (yes) or if duplicate
key values are allowed (no).
v For each index field, the output provides the following information.
Name specifies the name of the index field.
Ordering specifies the method of sorting applied to the field. Possible values
are ascending and descending.
v Volume lists the volume on which the index resides.
v Allocated pages specifies the number of pages allocated on the volume for the
index.
v Utilized pages lists the number of pages currently used by the index.
v Number of entries specifies the current number of entries in the index.
v Btree level lists the number of levels in the binary tree representing the index.
v Number of leaves specifies the number of leaves, or terminal nodes, in the binary
tree representing the index.
Privilege Required
CICS_TK SFS query (Q) permission on the file.
|
|
|
|
|
|
|
|
Related Information
|
|
|
|
|
|
|
|
|
|
|
|
|
|
v
v
v
v
v
v
v
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
add index on page 168

delete index on page 170
rebuild index on page 172
rename index
sfsadmin rename index

Purpose
Renames the specified index.
Synopsis
sfsadmin rename index -server server_name file_name index_name new_index_name
Arguments
-server server_name
CICS_TK_SFS_SERVER.
file_name
Specifies the name of the file containing the index to be renamed.
174
index_name
Specifies the name of the index to be renamed.
new_index_name
Specifies the new name of the index.
Description
The command replaces an index name with a new index name. The index remains
in the same physical location as the original index. Indices cannot be renamed to
different volumes.
Examples
The following command renames the index stockNumIndex in the file Inventory to
stockIndex:
%
sfsadmin rename index Inventory stockNumIndex stockIndex
sfsadmin expand index

Purpose
Allocates more disk space for the specified secondary index
Synopsis
sfsadmin expand index -server server_name file_name index_name number_of_pages
Arguments
-server server_name
CICS_TK_SFS_SERVER.
file_name
Specifies the name of the file containing the index to be expanded.
index_name
Specifies the name of the secondary index for which more space will be added.
number_of_pages
Specifies the number of pages of disk space to be added. The size of a page is
4096 bytes.
Description
The sfsadmin expand index command allocates more disk space for the specified
secondary index. Disk space to be allocated is expressed in pages. Note that the
amount of disk space allocated may not exactly equal the expansion request. This
is because the SFS rounds expansion requests up to the nearest convenient value.
Examples
The following example allocates an additional 500 pages of disk space to the
zipCodeIndex index of the Accounts file:
%
sfsadmin expand index Accounts zipCodeIndex 500
175
Related information
v sfsadmin rename index on page 174
176

The tkadmin commands are used to configure and maintain the SFS server and
PPC Gateway server. The tkadmin commands can be grouped by task, as shown in
the following list:
v Setting up and managing a servers log file
tkadmin disable mediaarchiving on page 187
tkadmin enable archfile on page 188
tkadmin enable logfile on page 189
tkadmin enable mediaarchiving on page 191
tkadmin query logvol on page 211
tkadmin query mediaarchiving on page 212
tkadmin restore logvol on page 224
v Managing volumes for server data
tkadmin add mirror on page 179

tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
delete disk on page 183

delete lvol on page 184
delete pvol on page 185
disable lvol on page 186
enable lvol on page 190
expand lvol on page 191
expand pvol on page 192
flush lvol on page 194
tkadmin flush mediaarchive on page 194

tkadmin move pvol on page 205
tkadmin recover lvols on page 216
tkadmin recreate lvol on page 217
tkadmin remove mirror on page 221
tkadmin rename lvol on page 222
tkadmin rename pvol on page 223
tkadmin sync mirrors on page 229
v Creating and deleting CICS Toolkit logical volumes backed by AIX volumes
tkadmin remap lvol on page 220
tkadmin unmap lvol on page 232
v Performing backups and restores
tkadmin backup lvol on page 180
tkadmin query backup on page 207
tkadmin restore lvols on page 225
tkadmin retain backups on page 227
v Obtaining information about disks and volumes
tkadmin list disks on page 197
177
tkadmin list lvols on page 198

tkadmin list pvols on page 199
tkadmin query disk on page 210
tkadmin query lvol on page 211
tkadmin query pvol on page 213
v Administering transactions
tkadmin abort transaction
tkadmin query transaction on page 215
v Controlling the tracing of server components
tkadmin dump ringbuffer on page 187
tkadmin redirect trace on page 218
tkadmin set ringbuffer size on page 228
tkadmin show ringbuffer size on page 229
tkadmin trace specification on page 230
v Obtaining trace and error history information
tkadmin list redirect on page 199
tkadmin list trace on page 200
tkadmin query redirect on page 214
tkadmin query trace on page 214
v Managing dynamic resource managers
tkadmin list rmi on page 200
Note: Some of the tkadmin commands that affect logical volumes, physical
volumes, disks, and mirrors have restricted usage. Any usage restrictions are
noted in the descriptions of the commands.
The AIX operating system supports logical volumes. CICS can use either the
logical volumes supported by the AIX operating system or CICS Toolkit
logical volumes (using disks and physical volumes). CICS provides a set of
commands for each approach.
tkadmin abort transaction

Purpose
Aborts a transaction.
Synopsis
tkadmin abort transaction -server server_name tid
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
tid Identifies the transaction.
178
Description
The tkadmin abort transaction command aborts the transaction identified by tid.
Only transactions that have not been prepared can be aborted via this command.
The states of the unresolved transactions at the server can be obtained via the
tkadmin list transactions command. You can abort active or inactive transactions.
Aborting a transaction frees all locks that were previously held by it. You can abort
transactions that are obstructing the operation of the Toolkit server.
Unresolved transactions that have reached the prepared state can be forced to a
specific outcome using the tkadmin force transaction command.
Examples
The following command aborts the transaction identified by tid 438:
%
Related information
v tkadmin list transactions on page 202
v tkadmin force transaction on page 195
tkadmin add mirror

Purpose
Adds a mirror to a logical volume.
Synopsis
tkadmin add mirror -server server_name logical_volume_name physical_volume_name
Arguments
-server server_name
logical_volume_name
Specifies the logical volume to be mirrored.
Specifies the physical volume to be used as the mirror. (This physical volume
must be at least as large as the smallest physical volume backing the logical
volume.)
Description
The tkadmin add mirror command mirrors a logical volume by providing more than
one copy of its data. Mirroring is used to increase the availability of a logical
volume. To be mirrored, logical volumes must first be enabled. You can list the
existing logical volumes using the tkadmin list lvols command.
The physical volume specified for use as a mirror should not be mapped to any
other logical volume. If it is mapped to another logical volume, this command fails.
When mirroring a logical volume, the content of the new physical volume remains
indeterminate until you invoke the tkadmin sync mirrors command. Adding a mirror
179
and synchronizing its contents can be done while a volume is enabled, that is, while
I/O is taking place. If a mirror is added to a volume before the volume is in use, the
two physical volumes do not have to be synchronized.
Note: Do not use this command if you are using AIX logical volume management.
Examples
The following command mirrors the logical volume named lvol8 by duplicating its
data and storing it on the physical volume pvol3:
%
tkadmin add mirror lvol8 pvol3
Related information
v tkadmin sync mirrors on page 229
v tkadmin remove mirror on page 221
tkadmin backup lvol

Purpose
Backs up a logical volume.
Synopsis
tkadmin backup lvol -server server_name logical_volume_name
[-fileprefix file_prefix] [-filesize file_size] [-nfiles number_of_files]
Arguments
-server server_name
logical_volume_name
Specifies the logical volume to back up.
[-fileprefix file_prefix]
Specifies a prefix used for each backup filename. The prefix can be a complete
or relative pathname used to write the backup files to a different location (for
example, /bkups/sfsvol1 (Open Systems), D:\bkups\sfsvol1 (Windows), or
sfsvol1). Using the last example, the backup files are named
sfsvol1.TRB.000000, sfsvol1.TRB.000001, sfsvol1.TRB.000002, and so on. A
relative pathname is interpreted within the context of the servers working
directory. The default file prefix is the volume name.
[-filesize file_size]
Specifies the backup file size. The file size argument can be specified in bytes
(an integer) or in kilobytes (an integer followed by the letter kfor example,
51k). The default file size is 1 megabyte.
Specifies the number of backup files to be created. The default number of files
is 1.
Description
The tkadmin backup lvol command backs up a logical volume by dumping its
contents to a set of backup files. The tkadmin backup lvol command backs up the
data only; it does not back up data structures such as files or queues. To use the
180
command, media archiving must be enabled by using the tkadmin enable

mediaarchiving command. You can back up a volume while the server is running,
although performance may be slowed.
You can create a complete backup by repeatedly issuing the tkadmin backup lvol
command with no options. The command creates one 1-megabyte backup file each
time the command is issued and returns a warning until a complete backup
containing enough files to restore the entire volume exists. If a volume is very large,
you can specify a file size and number of files sufficient to create a complete
backup with one or two issues of the command.
Examples
Enter the following command to create a complete backup of a 200-kilobyte volume
named debitvol with five files of 41 kilobytes each (each file allows 1 kilobyte for
header information):
%
tkadmin backup lvol debitvol -filesize 41k -nfiles 5
The backup files created are named debitvol.TRB.000000, debitvol.TRB.000001,

debitvol.TRB.000002, and so on.
Related information
v tkadmin enable mediaarchiving on page 191
v tkadmin query backup on page 207
v tkadmin query lvol on page 211
tkadmin create lvol

Purpose
Creates a logical volume.
Synopsis
tkadmin create lvol -server server_name logical_volume_name physical_volume_name
Arguments
-server server_name
logical_volume_name
Specifies the new logical volume. This name can be any string of alphanumeric
characters with a maximum length of 128 characters including the end-of-string
character.
Specifies the physical volume that backs the new logical volume.
Description
The tkadmin create lvol command creates a logical volume of the specified name.
Initially, each logical volume is mapped to one physical volume. The specified
physical volume cannot be mapped to another logical volume, or the command
fails.
181
Note: If you are using AIX logical volume management, use the tkadmin map lvol
command to create a CICS Toolkit logical volume and map it to an AIX
operating system logical volume.
Examples
The following command creates a logical volume named lvol1 and maps it to the
physical volume named pvol1:
%
tkadmin create lvol lvol1 pvol1
Related information
v tkadmin delete lvol on page 184
tkadmin create pvol

Purpose
Creates a physical volume.
Synopsis
tkadmin create pvol -server server_name physical_volume_name chunk_size
number_of_regions {{disk_name disk_offset [-regionsize region_size]}...}
Arguments
-server server_name
Specifies the physical volume. This name can be any string of alphanumeric
characters with a maximum length of 128 characters including the end-of-string
character.
chunk_size
Specifies the number of pages guaranteed to be physically contiguous on a disk
of the physical volume. The chunk size must be a power of two, for instance 16
or 64.
number_of_regions
Specifies the number of regions in the physical volume (an integer). Often, the
number of regions is between 1 and 4, but it may be as large as available disk
space allows.
disk_name
On Open Systems, specifies the full path name of the disk that is providing
storage space for this region. The name specified must be the same name that
was used to initialize the disk. On Windows, specifies the logical disk drive, the
physical disk, or the full path name of the operating system file being used. On
Windows, a disk is an entire physical disk specified in the form
\\.\PHYSICALDRIVEnumber_of_drive (for example, \\.\PHYSICALDRIVE3), a
logical disk drive specified in the form \\.\drive_name (for example, \\.\D:), or the
full pathname of an operating system file, including the drive letter (for example,
D:\filevol1). This argument is specified for each region.
Note: If you are using an entire physical disk on Windows systems, you must
ensure that the physical disk does not contain any configured partitions.
182
disk_offset
Specifies the offset (in pages) into the disk where this region begins. The size
of a page is defined as 4K. This argument is specified for each region.
[-regionsize region_size]
Specifies the size (in pages) of this region. This value can vary greatly; 1 page
is the smallest valid value. The largest value is dependent on the disk size and
usage. The region size cannot be smaller than the chunk size. The specified
region size is rounded down to a multiple of the chunk size. The default region
size is the entire remaining portion of the disk (beginning from the specified
offset to the end of the disk). This option is specified for each region. Note that
physical volumes have a maximum size of 16 TB. Therefore, the sum of all
regions assigned to the physical volume cannot exceed 16 TB.
Description
The tkadmin create pvol command creates a physical volume with the specified
name. The storage space for the volume is specified as one or more regions
(contiguous disk portions). The number of regions is specified in number_of_regions
and each region is described by its disk_name, disk_offset, and -regionsize
region_size. Region sizes are rounded down to a multiple of the chunk size. To
make the most efficient use of a disk, specify region sizes as a multiple of chunk
size.
Examples
Open Systems
The following command creates a physical volume named pvol1 that has two
regions. The first region takes up the entire /dev/rsd1g disk. The second region
takes 1024 pages of the /dev/rsd1e disk beginning at offset 1024.
%
tkadmin create pvol pvol1 16 2 /dev/rsd1g 0 /dev/rsd1e 1024 -regionsize 1024
Windows
The following command creates a physical volume named pvol1 that has two
regions. The first region takes up the entire \\.\D: logical disk drive. The second
region takes 1024 pages of the \\.\E: logical disk drive, beginning at offset 1024.
C:\> tkadmin create pvol pvol1 16 2 \\.\D: 0 \\.\E: 1024 -regionsize 1024
Related information
v tkadmin delete pvol on page 185
tkadmin delete disk

Purpose
Removes a disk from the Toolkit servers administration.
Synopsis
tkadmin delete disk -server server_name disk_name
183
Arguments
-server server_name
disk_name
Specifies the full path name of the disk to be removed. This must be the same
name that was used to initialize this disk. On Windows, a disk is an entire
physical disk specified in the form \\.\PHYSICALDRIVEnumber_of_drive (for
example, \\.\PHYSICALDRIVE3), a logical disk drive specified in the form
\\.\drive_name (for example, \\.\D:), or the full pathname of an operating system
file, including the drive letter (for example, D:\filevol1). This argument is
specified for each region.
Description
The tkadmin delete disk command removes a disk from the Toolkit servers
administration. This marks the disk as uninitialized. This command fails if there are
any physical volumes on the named disk. (You must delete all physical volumes on
a disk using the tkadmin delete pvol command before deleting the disk.)
Note: On Windows, the tkadmin delete disk command removes the disk name from
the servers administration, but does not remove the underlying file device.
Use the appropriate operating system command to delete the file or disk
partition.
Examples
Open Systems
The following command deletes the disk /dev/rsd1e:
%
tkadmin delete disk /dev/rsd1e
Windows
The following command deletes the logical disk \\.D::
C:\> tkadmin delete disk \\.\D:
Related information
v tkadmin delete pvol on page 185
tkadmin delete lvol

Purpose
Deletes a logical volume.
Synopsis
184
Arguments
-server server_name
logical_volume_name
Specifies the logical volume to be deleted.
Description
The tkadmin delete lvol command deletes the logical volume specified. This
command unmaps the last physical volume from this logical volume. Thus, all but
one replica of the data must be removed prior to deleting the logical volume (via the
tkadmin remove mirror command).
The names of logical volumes are permanently retained by the Toolkit server even
after the logical volume has been deleted. This allows the re-creation of a logical
volume at a future time (after it has been deleted) via the tkadmin recreate lvol
command. The contents of the re-created logical volume are restored from a
backup. Users who want to reuse the name of a logical volume after deleting it can
rename it.
Cautions
Before issuing this command, take the following cautions into consideration:
v This command fails if the logical volume is enabled.
v If you later need the contents of a deleted logical volume, you must restore the
volume from backup tapes.
To delete logical volumes on AIX, delete the mapping between the CICS
Toolkit logical volume and the AIX operating system logical volume with the
tkadmin unmap lvol command.
Examples
The following command deletes the logical volume lvol1:
%
tkadmin delete lvol lvol1
Related information
v tkadmin disable lvol on page 186
tkadmin delete pvol

Purpose
Deletes a physical volume.
Synopsis
tkadmin delete pvol -server server_name physical_volume_name
185
Arguments
-server server_name
Specifies the physical volume to be deleted.
Description
The tkadmin delete pvol command deallocates the disk space that the physical
volume occupies. This command fails if the specified physical volume is the only
physical volume mapped to a logical volume (that is, if the logical volume is not
mirrored).
Examples
The following example deletes the physical volume pvol3:
%
tkadmin delete pvol pvol3
Related information
tkadmin disable lvol

Purpose
MAkes a logical volume inaccessible for I/O.
Synopsis
tkadmin disable lvol -server server_name logical_volume_name
Arguments
-server server_name
logical_volume_name
Specifies the logical volume.
Description
The tkadmin disable lvol command makes a volume inaccessible for I/O. Disabling
a logical volume with this command persists across server restarts. Disabling
volumes can be used to speed restart and recovery if the Toolkit server uses many
data volumes.
Cautions
Disabling a volume is not allowed unless the server is in administrative mode.
However, in administrative mode all volumes are inaccessible. So disabling a
volume in administrative mode actually affects the state of the volume at the next
restart. Disabling a volume could prevent the server from restarting the next time
186
around. Volumes needed for server restarts must not be disabled. A logical volume
should only be disabled if you plan to delete it.
Examples
The following command disables the logical volume lvol8:
%
tkadmin disable lvol lvol8
Related information
v tkadmin enable lvol on page 190
tkadmin disable mediaarchiving

Purpose
Disables media archiving for the specified server.
Synopsis
tkadmin disable mediaarchiving -server server_name
Arguments
-server server_name
Description
The tkadmin disable mediaarchiving command disables the archiving of log records
for the specified Toolkit server. You can use this command to disable media
archiving for a server while the server is running.
Cautions
If you disable media archiving, you cannot restore server data after a media failure.
Examples
The following command stops media archiving for the server /.:/cics/sfs/mysfs:
%
tkadmin disable mediaarchiving -server /.:/cics/sfs/mysfs
Related information
v tkadmin query mediaarchiving on page 212
tkadmin dump ringbuffer

Purpose
Dumps the trace ring buffer.
Synopsis
tkadmin dump ringbuffer -server server_name file_name [-binary] [-overwrite]
187
Arguments
-server server_name
file_name
Specifies a destination for trace output (either an operating system file or
standard input/output stream). A complete or relative pathname can be
specified. If relative, the pathname is interpreted within the context of the
servers working directory.
[-binary]
Causes the trace output to be unformatted.
[-overwrite]
Causes the output file to be overwritten rather than appended.
Description
The tkadmin dump ringbuffer command dumps the contents of the ring buffer into
an operating system file. The main memory ring buffer captures trace data. The
tkadmin dump ringbuffer command formats the trace data and appends it to the
specified file. If the -binary option is used, the trace information is not formatted. If
the -overwrite option is used, the file is overwritten rather than appended.
Note: The tkadmin dump ringbuffer command should be used only as a diagnostic
tool. Using this command during normal server operation can degrade
performance.
Examples
The following command dumps the ring buffer to the file named ringbuffer.out:
%
tkadmin dump ringbuffer ringbuffer.out
Related information
v tkadmin set ringbuffer size on page 228

Purpose
Notifies a server that an archive file is now available online.
Synopsis
tkadmin enable archfile -server server_name archive_file_name
Arguments
-server server_name
archive_file_name
Specifies an archive file. The file name is composed of the name of the archive
device (specified when the log volume on which this servers log file is stored
was initialized), followed by an operating-system-specific path separator, the
188
name of the log volume, the .LA. string, and a sequence number. For example,
on Open Systems, an archive file might be specified as /var/cics_servers/
archives/mysfs/sfslogvol.LA.32..
Description
The tkadmin enable archfile on page 188 command informs a CICS Toolkit server
of the availability of a previously inaccessible (offline) log archive file. CICS Toolkit
servers that have media archiving enabled periodically write archive files into the
archive device directory associated with the servers log volume. You can move the
archive files to offline storage to conserve online storage space.
When the server needs to read data from an inaccessible archive file (when
restoring a log or data volume or displaying an old backup), the server displays a
message requesting that the operator fetch the file. The server then waits for an
operator to indicate that the file is available via this command.
The (offline) archive file should be restored to the archive device directory of its
associated log volume (the directory specified as the archive device associated with
the log volume on which this log file is stored). The name of the log volumes
archive device can be displayed via the tkadmin query logvol on page 211
command.
In some circumstances, you may not want to fetch a requested offline archive file,
for example, when displaying a very old backup. In this case, the command should
be issued with the specified file name without actually fetching the file. This serves
as a negative acknowledgment of the request and results in unblocking the server
thread that issued the request. The command that generated the request fails
gracefully.
Examples
Open Systems
The following command notifies the SFS server named /.:/cics/sfs/mysfs that the
/var/cics_servers/archives/mysfs/sfslogvol.LA.32 archive file is now available:
% tkadmin enable archfile -server /.:/cics/sfs/mysfs
/var/cics_servers/archives/mysfs/sfslogvol.LA.32
Windows
The following command notifies the SFS server named /.:/cics/sfs/mysfs that the
D:\opt\cics\sfs\mysfs\archives\sfslogvol.LA.17 archive file is now available:
C:\> C:\> tkadmin enable archfile -server /.:/cics/sfs/mysfs
D:\var\cics_servers\archives\mysfs\sfslogvol.LA.17
Related information
v tkadmin query logvol on page 211

Purpose
Enables a log file for use by a server.
189
Synopsis
tkadmin enable logfile -server server_name log_file_name
Arguments
-server server_name
log_file_name
Specifies the log file to be enabled. The format is log_volume/log_file_name,
where log_volume is the volume on which the log file is storedfor example,
sfs2logvol/sfslog.
Description
The tkadmin enable logfile on page 189 command enables a log file to be used by
a CICS Toolkit server. This command completes the initialization of the servers
Recovery Service. You must enable the log file before you can enable the server or
enable data volumes.
This command recovers enabled logical volumes (if any). The command should be
issued only once.
Examples
The following command enables the log file named sfslog for the server
/.:/cics/sfs/mysfs:
%
tkadmin enable logfile -server /.:/cics/sfs/mysfs mysfslogvol/sfslog
Related information
v tkadmin recover lvols on page 216
tkadmin enable lvol

Purpose
Makes a logical volume accessible for I/O.
Synopsis
tkadmin enable lvol -server server_name logical_volume_name
Arguments
-server server_name
logical_volume_name
Specifies the logical volume to be enabled.
Description
The tkadmin enable lvol command makes a volume accessible for I/O. Once
enabled, the logical volume must be initialized by the Toolkit server.
190
An enabled volume is mounted via the Volume Service and automatically recovered
at each server restart by the Recovery Service. During an automatic recovery,
updates lost because of a server crash are redone and in-progress transactions are
aborted.
Examples
The following command enables the lvol8 logical volume:
%
tkadmin enable lvol lvol8
Related information
v tkadmin disable lvol on page 186
tkadmin enable mediaarchiving

Purpose
Enables media archiving for a server.
Synopsis
tkadmin enable mediaarchiving -server server_name
Arguments
-server server_name
Description
The tkadmin enable mediaarchiving command enables the archiving of log records
for the specified Toolkit server. To back up and restore server data in the event of a
media failure, media archiving must be enabled.
Examples
The following command enables media archiving for the server /.:/cics/sfs/mysfs:
%
tkadmin enable mediaarchiving -server /.:/cics/sfs/mysfs
Related information
v tkadmin disable mediaarchiving on page 187
tkadmin expand lvol

Purpose
Expands a logical volume.
Synopsis
tkadmin expand lvol -server server_name logical_volume_name new_size
191
Arguments
-server server_name
logical_volume_name
Specifies the logical volume to expand.
new_size
Specifies the total size (in pages) of the new logical volume.
Description
The tkadmin expand lvol command increases the size of a logical volume. It adds
pages (new size - old size = additional pages) to the end of the logical volume. For
instance, if the volume contained pages 0 through N and was expanded by E
pages, the new pages are numbered N+1 through N+E. The output of the tkadmin
query lvol command includes the current size of the volume.
Each physical volume backing the logical volume must have at least new_size
pages, the number of pages in the expanded logical volume. If the physical
volumes are smaller than the logical volume, this command fails. To increase the
size of each physical volume, use the tkadmin expand pvol command.
A logical volume can be expanded while it is online and being used (I/O taking
place).
Examples
The following command expands the logical volume lvol1 to a size of 1024 pages:
%
tkadmin expand lvol lvol1 1024
Related information
v tkadmin expand pvol
tkadmin expand pvol

Purpose
Expands a physical volume.
Synopsis
tkadmin expand pvol -server server_name physical_volume_name number_of_regions
{{disk_name disk_offset [-regionsize region_size]}...}
Arguments
-server server_name
Specifies the physical volume to be expanded.
number_of_regions
space allows.
192
disk_name
On Open Systems, specifies the full path name of the disk that is providing
storage space for this region. The name specified must be the same name that
was used to initialize the disk. On Windows, specifies the logical disk drive, the
physical disk, or the full path name of the operating system file being used. On
disk_offset
Specifies the offset (in pages) into the disk where this region begins. The size
of a page is defined as 4K. This argument is specified for each region.
[-regionsize region_size]
Specifies the size (in pages) of the region allocated to the physical volume. This
value can vary greatly; 1 page is the smallest valid value. The largest value is
dependent on the disk size and usage. The region size is rounded down to a
multiple of the chunk size; therefore, the region size cannot be smaller than the
chunk size. The default region size is the entire remaining portion of the disk
(beginning from the specified offset to the end of the disk). This option is
Description
The tkadmin expand pvol command adds storage space to a physical volume. The
additional storage space is specified as one or more regions (contiguous disk
portions). The number of regions is specified in number_of_regions and each region
is described by the following three arguments: disk_name disk_offset -regionsize
region_size. Region sizes are rounded down to a multiple of the chunk size. To
make the most efficient use of a disk, specify region sizes as a multiple of chunk
size. Note that the maximum size allowed for a physical volume is 16 TB.
Examples
Open Systems
The following command expands the physical volume named pvol1 by adding 2
regions: 100 pages at offset 0 of disk /dev/rsd1f and the entire disk /dev/rsd1g
beginning at offset 100.
%
tkadmin expand pvol sfs_pvol1 2 /dev/rsd1f 0 -regionsize 100 /dev/rsd1g 100
Windows
The following command expands the physical volume named pvol1 by adding 2
regions: 100 pages at offset 0 of logical disk drive \\.\D: and the entire logical disk
drive \\.\E: beginning at offset 100.
C:\> tkadmin expand pvol sfs_pvol1 2 \\.\D: 0 -regionsize 100 \\.\E: 100
193
Related information
tkadmin flush lvol

Purpose
Propagates buffered changes to one or more logical volumes.
Synopsis
tkadmin flush lvol -server server_name [-lvolname logical_volume_name]
Arguments
-server server_name
[-lvolname logical_volume_name]
Specifies the specific logical volume for which you want to propagate all
buffered changes.
Description
The tkadmin flush lvol command propagates all buffered changes to the volume for
one or all of a servers data volumes. (The Recovery Service maintains a buffer
pool of pages belonging to data volumes under its control. The buffer pool is
managed as a write back cache; that is, page updates are cached in the buffer pool
and propagated to the data volumes at some time later.) To flush the changes of
one specific data volume, use the -lvolname option. To flush the changes of all
data volumes associated with the server (for which changes are buffered), do not
specify a specific volume.
Cautions
This command is not intended to be used with log volumes. If used on a log
volume, the command returns an error.
Examples
The following command flushes all the buffered changes to all logical volumes
associated with the /.:/cics/sfs/mysfs server.
%
tkadmin flush lvol -server /.:/cics/sfs/mysfs

Purpose
Writes log records from a log file to log archives.
Synopsis
194
Arguments
-server server_name
Description
The tkadmin flush mediaarchive on page 194 command writes cached log records
from a log file to log archive files. Because the server intermittently writes cached
data to archive files, there may be a delay before information about a recent
backup, for example, is written to the archive. This command can be used to
ensure that you have captured all recent activity in the log archive files. The
command writes changes to the active archive file, closes the file, and opens a new
log file for recording subsequent log activity.
Examples
The following command writes log records from a log file to the log archive files of
the server /.:/cics/sfs/mysfs:
%
tkadmin flush mediaarchive -server /.:/cics/sfs/mysfs
Related information
tkadmin force transaction

Purpose
Forces the outcomes of prepared transactions.
Synopsis
tkadmin force transaction -server server_name tid [-commitdesired] [-finish]
Arguments
-server server_name
[-commitdesired]
Forces the transaction to commit. Otherwise, the transaction is forced to abort.
[-finish]
Forces the transaction to finish regardless of whether or not its outcome has
been reported to all participating applications.
Description
The tkadmin force transaction command forces the outcome of the prepared
transaction, tid. Forcing a transaction to commit or abort releases the locks held by
that transaction. If the -commitdesired option is used, the transaction is committed;
otherwise, the transaction is aborted. (The output of the tkadmin list transactions
command shows the states of unresolved transactions.) If the -finish option is
used, the transaction is forced to finish even though the outcome has not been
195
reported to all participating applications (normally a requirement of a transactions

completion). This option is useful if one of the participating applications is no longer
available.
Cautions
You must force transactions with caution. Inconsistencies can be introduced into
server data by forcing a transaction to the wrong outcome (for instance, forcing it to
commit when it would have aborted). If the true outcome of the transaction is
unclear, it is safer for you to force the transaction to abort.
Examples
The following command forces transaction 2000 to commit:
%
tkadmin force transaction 2000 -commitdesired
Related information
v tkadmin abort transaction on page 178
tkadmin init disk

Purpose
Initializes a Volume Service disk.
Synopsis
Arguments
-server server_name
disk_name
Specifies the full path name of the disk partition to be initialized. On Open
Systems, the raw (unbuffered) interface to the disk should be used, as opposed
to a buffered disk. On Windows, a disk is an entire physical disk specified in the
form \\.\PHYSICALDRIVEnumber_of_drive (for example, \\.\PHYSICALDRIVE3),
a logical disk drive specified in the form \\.\drive_name (for example, \\.\D:), or
the full pathname of an operating system file, including the drive letter (for
example, D:\filevol1).
Description
The tkadmin init disk command initializes the specified disk to be used by the
Toolkit server. All disks must be initialized via this command before physical
volumes can be created.
Cautions
You should verify that this disk is not used. Calling this function on a disk that
belongs to a different server makes all data present on that disk unusable. (This
196
command overwrites the control data on a disk. The control data identifies the
owner of the data and the location of the data on the disk.)
In addition, you must have appropriate permissions (read and write) to the disk
partition initialized.
Examples
Open Systems
The following command initializes the disk /dev/rsd1e:
%
tkadmin init disk /dev/rsd1e
Windows
The following command initializes the logical disk drive \\.\D::
C:\> tkadmin init disk \\.\D:
Related information
v tkadmin delete disk on page 183
tkadmin list disks

Purpose
Lists all initialized disks.
Synopsis
tkadmin list disks -server server_name
Arguments
-server server_name
Description
The tkadmin list disks command lists all disks that have been initialized by the
Toolkit server. Once a disk is initialized for use by a specific server, no other server
can use the disk until the disk has been deleted (removed from the servers
administration) via the tkadmin delete disk command and reinitialized for use by the
intended server.
Note: On Window, a disk is an entire physical disk specified in the form
logical disk drive specified in the form \\.\drive_name (for example, \\.\D:), or
the full pathname of an operating system file, including the drive letter (for
example, D:\filevol1).
197
Examples
Open Systems
The following command lists all disks initialized by the server:
%
tkadmin list disks
/dev/rsd1e
/dev/rsd1f
Windows
The following command lists all disks initialized by the server:
C:\> tkadmin list disks
\\.\D:
\\.\E:
Related information
v tkadmin query disk on page 210
v tkadmin delete disk on page 183
tkadmin list lvols

Purpose
Lists logical volumes.
Synopsis
tkadmin list lvols -server server_name [-enabled]
Arguments
-server server_name
[-enabled]
Provides a list of only enabled logical volumes.
Description
The tkadmin list lvols command lists all existing logical volumes. The -enabled
option of this command lists all enabled logical volumesthat is, volumes that are
ready for I/O.
Examples
The following command lists all the enabled logical volumes:
%
tkadmin list lvols -enabled
lvol1
lvol2
Related information
v tkadmin query lvol on page 211
198
tkadmin list pvols

Purpose
Lists physical volumes.
Synopsis
tkadmin list pvols -server server_name
Arguments
-server server_name
Description
The tkadmin list pvols command lists all physical volumes created by the Toolkit
server.
Note: This command is not for use on the AIX operating system.
Examples
The following command lists all physical volumes created by the server:
%
tkadmin list pvols
pvol1
pvol2
Related information
v tkadmin query pvol on page 213

Purpose
Lists the trace output destinations for all classes.
Synopsis
tkadmin list redirect -server server_name
Arguments
-server server_name
Description
The tkadmin list redirect command can be used to list the trace output destination
for all trace classes. You can set the destination of trace output when a server is
initially started by using the -T option of the server start-up command. You can
redirect trace output (after a server is running) using the tkadmin redirect trace
command.
199
Examples
The following command lists all trace classes and their corresponding destinations
(if set):
%
entry:
event:
param:
audit: [formatted,unbuffered]STREAM:stderr
dump:
fatal: [formatted,unbuffered]STREAM:stderr
Related information
v tkadmin query redirect on page 214
v tkadmin redirect trace on page 218
tkadmin list rmi

Purpose
Lists all resource manager instances (RMI) associated with a server.
Synopsis
tkadmin list rmi -server server_name
Arguments
-server server_name
Description
The tkadmin list rmi command lists information on RMIs currently registered by a
server.
tkadmin list trace

Purpose
Lists components and their corresponding trace masks.
Synopsis
tkadmin list trace -server server_name [-product product_name]
Arguments
-server server_name
[-product product_name]
Specifies the product name, such as CICS Toolkit Executive, for which trace
masks are displayed. Product names containing spaces must be enclosed in
double quotes. The following aliases are also valid product names: all, exec,
200
server, sfs, ppc, and private. For example, exec (CICS Toolkit Executive)
includes several components such as threadTid, trdce and trpc.
Specifies the component name for which trace masks are displayed.
Description
The tkadmin list trace command displays trace masks for all components in a
server, a specific component, or all components within a product. A trace mask is a
variable that controls the amount of tracing for a component. If the command is
used without options, the trace masks for all components in the server are
displayed. If the -product option is used, the trace masks for all of the components
belonging to the specified product are displayed. If the -component option is used,
the trace masks for the specified component are displayed.
The tkadmin list trace command displays the trace mask as a string of one or more
trace options, such as trace_entry or trace_param. To display a components trace
mask in hexadecimal form, use the tkadmin query trace command. Note that it may
be possible to represent the same trace mask value with more than one string of
trace options. Only one of the possible strings is displayed for each trace mask.
Examples
The following command lists the trace masks for all components in the server:
%
tkadmin list trace
CICS Toolkit Server Core:

lock=0
rec=default
log=default
vol=default
restart=0
CICS Toolkit Area Manager:
area=default
CICS Toolkit Executive:
threadTid=0
alf=0
tran=0
tc=0
trpc=trace_all
trdce=trace_all
epm=0
admin=default
util=0
CICS Toolkit Private:
npr=0
sutils=0
startup=0
CICS SFS:
sfs_dir=0
sfs_ar=general
sfs_es=0
sfs_rel=0
sfs_btree=0
sfs_ddt=0
201
sfs_svr=trace_all
CICS Toolkit BDE:
bde=0
The following command lists the trace masks for all components in the CICS Toolkit
Executive using the exec alias:
%
tkadmin list trace -product exec

threadTid=0
alf=0
tran=0
tc=0
trpc=trace_all
trdce=trace_all
epm=0
admin=default
util=0
The following command displays the trace mask for the tran component:
%
tkadmin list trace -component tran

tran=0
Related information
v tkadmin query trace on page 214
v tkadmin trace specification on page 230

Purpose
Lists unresolved transactions in a server and their current state.
Synopsis
tkadmin list transactions -server server_name [-originator application]
[-participant application] [-global identifier]
Arguments
-server server_name
[-originator application]
Specifies the application that initiated the transactionthat is, the application
that issued the begin tran functionality.
[-participant application]
Specifies the participating application in the transaction.
[-global identifier]
Specifies the global identifier for the transaction.
Description
The tkadmin list transactions command lists the identities of unresolved transactions
in a server and their current states. The state of an unresolved transaction is crucial
when attempting to abort a transaction or to force an outcome. The state of the
transaction can be one of the following:
202
v active The transaction is currently active in the server. The state indicates that
the server has begun but not ended the transaction, the server has received but
not replied to an RPC for this transaction, or a before-prepare callback is in
progress that permits work to be done on this transaction.
v inactive The transaction has been active before, but is no longer active. It is
not legal to make RPCs on behalf of the transaction. It is legal to abort the
transaction; however, to commit the transaction, the application must be prepared
to commit.
v preparing The recovery services in the server are being asked to prepare the
transaction. A recovery service is permitted to do work as necessary to prepare,
but no other work is permitted on behalf of the transaction.
v prepared All participants have agreed to commit a transaction. An application
participating in the transaction can no longer perform work on behalf of the
transaction or unilaterally decide to abort the transaction. The application must
accept the instructions of the transaction coordinator (to commit or to abort).
v committing The recovery services are being informed that the transaction has
committed.
v committed All recovery services have committed the work associated with the
transaction such that the results of the work can be observed by other
transactions. After-resolution callbacks take place in this state.
v commit complete The transaction has completed all commitment-related
actions. Commit upcalls and after-resolution callbacks have been completed. The
transaction is not yet finished. Additional tasks such as reporting heuristic
damage to other participants or completing the requirements of the transaction
protocol are not yet complete.
v before abort The transaction has aborted but recovery services have not been
informed that the transaction is aborting. Before-abort callbacks are made in this
state. Abort delays leave the transaction in this state after the before-abort
callbacks.
v aborting The recovery services are being informed that the transaction is
aborting.
v aborted All recovery services have rolled back the work associated with the
transaction. No effects can be observed by other transactions. After-resolution
callbacks take place in this state.
v abort complete The transaction has completed all abort-related actions. Abort
upcalls and after-resolution callbacks have been completed. The transaction is
not yet finished. Additional tasks such as reporting heuristic damage to other
participants or completing the requirements of the transaction protocol are not yet
complete.
v finished All transaction service functions have taken place for this transaction.
After-finished callbacks take place in this state.
v present An RPC is in progress on behalf of this transaction, but no application
module has registered to participate. This state is not currently used.
v none The application has not directly participated in the transaction. The
application has neither begun nor received an RPC for the transaction. The
application possibly obtained the transaction identifier by using the transaction
relationship functions (parent, descendant, or top ancestor) or from a recovery
service upcall. When a transaction is in this state, the application is not permitted
to perform work on behalf of the transaction.
The following modifiers can be used to list specific unresolved transactions: the
-originator option is used to specify the application that initiated the transaction; the
-participant option is used to specify a participating application; and the -global
203
option is used to specify the global identifier for the transaction.
Examples
In the following example, transaction 29188 is inactive and waiting for one or more
locks. Subtransaction 29937, in the same transaction family as transaction 29188, is
also inactive and waiting for one or more locks. Transaction 38766 is preparing (and
now cannot be aborted via the tkadmin abort transaction command). Transaction
65536 is active and is holding one or more locks. Subtransaction 65992 is active
and holding one or more locks; subtransaction 66452 is inactive and holding one or
more locks.
The (W) indicates that a transaction is blocked, waiting for a lock. The (H) indicates
that a transaction is holding a lock. Subtransaction states are shown indented
beneath parent transactions.
%
29188 inactive (W)

29937 inactive (W)
38766 preparing
65536 active (H)
65992 active (H)
66452 inactive (H)
Related information
tkadmin map lvol

Purpose
Maps an AIX logical volume to a CICS Toolkit logical volume.
Synopsis
tkadmin map lvol -server server_name logical_volume_name
Arguments
-server server_name
logical_volume_name
Specifies the CICS Toolkit logical volume to be created by mapping it to an AIX
logical volume.
Specifies the AIX logical volume that is to be used as a backing store for the
CICS Toolkit logical volume.
chunk_size
Specifies the number of pages that can be used by the Toolkit server as an
allocation unit.
204
Description
The tkadmin map lvol command creates a new logical volume by using an AIX
logical volume as the backing store for it. (On AIX, operating system logical
volumes can be used as alternatives to physical volumes.) The new logical volume
inherits all the physical attributes of the AIX volume for example, the disk layout
and mirroring characteristics. The physical attributes of the new logical volume can
be manipulated via the AIX administrative facilities, for example, the SMIT LVM
utility.
The advantage of creating a logical volume in this way is that you can set the disk
storage attributes of all applications using the same tools provided by the operating
system.
After mapping the CICS Toolkit logical volume to an AIX logical volume, the CICS
Toolkit logical volume must be enabled.
The chunk size is normally used to specify the minimum size of the volume
physically contiguous on disk. However, when mapping an AIX volume, the Toolkit
volume service has no control over the physical layout of the volume. The chunk
size is merely stored by the volume service for possible use by its clients. It should
be set in accordance with the physical characteristics of the AIX volume.
Cautions
v You should not change the name of the AIX logical volume after mapping it to an
v As each Toolkit server manages its own physical storage, one server cannot
know the location of another servers volumes. You must prohibit multiple use of
AIX logical volumes.
Note: This command is for use on the AIX operating system only and applies only
if AIX logical volume management is being used.
Examples
The following command creates a new logical volume named lvol1 using the AIX
volume aix_lvol1 as the backing store and sets the chunk size of the volume to 8
pages:
%
tkadmin map lvol lvol1 aix_lvol1 8
Related information
v tkadmin unmap lvol on page 232
v tkadmin remap lvol on page 220
tkadmin move pvol

Purpose
Moves a physical volume to a different set of disks.
205
Synopsis
tkadmin move pvol -server server_name physical_volume_name number_of_regions
{{source_disk_name source_disk_offset region_size destination_disk_name
destination_disk_offset}...}
Arguments
-server server_name
Specifies the physical volume to be moved.
number_of_regions
space allows.
source_disk_name
On Open Systems, specifies the full path name of the disk that is storing the
source region. The name specified must be the same name that was used to
initialize the disk. On Windows, specifies the entire physical disk, the logical
disk drive, or the full path name of the operating system file being used. On
Note: If you are using an entire physical disk on a Windows system, you must
source_disk_offset
Specifies the offset (in pages) into the disk where the source region begins. The
size of a page defined as 4K. This argument is specified for each region.
region_size
Specifies the size (in pages) of the region to be moved. This value can vary
greatly; 1 page is the smallest valid value. The largest value is dependent on
the disk size and usage. The region size cannot be smaller than the chunk size.
This argument is specified for each region.
destination_disk_name
On Open Systems, specifies the disk to which this region is being moved. The
name specified must be the same name that was used to initialize the disk. On
Windows, specifies the entire physical disk, the logical disk drive, or the full
path name of the operating system file being used. On Windows, a disk is an
entire physical disk specified in the form \\.\PHYSICALDRIVEnumber_of_drive
(for example, \\.\PHYSICALDRIVE3), a logical disk drive specified in the form
\\.\drive_name (for example, \\.\D:), or the full pathname of an operating system
file, including the drive letter (for example, D:\filevol1). This argument is
Note: If you are using an entire physical disk on a Windows system, you must
destination_disk_offset
Specifies the offset (in pages) on the disk where the moved region is to begin.
The size of a page is defined as 4K. This argument is specified for each region.
206
Description
The tkadmin move pvol command moves regions backing a physical volume to new
storage locations. The destination regions, where the data will be stored, cannot
overlap any currently used regions. The size of a region remains constant; that is,
the size of the destination region is equal to the size of the source region.
Before a logical volume can be restored, it must be backed by functional disks. One
way to achieve that state is to move regions of physical volumes from nonfunctional
disks to functional disks. Physical volumes can be moved using this command.
Cautions
If the physical volume is mapped to a logical volume, the logical volume must be
disabled. (You must start the server in administrative mode.)
Examples
Open Systems
The following command moves two regions of the physical volume pvol5, each of
size 100 pages. Region 1 is moved from the disk /dev/rsd1f at offset 0 to the disk
/dev/rsd1g at offset 0. Region 2 is moved from the disk /dev/rsd1f at offset 100 to
disk /dev/rsd1g at offset 100.
% tkadmin move pvol pvol5 2 /dev/rsd1f 0 100 /dev/rsd1g 0 /dev/rsd1f \
100 100 /dev/rsd1g 100
Windows
The following command moves two regions of the physical volume pvol5, each of
size 100 pages. Region 1 is moved from the logical disk drive \\.\D: at offset 0 to
the logical disk drive \\.\E: at offset 0. Region 2 is moved from the logical disk drive
\\.\D: at offset 100 to logical disk drive \\.\E: at offset 100.
C:\> tkadmin move pvol pvol5 2 \\.\D: 0 100 \\.\E: 0 \\.\D: 100\
100 \\.\E: 100
Related information
v tkadmin expand pvol on page 192
tkadmin query backup

Purpose
Displays information about a backup of a volume.
Synopsis
tkadmin query backup -server server_name logical_volume_name
[-backupfilenum backup_file_number] [-count count] [-all]
207
Arguments
-server server_name
logical_volume_name
Specifies the logical volume that was backed up.
[-backupfilenum backup_file_number]
Specifies the sequence number of the backup file name for which to display
information. The default is the sequence number of the last complete backup of
the volume.
[-count count]
Specifies the number of complete, independent backups for which to display
information, starting with the most recent backup.
[-all]
Displays information for all backups of the volume.
Description
The tkadmin query backup command displays information about the last complete
backup for the specified volume. Where multiple backups of a volume exist,
information about a specific backup can be displayed by using the -backupfilenum
option. Alternatively, information about a specified number of complete, independent
backups can be displayed with the -count option, or information about all backups
of a volume can be displayed with the -all option.
The command displays the following information for each backup file:
v The directory in which the backup file was or is being written.
v The backup file name.
v The date the backup was started.
v The state of the backup file. The state of a backup file can be in progress if the
file is not complete, or end of backup if the file ends a complete backup. If no
state is displayed, the file is complete.
For each complete backup, the output displays the earliest log archive file required
to restore the volume with the backup.
Examples
The following command displays information about the most recent backup of the
volume testVol:
%
tkadmin query backup testVol
A backup for volume testVol comprises 4 files:

In directory <directory path>:
testVol.TRB.000015 (started Tue Oct 3 19:14:32 1995,
end of backup 15)
end of backup 16)
end of backup 17)
end of backup 18)
Earliest log archive file required to restore this data volume from
this backup (without restoring associated log volume):
208
log/logvol.LA.92
The following command displays information about all backups of the volume Lvol:
%
tkadmin query backup Lvol -all
Volume Lvol contains the following complete backups.

Lvol.TRB.000047 (started Wed Oct 4 16:47:55 1995)
Earliest MRA file required to restore this data volume from
this backup: log/logvol.LA.92
3: The next complete backup comprises the following 3 files:
The following command displays information about the last two complete,
independent backups of the volume Lvol:
%
tkadmin query backup Lvol -count 2
Volume Lvol contains the following complete backups.

209
Related information
v tkadmin backup lvol on page 180
tkadmin query disk

Purpose
Returns detailed information about a disk.
Synopsis
tkadmin query disk -server server_name disk_name
Arguments
-server server_name
disk_name
Specifies the disk to be queried. On Open Systems, this name is the name of
the character-interface to the diskfor instance, /dev/rsd1eas opposed to the
name of the block-interface to the disk. On Windows, specifies the entire
physical disk, the logical disk drive, or the full path name of the operating
system file being used. On Windows, a disk is an entire physical disk specified
in the form \\.\PHYSICALDRIVEnumber_of_drive (for example,
\\.\PHYSICALDRIVE3), a logical disk drive specified in the form \\.\drive_name
(for example, \\.\D:), or the full pathname of an operating system file, including
the drive letter (for example, D:\filevol1).
Description
The tkadmin query disk command displays the following information about the disk:
v Disk size
v Information about regions on the disk: the starting offset, the size, and the name
of the physical volume to which it belongs
If the disk queried is not initialized, this command fails. Using the information
provided by this command, you can calculate the available space on a disk.
Examples
Open Systems
The following command displays information for the disk /dev/rsd1e:
%
tkadmin query disk /dev/rsd1e
Information about disk /dev/rsd1e

All sizes and offsets are in pages, page size is 4Kbytes.
Disk Size: 1180
Disk Usage:
region [ 0]: offset:
0 size: 100 pvol: pvol1
region [ 1]: offset: 100 size: 1000 pvol: pvol2
Windows
The following command displays information for the disk \\.\D::
210
C:\> tkadmin query disk \\.\D:

Information about disk \\.\D:
All sizes and offsets are in pages. Page Size is: 4 Kbytes
size: 1023
numRegions: 1
region 0: offset:
0 size:
960 pvol: sfsLogPvol
Related information
v tkadmin list disks on page 197
tkadmin query logvol

Purpose
Displays information about a logical volume storing log data.
Synopsis
tkadmin query logvol -server server_name log_volume_name
Arguments
-server server_name
log_volume_name
Specifies the log volume about which information is to be displayed.
Description
The tkadmin query logvol command displays the following information about the
specified log volume:
v
v
v
v
The
The
The
The
names of the log files stored on the volume

name of the associated archive device
name of the oldest archive file stored on that device
available free space on the log volume
This command cannot be used to display information about a log volume that is
being initialized, recovered, or restored.
Examples
The following command displays information about the sfsLogVol log volume:
%
tkadmin query logvol sfsLogVol
Information about log volume : sfsLogVol

Archive device : logarchive
Number of free pages : 640
Number of log files : 1
Log file list :
sfsLogfile
tkadmin query lvol

Purpose
Obtains information about a logical volume.
211
Synopsis
tkadmin query lvol -server server_name logical_volume_name
Arguments
-server server_name
logical_volume_name
Specifies the logical volume to be queried.
Description
The tkadmin query lvol command displays information about a logical volume. The
information includes the total size of the logical volume, its chunk size, its state, the
names of the physical volumes backing it, and the state of each physical volume.
Examples
In the following example, the sfsDataVolume logical volume is queried:
%
tkadmin query lvol sfsDataVolume
Information about logical volume sfsDataVolume

size: 1984
chunkSize: 64
Backing physical volumes
(only clean and dirty volumes are active):
sfsDataPvolume (clean)
sfsDataPvolMirr (stale)
Volume is currently enabled.
Related information
v tkadmin list lvols on page 198

Purpose
Displays the media archiving setting for a server.
Synopsis
tkadmin query mediaarchiving -server server_name
Arguments
-server server_name
Description
The tkadmin query mediaarchiving command displays the media archiving setting
for the specified server. Media archiving is either enabled or disabled for a server.
212
Examples
The following command displays the media archiving status for a server:
%
Media archiving is disabled.
Related information
v tkadmin disable mediaarchiving on page 187
tkadmin query pvol

Purpose
Obtains detailed information about a physical volume.
Synopsis
tkadmin query pvol -server server_name physical_volume_name
Arguments
-server server_name
Specifies the physical volume to be queried.
Description
The tkadmin query pvol command displays information about the physical volume.
The information includes the total size of the physical volume, its chunk size,
descriptions of its layout on one or more disks, and the name of the logical volume
to which it is mapped.
Examples
Open Systems
In the following example, the pvol1 physical volume is queried.
%
tkadmin query pvol pvol1
Information about physical volume pvol1

All sizes and offsets are in pages, Page Size is 4Kbytes
Mapped to logical volume lvol1
Chunk Size: 8
numRegions: 2
region 0: disk: /dev/rsd1f size: 496
region 1: disk: /dev/rsd1e size: 496
Windows
In the following example, the sfsDataPvol physical volume is queried.
C:\> tkadmin query pvol sfsDataPvol
213
Information about physical volume sfsDataPvol

Mapped to logical volume sfsDataVol
chunkSize: 64
numRegions: 1
region 0: disk: \\.\D: offset: 0 size: 960
total size: 960
Related information
v tkadmin list pvols on page 199
tkadmin query redirect

Purpose
Lists the trace output destination for a specified class.
Synopsis
tkadmin query redirect -server server_name
{entry | event | param | audit | dump | error | fatal | trace}
Arguments
-server server_name
Specifies the class of trace output. The argument can be one of the standard
trace classes: entry, event, param, audit, dump, error, fatal, or trace.
Description
The tkadmin query redirect command can be used to list the trace output
destination for a specific trace class. You can set the destination of trace output
when a server is initially started by using the -T option of the server start-up
command. You can redirect trace output (after a server is running) using the
tkadmin redirect trace command.
Examples
The following command displays the trace output destination for the error trace
class:
%
tkadmin query redirect error
Related information
v tkadmin list redirect on page 199
v tkadmin redirect trace on page 218
tkadmin query trace

Purpose
Lists trace mask and trace options for the specified component.
214
Synopsis
tkadmin query trace -server server_name component_name
Arguments
-server server_name
component_name
Specifies the component name for which trace options are displayed. Use the
tkadmin list trace command to obtain a list of components in a server.
Description
The tkadmin query trace command lists the current trace mask (in hexadecimal
form) and all valid trace options for the specified component. A trace mask is a
variable that controls the amount of trace output for a component. Trace options are
identified by string names and their corresponding hexadecimal values. These trace
options can be used with commands such as tkadmin trace specification to control
the amount of tracing for a component.
To display a components trace mask in string form, as used by the tkadmin trace
specification command, use the tkadmin list trace command.
Examples
The following command displays the current value of the trace mask variable for the
tmxa component and trace options recognized for the tmxa component:
%
tkadmin query trace tmxa
0x00000401:
0x00000100:
0x00000200:
0x00000400:
0x00000800:
0x00001000:
tmxa_traceMask
xa
lock
callback
xa90
init
Related information
v tkadmin list trace on page 200
v tkadmin trace specification on page 230
tkadmin query transaction

Purpose
Displays information about a transaction.
Synopsis
tkadmin query transaction -server server_name tid [-state] [-originator]
[-participants] [-global] [-start]
Arguments
-server server_name
215
[-state]
Shows transaction state information for the server.
[-originator]
Shows the application that initiated the transactionthat is, the application that
issued the begin tran functionality.
[-participants]
Lists the participating applications in the transaction.
[-global]
Shows the global identifier for the transaction.
[-start]
Shows the start time for the transaction. If the transaction is a subtransaction,
the start time is displayed for the parent transaction. (Start times are recorded
on a per-family basis, not for each individual subtransaction.)
Description
The tkadmin query transaction command displays information about the specified
transaction. (Valid transaction identifiers for a server can be displayed with the
tkadmin list transactions command.) By default, all information is displayed and
preceded by descriptive field names. To display information without the field names
(if, for example, the information is to be used in a script), the appropriate options
must be specified.
Examples
The following command displays information about transaction 65536. The output
includes the descriptive field names.
%
tkadmin query transaction 65536
Global identifier: 0001000001120101e0823800ef0b861da930c037cf57aa77

State: commitcomplete
Originator: 0101e0823800ef0b861da930c037cf57aa77
Participants: 0101e0823800ef0b861da930c037cf57aa77
Start time: Thu Mar 12 17:06:06 1998
The following command displays state information, only, for transaction 65536 :
%
tkadmin query transaction 65536 -state
commitcomplete
The following command displays the start time, only, for transaction 65536 :
%
tkadmin query transaction 65536 -start
Thu Mar 12 17:06:06 1998
Related information

Purpose
Recovers data on enabled logical volumes.
216
Synopsis
tkadmin recover lvols -server server_name
Arguments
-server server_name
Description
The tkadmin recover lvols command brings a servers data volumes up to date with
the information in the servers log file, if any, and mounts the enabled logical
volumes, if any. You cannot create or use data volumes for the server until after
issuing this command. This command should be issued only once.
Examples
The following command recovers the enabled logical volumes of the server
/.:/cics/sfs/mysfs:
%
tkadmin recover lvols -server /.:/cics/sfs/mysfs
tkadmin recreate lvol

Purpose
Re-creates a deleted logical volume.
Synopsis
tkadmin recreate lvol -server server_name logical_volume_name physical_volume_name
Arguments
-server server_name
logical_volume_name
Specifies the logical volume to re-create.
Specifies the physical volume to back the logical volume.
Description
The tkadmin recreate lvol command is used to re-create a deleted logical volume by
establishing a mapping to an existing physical volume. This command is used to
re-create a logical volume that once existed but had all of its physical volumes
destroyed (for example, by a disk crash). This is usually a prelude to restoring the
contents of the logical volume from a backup via the tkadmin restore lvols
command. The difference between this command and the tkadmin create lvol
command is that this makes the contents of the logical volume visible via the same
logical volume name that was previously used.
Note: Do not use this command if you are using AIX logical volume management
(LVM). Re-creating logical volumes through AIX LVM is done by remapping
217
the CICS Toolkit logical volume to the AIX operating system logical volume.
Use the tkadmin remap lvol command to re-create an AIX logical volume.
Examples
The following command re-creates the logical volume named lvol1 by mapping it to
the physical volume named pvol1:
%
tkadmin recreate lvol lvol1 pvol1
Related information
tkadmin redirect trace

Purpose
Redirects trace output to a file or special destination.
Synopsis
tkadmin redirect trace -server server_name
[-destination destination]
Arguments
-server server_name
Specifies the class of trace output. The argument can be one of the standard
trace classes: entry, event, param, audit, dump, error, fatal, or trace. The
trace classes are described in the TXSeries for Multiplatforms SFS Server and
PPC Gateway Server: Advanced Administration.
[-destination destination]
Specifies a file or special destination to which trace output is to be redirected.
See the Description section for more information.
Description
The tkadmin redirect trace command redirects the output of the specified trace
class to a file or special destination. By using the -destination option of this
command, you can redirect trace output from any class to a file, a standard
input/output stream, or the AIX trace or error logging facility. If the -destination
option is omitted, trace output is redirected to the default destination of the specified
trace class. By default, all trace output is sent to a main memory ring buffer, and
output from the fatal, error, and audit trace classes is redirected to the Serious
Event Subscription Facility and the servers standard error stream.
The following destinations are valid:
v A relative or complete pathname of a file (for example, trace.data). If a relative
pathname is specified, the file is stored relative to the current working directory of
the server. If the file already exists, tracing information is appended to the file.
v A standard input/output stream (for example, the msg file in the servers working
directory).
v The AIX trace (trace) or error logging (errlog) facilities.
218
Note that the trace and errlog names are meaningful only to servers running on
the AIX operating system.
The -destination option accepts the following syntax:
[[option...]]destination_type[(context_string)]:destination
The optional [option...] argument can be one or more of the following:

v buffered buffered output. Buffered output improves performance by
minimizing system calls but can cause some trace output to be lost during a
crash. This option can take an argument of maximum_size in the form
buffered=maximum_size. The maximum_size argument specifies the maximum
number of bytes of trace output that are buffered before the output is routed to its
destination. The default is 64 KB.
v unbuffered unbuffered output (the default). Unbuffered output can degrade
performance but guarantees that all trace output is routed to its destination in the
event of a crash.
v formatted formatted output (the default). Formatted output is in
human-readable (ASCII) form. This option can take an argument of format_mode
in the form formatted=format_mode. The format_mode argument controls the
amount of trace information that is displayed. Its value is an unsigned integer
interpreted as a bit mask. If a bit is set in the mask, the corresponding field
appears in the formatted trace output. If no value is specified, all fields except the
high-order 16 bits of the process ID are displayed. The thread ID, message
prefix, and message always appear in the formatted output. Other fields are
controlled by the following bit values:
1 hours, minutes, and seconds
2 date
3 milliseconds
4 microseconds
0x10 low-order 16 bits of process ID
0x20 all bits of process ID
0x40 local time instead of Greenwich Mean Time (GMT)
0x100 trace ID
v unformatted unformatted (binary) output. Unformatted output improves
performance by reducing the amount of work that must be done during
redirection. For optimal performance, it is best to collect trace output in
unformatted form and translate it into ASCII format later with the interpretTrace
utility.
Multiple options must be separated with a , (comma).
The destination_type argument must appear in uppercase and can be one of the
following: FILE, STREAM, orAIX. The destination argument can be one of the
following:
v For the FILE destination type, a filename
v For the STREAM destination type, a standard input/output stream
v For the AIX destination type, the AIX trace (trace) or error logging (errlog)
facilities
The tkadmin redirect trace command can be issued multiple times to redirect
different trace classes to different destinations. For example, you can use the
command to redirect trace dump output to a file named dump.out then use it a
219
second time to redirect trace error output to the AIX errlog facility. However, for
any given server, each trace class can be redirected only to one destination. For
instance, if you redirect a servers trace dump output to a file named dump.out
and then reissue the command to redirect trace dump output to stdout, trace
dump output is directed only to stdout.
When redirecting trace output for multiple trace classes to the same file, be sure to
specify the same filename (exact string) with each tkadmin redirect trace command.
If the filenames are not exactly the same (that is, if one is specified as a relative
pathname and one is specified as the full pathname), proper interleaving of the
trace output does not occur.
We recommend that trace output files reside in the primary local directory where the
server was started. For example, for server sfs1 running on an Open Systems host,
trace output files should reside in /var/cics_servers/SSD/cics/sfs/sfs1/trace/
events.. The file must be writable by the server; that is, if it belongs to the local file
system, it must be on the same host as the server.
Note: On Windows, applications that do not have standard output or standard error
streams cannot use the STREAM destination type. In this case, use the
environment variable CICS_TK_TRACE_REDIRECT to redirect tracing. The
value of the variable uses the same syntax as the -T option of the server
start-up command.
Examples
The following command redirects trace dump output to a file named dump.out:
%
tkadmin redirect trace dump -destination FILE:dump.out
The following command redirects trace error output to the AIX errlog facility. The
output includes all bits of the process ID in addition to the thread ID, message
prefix, and message.
%
tkadmin redirect trace error -destination [formatted=0x20]AIX:errlog
The following command redirects trace entry, event, and param output to the
stdout stream without buffering:
%
tkadmin redirect trace trace -destination [unbuffered]STREAM:stdout
tkadmin remap lvol

Purpose
Remaps an AIX operating system logical volume to a CICS Toolkit logical volume.
Synopsis
Arguments
-server server_name
logical_volume_name
Specifies the logical volume to be created by remapping the AIX volume.
220
Specifies the AIX volume to be used to store the newly re-created logical
volume.
chunk_size
Specifies the number of pages that can be used by the Toolkit server as an
allocation unit.
Description
The tkadmin remap lvol command remaps an unmapped CICS Toolkit logical
volume to an AIX logical volume. (On AIX, operating system logical volumes can be
used as alternatives to physical volumes.) This command is analogous to the
tkadmin recreate lvol command, but is used when a CICS Toolkit logical volume is
backed by an AIX logical volume.
This command is used to re-create a logical volume that once existed but had the
AIX volume used as its backing storage destroyed (for example, by a disk crash).
This is usually a prelude to restoring the contents of the logical volume from a
backup via the tkadmin restore lvols command.
The new logical volume inherits all the physical attributes of the AIX volume (for
example, the disk layout and mirroring characteristics). The physical attributes of
the new logical volume can be manipulated via the AIX administrative facilities (for
instance, the SMIT LVM utility). The difference between this command and the
tkadmin map lvol is that this makes the contents of the logical volume visible via the
same logical volume name that was previously used.
Cautions
v You should not change the name of the AIX logical volume after mapping it to a
v As each Toolkit server manages its own physical storage, one server cannot
know the location of another servers volumes. You must prohibit multiple use of
AIX logical volumes.
Note: This command is for use on the AIX operating system only.
Examples
The following command remaps the operating system volume aix_lvol1 to the
logical volume lvol1:
%
tkadmin remap lvol lvol1 aix_lvol1 8
Related information
v tkadmin unmap lvol on page 232

Purpose
Removes a mirror from a CICS Toolkit logical volume.
221
Synopsis
tkadmin remove mirror -server server_name logical_volume_name physical_volume_name
Arguments
-server server_name
logical_volume_name
Specifies the logical volume for which the mirror is being removed.
Specifies the physical volume that stores the mirror.
Description
The tkadmin remove mirror command removes the mapping between the logical
volume and the physical volume. If there is only one physical volume backing the
logical volume (only one copy, no mirrors) and you try to remove it with this
command, the command fails. The logical volume should be deleted using the
tkadmin delete lvol command.
Cautions
This is a dangerous operation. Removing mirrors reduces the availability of the data
stored on the logical volume.
Examples
In the following example, the pvol3 mirror of the data stored on the lvol8 logical
volume is removed:
%
tkadmin remove mirror lvol8 pvol3
Related information
tkadmin rename lvol

Purpose
Renames a logical volume.
Synopsis
tkadmin rename lvol -server server_name old_name new_name
Arguments
-server server_name
old_name
Specifies the logical volume to be renamed.
222
new_name
Specifies the new name of logical volume. The name may be any string of
alphanumeric characters with a maximum length of 128 characters including the
end-of-string character.
Description
The tkadmin rename lvol command changes the name of a logical volume. This
command can be used to rename any CICS Toolkit logical volume.
Cautions
The volume to be renamed must be disabled. (You must start the server in
administrative mode.)
Examples
The following command renames logical volume lvol1 to lvol2:
%
tkadmin rename lvol lvol1 lvol2
Related information
v tkadmin expand lvol on page 191
tkadmin rename pvol

Purpose
Renames a physical volume.
Synopsis
tkadmin rename pvol -server server_name old_name new_name
Arguments
-server server_name
old_name
Specifies the current name of the physical volume to rename.
new_name
Specifies the new name of the physical volume. The volume name can be any
string of alphanumeric characters with a maximum length of 128 characters
including the end-of-string character.
Description
The tkadmin rename pvol command renames a physical volume.
Cautions
The logical volume that this physical volume backs must be disabled. (You must
start the server in administrative mode.)
223
Examples
The following command renames physical volume pvol3 to pvol3.new:
%
tkadmin rename pvol pvol3 pvol3.new
tkadmin restore logvol

Purpose
Restores the data of a logical volume storing log data.
Synopsis
tkadmin restore logvol -server server_name log_volume_name archive_device_name
archive_file_name
Arguments
-server server_name
log_volume_name
Specifies the log volume to be restored.
archive_device_name
Specifies the archive device associated with the log volume to be restored.
archive_file_name
Specifies the latest archive file to use in the restore.
Description
The tkadmin restore logvol command restores a log volume that was damaged by
media failure using archive files associated with the log volume. The command
requires you to specify the latest archive file to be used in the restore. Typically, this
is the last complete archive file generated during normal server operation. (Online
archive files may not be destroyed in the media failure. You should attempt to save
and use the latest complete archive files available.)
Before a damaged log volume is restored, the server must be restarted in
administrative mode and the volume must be relocated onto functional physical
storage.
The servers log service component first reads the specified archive file from the
archive device. Then, a range of archive files is read in, ending with the specified
file. For example, if you specify logvol.LA.12 as the latest archive file to use in the
restore, the server reads that file and then a range of files from logvol.LA.n to
logvol.LA.12, where n is less than or equal to 12.
Messages are displayed by the server naming the required archive file, if the
required archive file is not available online. After fetching the named archive file,
you must inform the server of its accessibility via the tkadmin enable archfile
command.
Examples
Open Systems
224
The following command restores the sfs1logvol log volume using archive files in
the /var/cics_servers/archives/mysfs directory. The latest archive file used in the
restore is number 32.
% tkadmin restore logvol sfs1logvol /var/cics_servers/archives/mysfs
sfslogvol.LA.32
Windows
The following command restores the sfs1logvol log volume using archive files in
the D:\var\cics_servers\archives\mysfs directory. The latest archive file used in
the restore is number 32.
C:\> tkadmin restore logvol sfs1logvol D:\var\cics_servers\archives\mysfs
sfslogvol.LA.32
Related information
v tkadmin query logvol on page 211

Purpose
Restores the contents of one or more logical volumes.
Synopsis
tkadmin restore lvols -server server_name number_of_volumes {{logical_volume_name
[-nobackup] [-backupfilenum backup_file_number]}...} [-noresume]
Arguments
-server server_name
number_of_volumes
Specifies the number of volumes to restore.
logical_volume_name
Specifies the logical volume to restore.
[-nobackup]
Enables restoration of a volume even in the absence of any backups. Requires
all log archive files to be present, starting from file 0.
[-backupfilenum backup_file_number]
Specifies the sequence number of the most recent backup file to restore from.
Default is the number of the last complete backup of the volume.
[-noresume]
Alerts the server to restart the restore process (not to resume the interrupted
restore of volumes, the default behavior).
Description
The tkadmin restore lvols command restores a set of volumes from a backup.
Restoring several volumes at a time is more efficient than restoring each of them
separately. For each volume to restore, you specify the backup to use (via the
sequence number of the most recent file in the backup) and the volume name.
225
Since each server has a single log file, restoring multiple volumes via separate
invocations of the restore command requires reading the same log file several
times. To avoid this, the restore command accepts a list of volumes to be restored
concurrently. However, you can have only a single outstanding restore request at
any given time. You should not issue a second tkadmin restore lvols command until
the first is complete. If a second restore process (of the same or another volume) is
invoked via this command, the first is terminated. Restore processes terminated in
this manner cannot be resumed.
If the command fails to complete (either due to a server or system failure or due to
unavailable backup files), the volumes being restored are left in an indeterminate
state. The command can be reissued after the server has restarted. By default,
reissuing this command after a server restart resumes the restore process from
where it left off. To start the restore process from the beginning (prevent it from
resuming), use the -noresume option.
When multiple volumes are restored in one command, first all backup files (from
oldest to newest) are restored for each volume specified on the command line (in
the order the volumes are specified). Then the servers log file including media
archive files is replayed once (from oldest archive files to newest data in log file) to
update all volumes being restored. The backup files and archive files required to
restore a data volume can be displayed with the tkadmin query backup command.
Cautions
v The logical volumes must be disabled. (You must start the server in
administrative mode.)
v The logical volume should be unmirrored. You should remove all mirrors of the
volume before the restore, restore only one copy, and mirror the volume again
after the restore is complete.
Examples
The following command restores the logical volumes debitvol and creditvol from
backups. Assume that the 200-kilobyte volume debitvol has 6 backup files named
debitvol.TRB.000000 through debitvol.TRB.000005, 41 kilobytes each. (200
kilobytes / 6 = 40 kilobytes; the additional 1KB is necessary to hold the backup file
header information.) There are two valid backups of debitvol that can be used for a
restore, backup number 4 (consisting of files 0 through 4) and backup number 5
(consisting of files 1 through 5). Similarly, the creditvol volume has two valid
backups, backup number 2 (consisting of files 0 through 2), and backup number 3
(consisting of files 1 through 3).
The following command restores debitvol using the backup number 5 and
creditvol using backup number 3. Note that no backup file number is specified for
the restoration of the creditvol volume as the latest complete backup (3) is used by
default.
%
tkadmin restore lvols 2 debitvol -backupfilenum 5 creditvol
In cases where the backup files needed by this command are inaccessible (possibly
not online), the following message is displayed:
Restore process paused due to missing backup files.
Please ensure the following backup files are available and try again.
debitvol.TRB.000001
creditvol.TRB.000001
226
You must make the backup files accessible and reissue the tkadmin restore lvols
command. At completion, the following message is displayed:
The restore completed successfully.
Restart the server normally to begin using the restored data.
Related information
tkadmin retain backups

Purpose
Retains information about the specified number of complete, independent backups.
Synopsis
tkadmin retain backups -server server_name logical_volume_name number_of_backups
Arguments
-server server_name
logical_volume_name
Specifies the logical volume that was backed up.
number_of_backups
Specifies the number of complete, independent backups about which to retain
information.
Description
The tkadmin retain backups command retains information about a specified
number of complete, independent backups, starting with the most recent backup,
and invalidates information about older backups. This command does not actually
remove backup files; it frees recoverable storage used by the server to maintain
information about the backups. The command deletes any log archive files
associated with the invalidated backup files. Upon successful completion, this
command lists the backup files about which information was invalidated. These files
can be deleted safely by operating system commands.
Two backups are independent if they do not overlap or share any files. For
example, assume the volume testVol has several complete backups: the first
backup consists of files 0 through 4, the second backup consists of files 1 through
5, and so on. Files 0 through 4 and 5 through 9 are independent backups. If you
issue the tkadmin retain backups command and specify a value of 2 for the
argument number_of_backups, the server keeps information about the last 2
independent backups and invalidates files all older backup files, which can then be
safely deleted.
You can remove all backup information for a volume by specifying 0 (zero) as the
number_of_backups argument. Note that if you delete all backup information for a
volume, you can no longer restore the volume from a backup in the event of media
failure.
227
Examples
The following command retains information for the last two independent backups
(consisting of files 5 through 9 and 10 through 14) for volume testVol:
%
tkadmin retain backups testVol 2
Truncated backup for volume testVol

The following files are no longer needed.
numfiles: 5
0: testVol.TRB.000000
As the output indicates, backup files 0 through 4 are no longer needed and can be
deleted safely.
Related information

Purpose
Sets the ring buffers size.
Synopsis
-server server_name size
Arguments
-server server_name
size
Specifies the new size in bytes. To make best use of the available space, this
value must be a multiple of the ring buffers segment size.
Description
The tkadmin set ringbuffer size command sets the ring buffer size and displays its
current and new size, as well as its segment size, on the standard output stream.
The default ring buffer size is 65536 bytes (64 KB).
The initial number of segments in a ring buffer is fixed at eight. Each segment is
one-eighth of the total size of the ring buffer. You can increase the size of the ring
buffer (and thus the number of segments), but you cannot decrease the size below
the initial buffer size of 64 KB. The segment size is fixed at 8192 bytes. To make
the best use of the available space, the ring buffer size must be a multiple of the
segment size. Use the tkadmin show ringbuffer size command to display a ring
buffers total size and current segment size.
You can also use the CICS_TK_TRACE_RING_SIZE environment variable to
change the size of the ring buffer. If you use the environment variable, the change
does not take effect until the next time the server is started. If you use the tkadmin
set ringbuffer size command, the change takes effect immediately.
228
Examples
The following command sets the ring buffer size to 85536 bytes and displays the
current and new settings for the ring buffer. Note that the resulting ring buffer size is
90112 (8192 * 11). If you specify a size that is not a multiple of the segment size,
the next multiple of the segment size is used.
% tkadmin set ringbuffer size 85536
Present Ring Buffer Segment Size: 8192
Requested Ring Buffer Size: 85536
Resulting Ring Buffer Size: 90112
Related information
v tkadmin show ringbuffer size
v tkadmin dump ringbuffer on page 187
tkadmin show ringbuffer size

Purpose
Displays the ring buffers size.
Synopsis
tkadmin show ringbuffer size -server server_name
Arguments
-server server_name
Description
The tkadmin show ringbuffer size command displays the ring buffers total size and
its segment size. The default ring buffer size is 65536 bytes (64 KB).
Examples
The following command displays the current ring buffers total size and its segment
size on the standard output stream:
% tkadmin show ringbuffer size
Present Ring Buffer Segment Size:
8192
Related information
v tkadmin dump ringbuffer on page 187
v tkadmin set ringbuffer size on page 228

Purpose
Synchronizes a logical volume.
Synopsis
tkadmin sync mirrors -server server_name logical_volume_name
229
Arguments
-server server_name
logical_volume_name
Specifies the logical volume to be synchronized.
Description
The tkadmin sync mirrors command brings the physical volumes backing a logical
volume into synchronization by copying data from a consistent physical volume to
all appropriate available intermediate or stale physical volumes. This command is
rather expensive in terms of I/O; however, it is cheaper than the equivalent
sequence of client page I/O operations.
This command does not return until the synchronization is complete. If a server
crashes during this command, one or more of the physical volumes that were out of
date at the beginning of this command remain so. The command should be
reissued after the server recovers. This command can be issued while a volume is
enabled, that is, while I/O is being performed on the volume.
Only execute this command after a servers data volumes have been recovered
whether the server has been restarted in normal operations mode or after the
tkadmin restore lvols command has been executed following a restoration of data.
Examples
In the following example, the physical volumes backing the lvol8 logical volume (an
up-to-date copy and a new mirror) are synchronized.
%
tkadmin sync mirrors lvol8
Related information
tkadmin trace specification

Purpose
Enables or disables tracing for a component.
Synopsis
tkadmin trace specification -server server_name specification
Arguments
-server server_name
specification
Specifies tracing for a component. The basic form of this argument is
name={trace_options...}. The name is any valid component name and
{trace_options...} consists of one or more trace options that are assigned to the
trace mask of the named component. If no trace options are specified, all
230
standard tracing is enabled for the named component. Trace options can be
combined by bitwise addition or subtraction as in trace_option+trace_option or
trace_option-trace_option. This argument cannot contain any whitespace.
Description
The tkadmin trace specification command can be used to enable or disable tracing
of various events for one or more components in a server. The syntax of the
specification argument allows the use of assignment operators similar to those
defined in the C language. The name={trace_options...} form sets or replaces the
named components current trace mask with the trace options specified. Alternately,
the form name+={trace_options...} adds the trace options specified to the current
trace mask, and the form name-={trace_options...} subtracts the trace options
specified from the current trace mask. The form name1=name2={trace_options...}
assigns the same value to multiple names. Multiple assignments can be separated
by a, (comma) as in name=trace_option,name=trace_option, and are processed left
to right.
Any valid component name can be specified as the name. The following aliases
cause the trace masks for more than one component to be updated: all, sfs, and
ppc. The tkadmin list trace command can be used to obtain a list of components in
a server.
Trace options are identified by string values or their associated hexadecimal values.
The CICS Toolkit defines the following standard trace options for all components:
v trace_event (0x00000001) events in all functions
v trace_entry (0x00000002) entry/exit of all exported functions
v trace_param (0x00000004) parameters of all exported functions
v trace_export (0x00000006) entry/exit and parameters of all exported
functions
v trace_internal_entry (0x00000008) entry/exit of non-exported functions
v trace_internal_param (0x00000010) parameters of non-exported functions
v trace_global (0x0000001F) entry/exit and parameters of all functions
v trace_all, or all (0xFFFFFFFF) includes all bits in the trace mask
Tracing can be disabled for the named component by specifying a value of 0 (zero)
or none as a trace option. The default trace option causes the default tracing to be
restored for the named component. The tkadmin query trace command can be used
to look up component-specific trace options.
Examples
The following example sets the trace mask of the trpc component to trace entry
and exit of exported functions:
%
tkadmin trace specification trpc=trace_entry
The following example adds parameter tracing to the current trace mask for the
trpc component:
%
tkadmin trace specification trpc+=trace_param
The following example sets the trace masks of all components in the CICS Toolkit
Executive to trace entry, exit and parameters of exported functions using the exec
alias:
231
tkadmin trace specification exec=trace_entry+trace_param
The following examples illustrate how multiple assignments can be chained or

combined. Both examples set the trace masks of the trpc and tmxa components to
trace entry and exit of exported functions:
%
tkadmin trace specification trpc=tmxa=trace_entry
tkadmin trace specification trpc=trace_entry,tmxa=trace_entry
The following example disables tracing for all components:

%
tkadmin trace specification all=0
The following example disables event tracing only for the trpc component:
%
tkadmin trace specification trpc-=trace_event
Related information
v tkadmin list trace on page 200
v tkadmin query trace on page 214
tkadmin unmap lvol

Purpose
Unmaps a CICS Toolkit logical volume from an AIX operating system logical
volume.
Synopsis
Arguments
-server server_name
logical_volume_name
Specifies the CICS Toolkit logical volume to be deleted by unmapping it from an
AIX logical volume.
Description
The tkadmin unmap lvol command unmaps a CICS Toolkit logical volume from an
AIX logical volume. (On AIX, operating system logical volumes can be used as
alternatives to physical volumes.) The names of the logical volumes are
permanently retained by the Toolkit server. This is to facilitate the recreation of the
logical volume at a future time (via the tkadmin remap lvol command) and the
restoration of its contents from a backup. Users who want to reuse the name of a
logical volume after unmapping it can rename it.
Cautions
v The logical volume must be disabled. (You must start the server in administrative
mode.)
v If you later need the contents of an unmapped logical volume, the volume can be
remapped and restored from backup tapes.
232
Note: This command is for use on the AIX operating system only.
Examples
The following command unmaps the logical volume lvol1 from an operating system
volume serving as its backing store:
%
tkadmin unmap lvol lvol1
Related information
v tkadmin remap lvol on page 220
233
234
|
|
Appendix. Environment Variables
|
|
|
|
CICS_TK_ABORT_TIMEOUT
Specifies the maximum number of seconds that transactions can remain
inactive in an application before being aborted. The default value of this variable
is 180 seconds.
|
|
|
To set CICS_TK_ABORT_TIMEOUT in a C shell, specify the interval in seconds

(for example, 120 seconds) as follows:
|
|
|
|
CICS_TK_ADMIN_THREADS
Specifies the number of threads that CICS_TK servers make available for CICS
administrative tools (for example, the tkadmin commands and Enconsole) that
make administrative remote procedure calls (RPCs).
|
|
The default value is 1 thread. To set CICS_TK_ADMIN_THREADS in a C shell,

specify the appropriate number of threads (for example, 2) as follows:
setenv CICS_TK_ADMIN_THREADS 2
|
|
|
|
|
|
|
|
|
|
|
|
|
setenv CICS_TK_ABORT_TIMEOUT 120
CICS_TK_ALLOW_DEBUGGING
(Windows only) Specifies the conditions under which a debugging tool (such as
the CICS_TK showProcInfo utility) is started automatically. The following are
valid values for the CICS_TK_ALLOW_DEBUGGING environment variable:
1. Specifies that the default debugging tool is automatically started whenever
an unhandled exception is encountered within a CICS_TK application.
2. Specifies that the default debugging tool is automatically started whenever a
CICS_TK application is started; the debugging tool is attached to the
application process. The CICS_TK showProcInfo utility is designed to work
in this mode, and the utility can run unattended.
Note: Although you can run other debugging tools in this mode, they typically
cannot run unattended. Many debuggers require user input before
resuming the debugging process after an error is detected.
|
|
|
To set CICS_TK_ALLOW_DEBUGGING from the Windows command

prompt, specify the debugging mode you want to use (for example 1), as
follows:
C:\> set CICS_TK_ALLOW_DEBUGGING=1
|
|
|
|
|
CICS_TK_BDE_PLUMBING
Enables the Base Development Environment (BDE) plumbing, which sets the
type and frequency of plumber dumps. Plumber dumps contain information on
memory allocation (with the malloc function) and deallocation (with the free
function) for a program.
|
|
|
This environment variable has two formats. Use the first format when you want
to perform plumber dumps at a regular interval:
|
|
|
Use the second format when you want to perform plumber dumps when a
specific signal is sent:
The variables in these two formats have the following purpose:
@alloc_skip:sec_skip:dump_interval:filename.%d.%s.%d
@alloc_skip:#signal_num:filename.%d.%s.%d
235
|
|
|
|
|
|
alloc_skip
This variable indicates the number of allocations to skip after the
program is started. These allocations are not placed into the plumber
dumps. When collecting plumber dumps by interval, allocations are
placed in dumps only when both this number of allocations has been
exceeded and the sec_skip number of seconds has passed.
|
|
|
|
|
|
sec_skip
This variable indicates the number of seconds that must pass before
allocations are placed in a plumber dump. When collecting plumber
dumps by interval, allocations are placed in dumps only when both the
alloc_skip number has been exceeded and this number of seconds has
passed.
|
|
dump_interval
This variable indicates the number of seconds between plumber dumps.
|
|
signal_num
This variable indicates the signal number that causes a plumber dump.
A sprintf string comprises the following fields:
|
|
|
filename
The initial part of the file name used to hold the dump. Normally, this is
set to the program name.
|
|
%d
An integer that is automatically increments for each new dump to

distinguish between the dumps.
|
|
%s
A variable that is automatically set to the hostname of the node. It is

based on the HOST environment variable.
|
|
%d
A variable that is automatically set to the process ID of the program

being plumbed.
|
|
|
|
|
|
To set CICS_TK_BDE_PLUMBING in a C shell using the first format, specify

the appropriate settings as follows. In this example, at least the first 1000
allocations and all allocations in the first 180 seconds are skipped; plumber
dumps are made every 120 seconds thereafter into files named
myapp.#.hostname.pid.
|
|
|
CICS_TK_BDE_STACK_SIZE
Specifies the stack size, in bytes, for threads created by CICS_TK applications.
The default value varies by platform.
|
|
|
To set CICS_TK_BDE_STACK_SIZE in a C shell, specify the appropriate stack

size (for example, 65536 for 64 KB) as follows:
|
|
|
|
|
CICS_TK_DEFAULT_THREAD_POOL_QUEUE_LENGTH
Specifies the number of requests (per thread) that can be queued, waiting for
processing by a listener thread, in a servers default thread pool. If this variable
is not set, the value of the CICS_TK_THREAD_POOL_QUEUE_LENGTH
environment variable is used.
|
|
|
|
To set CICS_TK_DEFAULT_THREAD_POOL_QUEUE_LENGTH in a C shell,

specify the appropriate number of requests that can be queued (for example, 5
per listener thread) as follows:
setenv CICS_TK_BDE_PLUMBING @1000:180:120:myapp.%d.%s.%d
setenv CICS_TK_BDE_STACK_SIZE 65536
setenv CICS_TK_DEFAULT_THREAD_POOL_QUEUE_LENGTH 5
236
|
|
|
CICS_TK_PB_CLOBBER
Enables or disables detection of invalid access to memory. Set this variable to
TRUE to enable detection; set it to FALSE to disable detection.
|
|
By default, detection is enabled if the CICS_TK_BDE_PLUMBING environment

variable is set.
|
|
|
To set CICS_TK_PB_CLOBBER in a C shell, specify either TRUE or FALSE as

follows:
|
|
|
|
|
CICS_TK_PB_RINGBUF
Specifies the number of entries to maintain in the ring buffer for recent memory
allocations (with the malloc function) and deallocations (with the free function).
By default, no entries are maintained. The CICS_TK_BDE_PLUMBING
environment variable must be set to enable use of this environment variable.
|
|
|
To set CICS_TK_PB_RINGBUF in a C shell, specify the appropriate number of

entries (for example, 40) as follows:
setenv CICS_TK_PB_CLOBBER TRUE
setenv CICS_TK_PB_RINGBUF 40
|
|
|
|
|
|
|
|
CICS_TK_PB_TSTAMPS
Enables or disables inclusion of timestamps in Base Development Environment
(BDE) plumber output. Set this variable to TRUE to include timestamps; set it to
FALSE to exclude timestamps. By default, timestamps are not included. The
CICS_TK_BDE_PLUMBING environment variable must be set to enable use of
this environment variable. To set CICS_TK_PB_TSTAMPS in a C shell, specify
the appropriate value (for example, TRUE to include timestamps) as follows:
|
|
|
|
|
|
CICS_TK_PPC_ALLOCATE_TIMEOUT
Specifies how long the Peer-to-Peer Communications (PPC) Gateway or PPC
Executive process waits for an allocate request to complete the connection. The
timeout value is specified in seconds; 300 seconds is the default value. The
CICS_TK_PPC_ALLOCATE_TIMEOUT variable must be set before you start
the PPC Gateway.
|
|
|
setenv CICS_TK_PB_TSTAMPS TRUE
To set CICS_TK_PPC_ALLOCATE_TIMEOUT in a C shell, specify the

appropriate timeout value (for example, 400) as follows:
setenv CICS_TK_PPC_ALLOCATE_TIMEOUT 400
|
|
|
CICS_TK_PPC_CONNECT_RETRY_COUNT
Specifies the number of times a PPC Gateway server attempts to obtain a TCP
connection after a transient error occurs. The default value is 4.
|
|
|
To set CICS_TK_PPC_CONNECT_RETRY_COUNT in a C shell, specify the

number of connection attempts (for example, 8) as follows:
setenv CICS_TK_PPC_CONNECT_RETRY_COUNT 8
|
|
|
|
CICS_TK_PPC_CONNECT_RETRY_INTERVAL
Specifies the amount of time between a PPC Gateway servers attempts to
obtain a TCP connection after a transient error occurs. The interval is specified
in seconds; the default value is 2 seconds.
|
|
|
To set CICS_TK_PPC_CONNECT_RETRY_INTERVAL in a C shell, specify the

number of seconds between connection attempts (for example, 5) as follows:
|
|
|
CICS_TK_PPC_IP_ADDR
Directs the PPC Executive to use the specified IP address for its TCP/IP
connections. If this variable is not set, the PPC Executive uses the first address
setenv CICS_TK_PPC_CONNECT_RETRY_INTERVAL 5
237
|
|
returned by the gethostbyname function. Note that this address cannot be

derived from an alias; it must be specified explicitly.
|
|
|
To set CICS_TK_PPC_IP_ADDR in a C shell, specify the appropriate IP

address (for example, 128.6.4.7) as follows:
setenv CICS_TK_PPC_IP_ADDR 128.6.4.7
|
|
|
|
|
|
|
|
CICS_TK_FLT_CLIENT_MAX_FDS
Specifies whether a client can make Fast Local Transport (FLT) requests. If the
value is set to 0, the client is unable to make FLT requests. A nonzero value
(the default) enables FLT requests. The client can use any number of open file
descriptors up to the limit set for the operating system. To set
CICS_TK_FLT_CLIENT_MAX_FDS in a C shell, specify the appropriate value
(for example, 0 to disable FLT communication) as follows:
|
|
|
|
|
|
|
Specifies the number of seconds after a server sends a reply to a client, by way
of Fast Local Transport (FLT), that the server can disconnect the client and
reuse its resources. Smaller timeouts can reduce system performance because
of the overhead associated with reestablishing broken connections. Larger
timeouts can prevent active clients from using FLT. The default value is 300
seconds.
setenv CICS_TK_FLT_CLIENT_MAX_FDS 0
To set CICS_TK_FLT_INACTIVE_TIMEOUT in a C shell, specify the

appropriate number of seconds (for example, 360) as follows:
|
|
|
setenv CICS_TK_FLT_INACTIVE_TIMEOUT 360
|
|
|
|
CICS_TK_FLT_INITIAL_THREADS
Specifies the initial number of threads in the Fast Local Transport (FLT) thread
pool. This number must be less than or equal to the value of
CICS_TK_FLT_MAX_THREADS. The default value is 1 thread.
|
|
|
To set CICS_TK_FLT_INITIAL_THREADS in a C shell, specify the appropriate

number of threads (for example, 2) as follows:
setenv CICS_TK_FLT_INITIAL_THREADS 2
|
|
|
|
|
|
|
CICS_TK_FLT_MAX_THREADS
Specifies the maximum number of threads in the Fast Local Transport (FLT)
thread pool. If all threads are busy when a server receives an FLT request, the
server returns the request to the client with instructions to repeat the request by
way of DCE RPC. The default value is 30 threads. The value of this variable
must be greater than or equal to the value of the
CICS_TK_FLT_INITIAL_THREADS environment variable.
|
|
|
To set CICS_TK_FLT_MAX_THREADS in a C shell, specify the appropriate

number of threads (for example, 25) as follows:
|
|
|
|
|
|
CICS_TK_TPOOL_SIZE
Specifies the number of threads available in the default thread pool for a server.
The default value is 5 threads. To increase the number of threads available to a
CICS_TK application server for processing client requests, use the
CICS_TK_APPL_TPOOL_SIZE environment variable. CICS_TK++ servers use
the value specified by CICS_TK_TPOOL_SIZE only.
setenv CICS_TK_FLT_MAX_THREADS 25
To set CICS_TK_TPOOL_SIZE in a C shell, specify the appropriate number of

threads (for example, 8) as follows:
|
|
|
setenv CICS_TK_TPOOL_SIZE 8
238
|
|
|
|
|
|
CICS_TK_FLT_PIPE_DIR
Specifies the directory used to store UNIX-domain sockets or named pipes (for
pipes-based transport) used with Fast Local Transport (FLT). It is recommended
that this directory not be on a network file system. The server using FLT must
have permission to create and remove files in the directory, and clients using
FLT must have lookup permission in the directory. The default directory is /tmp.
|
|
|
To set CICS_TK_FLT_PIPE_DIR in a C shell, specify the full path name for the
appropriate directory (for example, /tmp/sockets) as follows:
|
|
|
|
|
|
|
CICS_TK_SERVER
Specifies the DCE path name (either fully qualified or relative) of a Toolkit
server. If CICS_TK_CDS_ROOT is set, this variable can be a relative path
name; in this case, the value of CICS_TK_CDS_ROOT is prepended to the
value specified by this variable. When a tkadmin command is executed, this
variable identifies the Toolkit server to use when the commands -server option
is not specified.
|
|
|
To set CICS_TK_SERVER in a C shell, specify the DCE path name for the
appropriate Toolkit server (for example, /.:/branch1/server/tk1) as follows:
|
|
|
|
|
|
|
CICS_TK_SFS_SERVER
Specifies the DCE path name (either fully qualified or relative) of a Structured
File Server (SFS) server. If CICS_TK_CDS_ROOT is set, this variable can be a
relative path name; in this case, the value of CICS_TK_CDS_ROOT is
prepended to the value specified by this variable. When executing an sfsadmin
command, this variable identifies the SFS server to use when the commands
-server option is not specified.
|
|
|
To set CICS_TK_SFS_SERVER in a C shell, specify the DCE path name for

the appropriate SFS server (for example, /.:/branch1/server/sfs1) as follows:
|
|
|
|
|
|
CICS_TK_FLT_SERVER_MAX_FDS
Specifies the maximum number of UNIX file descriptors that the server can use
to connect to Fast Local Transport (FLT) clients concurrently. Setting this
variable to 0 disables FLT connections. The default is 20 less than the file
descriptor limit set when the operating system is configured. To disable FLT
connections, set this variable to 0.
setenv CICS_TK_FLT_PIPE_DIR /tmp/sockets
setenv CICS_TK_SERVER /.:/branch1/server/tk1
setenv CICS_TK_SFS_SERVER /.:/branch1/server/sfs1
|
|
|
|
|
|
|
|
|
|
|
Note: We recommend that the limit on file descriptors be set to 128 for all
UNIX platforms. The limit on file descriptors is determined by the UNIX
system administrator when a machine is configured; the limit and the
method of setting this limit vary by platform. For example, on Solaris
systems, the file descriptor limit is 64 by default (at most 44 file
descriptors are available for FLT requests; the descriptors unused by FLT
are available for other operations, such as communications and file I/O).
Because file descriptors are a limited resource, you can set
CICS_TK_FLT_SERVER_MAX_FDS to a smaller value if you expect the
server to handle many operations that require file descriptors (such as
accepting many DCE connections via the TCP/IP protocol).
|
|
|
To set CICS_TK_FLT_SERVER_MAX_FDS in a C shell, specify the

appropriate number of connections (for example, 10) as follows:
setenv CICS_TK_FLT_SERVER_MAX_FDS 10
239
CICS_TK_RPC_THREAD_STACK_SIZE
Specifies, using the DCE rpc_mgmt_set_server_stack_size function, the
manager function stack size, in bytes, for RPC threads. The default value varies
by platform.
|
|
|
|
To set CICS_TK_RPC_THREAD_STACK_SIZE in a C shell, specify the

appropriate stack size (for example, 262144 for 256 KB) as follows:
|
|
|
setenv CICS_TK_RPC_THREAD_STACK_SIZE 262144
CICS_TK_TRACE
Specifies a trace specification that defines the type of tracing to be performed.
Prior to starting a process for which you want to gather trace data, you must set
this environment variable if you are not using some other way of enabling
tracing.
|
|
|
|
|
|
|
|
|
|
|
Note: Setting or modifying the trace specification at the command line, by

using Enconsole, enccp, or emadmin overrides the value of the
CICS_TK_TRACE environment variable. (For information on other
methods of enabling tracing, see CICS_TK Administration Guide Volume
1: Basic Administration.)The trace specification is made up of one or
more basic statements with the following syntax: name=value.
|
|
|
The name is the name of the CICS_TK components for which trace output can
be generated. To get a list of valid component names, issue the tkadmin list
trace command.
|
|
|
The value is an expression that can contain numeric constants or one of the
following string values as shown in the Table 14. (Each string value sets one or
more bits in a trace mask.)
Table 14. String values and their expressions
String value
Expression
trace_event
Trace all events
trace_entry
Trace external function entry or exit
trace_param
Trace external function parameters
trace_internal_entry
Trace internal function entry or exit
trace_internal_param
Trace internal function parameters
|
|
|
|
trace_global
Trace all of the following: trace_event,

trace_entry, trace_param,
trace_internal_entry, and
trace_internal_param
|
|
trace_export
Trace external function entry or exit and

function parameters
trace_dump
Dump the component on a fatal error
trace_dump_selected
Dump the component on a fatal error
trace_all
Trace all except trace_dump
|
|
all
Trace all except trace_dump
|
|
|
|
|
CICS_TK_TRACE_BUFFER_DUMP_ON_EXIT
Triggers an automatic ring buffer dump when a process exits. State dumps for
selected components are produced prior to dumping the ring buffer. To trigger
dumps on exit, set this value to a nonzero integer. (See the description of the
value of trace_dump under the definition of the CICS_TK_TRACE variable.)
240
|
|
|
|
|
|
|
|
|
|
To set CICS_TK_TRACE_BUFFER_DUMP_ON_EXIT in a C shell, specify the

appropriate zero or nonzero numeric value (for example, 1 to trigger an
automatic dump when a process exists) as follows:
setenv CICS_TK_TRACE_BUFFER_DUMP_ON_EXIT 1
CICS_TK_TRACE_BUFFER_DUMP_ON_SIGNAL
Specifies the numeric value of a signal that, when received by an CICS_TK
server, triggers an automatic ring buffer dump.
To set CICS_TK_TRACE_BUFFER_DUMP_ON_SIGNAL in a C shell, specify
the appropriate signal number (for example, 31) as follows:
setenv CICS_TK_TRACE_BUFFER_DUMP_ON_SIGNAL 31
|
|
|
|
CICS_TK_TRACE_BUFFER_DUMP_ON_UIDS
Specifies one or more trace IDs that, when encountered, cause an automatic
dump of the ring buffer. If more than one trace ID is specified, the IDs must be
separated by a , (comma).
|
|
|
|
To set CICS_TK_TRACE_BUFFER_DUMP_ON_UIDS in a C shell, specify the

appropriate trace IDs (for example, 280c1825, 280c1835, and 280c1845) as
follows:
|
|
|
|
|
CICS_TK_TRACE_BUFFER_DUMP_WHEN_FULL
Specifies that the contents of the ring buffer are dumped into a binary trace file
before the buffer wraps and begins to reuse segments. By default,
CICS_TK_TRACE_BUFFER_DUMP_WHEN_FULL is not set, and the trace
information contained in the ring buffer is not dumped into a trace file.
|
|
|
|
|
|
|
|
|
|
|
|
setenv CICS_TK_TRACE_BUFFER_DUMP_ON_UIDS 280c1825,280c1835,280c1845
Set CICS_TK_TRACE_BUFFER_DUMP_WHEN_FULL in a C shell as follows:

setenv CICS_TK_TRACE_BUFFER_DUMP_WHEN_FULL
CICS_TK_TRACE_FILE_FORMAT
Specifies a naming convention for the files in which a ring buffer is dumped. By
default, files are named CICS_TKTraceBuffer.%d (where %d is the ID of the
process that caused the dump). This environment variable takes the format of a
sprintf string that contains %d, where %d defines the position of the process ID
within the file name:
setenv CICS_TK_TRACE_FILE_FORMAT MyTraceBuffer.%d
To set CICS_TK_TRACE_FILE_FORMAT in a C shell, specify the appropriate

format (for example, MyApp.%d) as follows:
setenv CICS_TK_TRACE_FILE_FORMAT MyApp.%d
|
|
|
|
CICS_TK_TRACE_RING_SIZE
Specifies the size of the ring buffer, in bytes. To make best use of the available
space, this value must be a power of 2 (for example, 1024 for 1 KB). If this
variable is not set, it defaults to 65536 (64 KB).
|
|
|
To set CICS_TK_TRACE_RING_SIZE in a C shell, specify the appropriate ring

buffer size (for example, 524288 to set the size to 512 KB) as follows:
|
|
|
|
You can also set the ring buffer size by using the tkadmin set ringbuffersize
command. If you use this command, the new ring buffer size takes effect
immediately. If you use the CICS_TK_TRACE_RING_SIZE environment
variable, the change takes effect the next time the server is started.
|
|
setenv CICS_TK_TRACE_RING_SIZE 524288
CICS_TK_TRACE_VERBOSE
Redirects trace output to either the standard error stream (stderr) or the
241
|
|
|
|
standard output stream (stdout). To redirect output to stderr, set this variable to
1; to redirect output to stdout, set this variable to 2. Redirecting output to stderr
is generally preferable to redirecting it to stdout because the former is an
unbuffered stream.
|
|
|
To set CICS_TK_TRACE_VERBOSE in a C shell, specify the appropriate

direction for trace output (for example, 1 to direct it to stderr) as follows:
setenv CICS_TK_TRACE_VERBOSE 1
CICS_TK_TRACE_REDIRECT
Specifies a destination for messages of specific trace classes after the
messages are captured in the ring buffer. You can override this variable by
using the tkadmin redirect trace command.
|
|
|
|
|
|
This environment variable takes the following format:
|
|
The trace_class can take any of the following values, as shown in the Table 15
to indicate the events to be traced.
trace_class[=trace_class...][[[buffering][,formatting]]]=destination
Table 15. Trace class and events
Values
Events to be traced
audit
Trace administratively significant events
critical
Trace a combination of audit, error, and fatal
dump
Trace state dumps
entry
Trace function entry and exit
error
Trace nonfatal errors (warnings)
event
Trace events
fatal
Trace fatal errors
param
Trace parameters
serious
Same as critical
|
|
|
trace
Trace a combination of entry, event, and

param
|
|
|
CICS_TK_TRAN_TUNING
The CICS_TK_TRAN_TUNING environment variable sets TRAN tuning
parameters.
|
|
Note: Do not set this environment variable unless directed to do so by your

customer support organization.
|
|
|
|
|
CICS_TK_TRPC_TRANSMIT_TIMEOUT
Limits the time TRPC spends trying to send an out-of-band TRAN message to a
participant. The value of CICS_TK_TRPC_TRANSMIT_TIMEOUT is specified in
microseconds; it is typically greater than the timeout value of the protocol used
for the RPC.
The default value is 60,000,000 microseconds (60 seconds).
|
|
Note: Set the CICS_TK_TRPC_TRANSMIT_TIMEOUT environment variable

only when directed to do so by your customer support organization.
CICS_TK_TRPC_CLEANUP_INTERVAL
Specifies how often the TRPC cache is cleaned up. The cleanup process
|
|
242
|
|
|
deletes handles that have been idle for too long or that have been marked as
invalid. The value of this variable is specified in microseconds; the default value
is 30,000,000 (30 seconds).
|
|
|
To set CICS_TK_TRPC_CLEANUP_INTERVAL in a C shell, specify the

appropriate interval (for example, 60000000) as follows:
|
|
|
|
|
CICS_TK_TRPC_BINDING_TIMEOUT
Specifies the CICS_TK clients communications timeout value for the TRPC
binding handle used to deliver out-of-band TRAN messages. Setting this
environment variable causes the rpc_mgmt_set_com_timeout function to be
called.
setenv CICS_TK_TRPC_CLEANUP_INTERVAL 60000000
The timeout indicates the relative amount of time that CICS_TK clients use
when attempting to communicate with an CICS_TK server. The value of the
variable can be any number between 0 and 10 (the default value is 3). The
number does not represent seconds; rather, it represents a relative amount of
time to spend to establish a binding, as follows:
|
|
|
|
|
|
Table 16. Values of the timeout variables
|
|
Value of the
timeout variable
|
|
|
|
The client attempts to communicate with the server for the minimum
amount of time for the network protocol in use. This value favors
response time over correctness in determining whether the server is
running.
|
|
|
|
The client attempts to communicate with the server for an average

amount of time for the network protocol in use. This value gives equal
consideration to response time and correctness in determining whether
the server is running.
|
|
|
|
The client attempts to communicate with the server for the longest
finite amount of time for the network protocol in use. This value favors
correctness in determining whether the server is running over
response time.
|
|
|
|
|
10
The client attempts to communicate with the server forever. To set

CICS_TK_TRPC_BINDING_TIMEOUT in a C shell, specify the
appropriate value (for example, 5) as follows:
|
|
|
|
CICS_TK_TRPC_CLEANUP_MAX_IDLE_COUNT
Specifies how many iterations of the cleanup process can occur before an idle
TRPC handle (used for out-of-band TRAN messages) is deleted from the
cache. The default value is 20.
|
|
|
Action
setenv CICS_TK_TRPC_BINDING_TIMEOUT 5
To set CICS_TK_TRPC_CLEANUP_MAX_IDLE_COUNT in a C shell, specify

the appropriate number of cleanup processes (for example, 15) as follows:
setenv CICS_TK_TRPC_CLEANUP_MAX_IDLE_COUNT 15
|
|
|
|
CICS_TK_TRPC_THREADS
Specifies the number of threads used for out-of-band RPCs. Out-of-band RPCs
are auxiliary messages sent by the Transaction Service to carry information
about TRPCs. The default value is 1 thread.
|
|
|
To set CICS_TK_TRPC_THREADS in a C shell, specify the appropriate number

of threads (for example, 2) as follows:
setenv CICS_TK_TRPC_THREADS 2
243
|
|
|
|
|
|
|
CICS_TK_EXTFH_AUTO_FLUSH
Controls the setting of the operational force flag that the Structured File Server
(SFS) uses when opening an SFS file by way of the COBOL External File
Handler (EXTFH). Operational force applies only when accessing an SFS file
nontransactionally. If operational force is enabled, changes to SFS data must be
committed to disk before the operation can complete. If operational force is
disabled, changes to SFS data are written to disk when necessary (lazily).
|
|
|
|
|
|
Setting the variable to 0 disables operational force; any other value enables
operational force. If this variable is not set, it defaults to 0. To set
CICS_TK_EXTFH_AUTO_FLUSH in a C shell, specify the appropriate value for
the use of operational force (for example, 1 to enable operational force) as
follows:
|
|
|
|
|
|
|
CICS_TK_EXTFH_CACHE
Specifies the size of the read and insert cache, in pages (a page is 4 KB), used
by the Structured File Server (SFS) by way of the COBOL External File Handler
(EXTFH). If this variable is not set, caching is disabled. Use one of the following
formats to set the value of this environment variable:
setenv CICS_TK_EXTFH_AUTO_FLUSH 1
read_and_insert_cache_size[:flag[,flag...]]
read_cache_size:insert_cache_size[:flag[,flag...]]
The parameters are defined as follows:
|
|
|
read_and_insert_cache_size
Specifies the size of both the read and insert caches in pages. Setting this
value to 0 (zero) disables read and insert caching.
|
|
|
read_cache_size
Specifies the size of the read cache in pages. Setting this value to 0 (zero)
disables read caching.
|
|
|
insert_cache_size
Specifies the size of the insert cache in pages. Setting this value to 0 (zero)
disables insert caching.
|
|
|
|
|
|
flag
|
|
|
|
To set CICS_TK_EXTFH_CACHE in a C shell, specify the appropriate cache

sizes (for example, 0 to disable the read cache, and 64 pages for the insert
cache) followed by any flags (for example, ALLOW_DIRTY_READS) as follows:
|
|
|
|
|
|
|
|
|
|
CICS_TK_EXTFH_DUP_DETECTION
Specifies whether duplicate detection is enabled for Structured File Server
(SFS) operations initiated by way of the COBOL External File Handler (EXTFH).
Setting the variable to NONE disables duplicate detection; setting the variable
to ALL enables duplicate detection. If this variable is not set, it defaults to ALL
unless caching is enabled (see the CICS_TK_EXTFH_CACHE variable), in
which case the default is NONE. To set CICS_TK_EXTFH_DUP_DETECTION
in a C shell, specify the appropriate value for duplicate detection in a file (for
example, NONE) as follows:
Specifies one or more caching restrictions to be relaxed. For a listing of

these flags, see the reference page for the sfs_InitializeCache function.
When specifying a flag, omit the SFS_CACHE_ prefix. For example, to
specify the SFS_CACHE_ALLOW_DIRTY_READS flag, use
ALLOW_DIRTY_READS.
setenv CICS_TK_EXTFH_CACHE 0:64:ALLOW_DIRTY_READS
setenv CICS_TK_EXTFH_DUP_DETECTION NONE
244
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CICS_TK_EXTFH_OP_TIMEOUT
Specifies the timeout, in seconds, for Structured File Server (SFS) operations
initiated by way of the COBOL External File Handler (EXTFH). The operation
timeout specifies how long an application is willing to wait for an SFS operation
to complete. If this variable is not set, it defaults to 60 seconds.
To set CICS_TK_EXTFH_OP_TIMEOUT in a C shell, specify the appropriate
number of seconds for operation timeouts (for example, 120) as follows:
setenv CICS_TK_EXTFH_OP_TIMEOUT 120
CICS_TK_EXTFH_OPEN_TIMEOUT
Specifies the timeout, in seconds, for Structured File Server (SFS) open file
operations initiated by way of the COBOL External File Handler (EXTFH). The
open timeout specifies how long an application is willing to wait for an SFS
open file operation to complete. If this variable is not set, it defaults to 60
seconds.
|
|
|
To set CICS_TK_EXTFH_OPEN_TIMEOUT in a C shell, specify the appropriate

number of seconds for open timeouts (for example, 120) as follows:
|
|
|
|
|
|
CICS_TK_EXTFH_SFS
Specifies the DCE path name (either fully qualified or relative) of a Structured
File Server (SFS) server used by the COBOL External File Handler (EXTFH). If
CICS_TK_CDS_ROOT is set, this variable can be a relative path name; in this
case, the value of CICS_TK_CDS_ROOT is prepended to the value specified
by this variable.
|
|
|
|
To set CICS_TK_EXTFH_SFS in a C shell, specify the fully qualified or relative

DCE path name for the appropriate SFS server (for example,
/.:/branch1/server/sfs2) as follows:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
setenv CICS_TK_EXTFH_OPEN_TIMEOUT 120
setenv CICS_TK_EXTFH_SFS /.:/branch1/server/sfs2
CICS_TK_EXTFH_SLOT_CHOICE
Controls where record inserts occur in Structured File Server (SFS) relative files
when using the COBOL External File Handler (EXTFH). Setting the variable to
FIRST specifies that insertions occur in the first open slot; setting the variable to
LAST indicates that insertions occur after the last record. If this variable is not
set, it defaults to LAST.
To set CICS_TK_EXTFH_SLOT_CHOICE in a C shell, specify the appropriate
value for the location of record inserts in relative files (for example, FIRST) as
follows:
setenv CICS_TK_EXTFH_SLOT_CHOICE FIRST
CICS_TK_EXTFH_VOL
Specifies the name of the Structured File Server (SFS) data volume used by
the COBOL External File Handler (EXTFH).
To set CICS_TK_EXTFH_VOL in a C shell, specify the name of the appropriate
SFS logical volume (for example, sfsVol1) as follows:
setenv CICS_TK_EXTFH_VOL sfsVol1
245
246
Notices
This information was developed for products and services offered in the U.S.A. IBM
may not offer the products, services, or features discussed in this document in other
countries. Consult your local IBM representative for information on the products and
services currently available in your area. Any reference to an IBM product, program,
or service is not intended to state or imply that only that IBM product, program, or
service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However,
it is the users responsibility to evaluate and verify the operation of any non-IBM
product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
DOCUMENT AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OR CONDITIONS OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express
or implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the document. IBM may make improvements and/or
changes in the product(s) and/or the program(s) described in this publication at any
time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those
Web sites. The materials at those Web sites are not part of the materials for this
IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs
247
and other programs (including this one) and (ii) the mutual use of the information
which has been exchanged, should contact:
IBM Corporation
ATTN: Software Licensing
11 Stanwix Street
Pittsburgh, PA 15222
U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available
for it are provided by IBM under terms of the IBM International Program License
Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those
products, their published announcements or other publicly available sources. IBM
has not tested those products and cannot confirm the accuracy of performance,
compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those
products.
All statements regarding IBMs future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples may include
the names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
If you are viewing this information softcopy, the photographs and color illustrations
may not appear.
Trademarks and service marks

The following terms are trademarks or registered trademarks of the IBM Corporation
in the United States, other countries, or both:
Advanced Peer-to-Peer Networking
AS/400
CICS/400
248
AIX
CICS
CICS/6000
CICS/ESA
CICS/MVS
CICS/VSE
CICSPlex
C-ISAM
Database 2
DB2
DB2 Universal Database
GDDM
IBM Registry
IBM
IMS
Informix
Language Environment
MVS
MVS/ESA
OS/390
OS/2
OS/400
RACF
RETAIN
RISC System/6000
RS/6000
SOM
Systems Application Architecture
System/390
TXSeries
TCS
VisualAge
VSE/ESA
VTAM
WebSphere
z/OS
Domino, Lotus, and LotusScript are trademarks or registered trademarks of Lotus

Development Corporation in the United States, other countries, or both.
ActiveX, Microsoft, Visual Basic, Visual C++, Visual J++, Visual Studio, Windows,
Windows NT, and the Windows 95 logo are trademarks or registered trademarks
of Microsoft Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Acucorp and ACUCOBOL-GT are registered trademarks of Acucorp, Inc. in the
United States, other countries, or both.
Pentium is a trademark of Intel Corporation in the United States, other countries,
or both.
This software contains RSA encryption code.
Other company, product, and service names may be trademarks or service marks
of others.
Notices
249
250
Index
A
CICS_TK_SFS_SERVER environment variable 4

CICS_TK_TRACE_REDIRECT environment
variable 50
closing
files in SFS 76, 156
OFDs 76, 156
clustered files
creating 65
components
disabling trace for servers 230
displaying for servers 48
displaying trace masks for servers 200, 214
enabling trace for servers 230
conversations
deleting 105, 116
displaying 97, 98, 119, 126
copying
creating
backups 24
clustered files 65
entry-sequenced files 63
files in SFS 59
logical volumes 181
physical volumes 182
relative files 64
volumes 9
aborting
transactions 21, 178
adding
mirrors 179
administrative mode 13
restarting servers 13
tasks 13
using server startup commands 13
AIX logical volumes
mapping 204
moving 39
remapping 39, 220
renaming 15
unmapping 18, 232
allocating
disk space for secondary indices 175
disk space for SFS files 139
archive files
enabling 188
B
backing up
data volumes 25
log volumes 24
logical volumes 180
server restart files 28
volumes 24
backups
creating 24
deleting 31
displaying information 207
log archive files 23
log files 23
moving offline 28
querying 29
retaining information 227
buffer pools
specifying sizes 91
C
canceling
resynchronizations 106, 113
changing ring buffer size
trace 53, 228
changing size
ring buffers 53, 228
checkpoints
setting intervals for SFS servers 92
chunk 8
chunks
size recommendations 91
CICS Toolkit Trace Facility 45
CICS_PPC_GWY_SERVER environment variable
CICS_TK_SERVER environment variable 4
damage
reporting during resynchronizations 110
data restores
performing 35
data volumes
backing up 25
deleting
backups 31
conversations 105, 116
disks 183
files in SFS 77
logical volumes 184
destroying
files in SFS 77
determining
log exchange status 108
diagnosing
media failures 33
disabling
logical volumes 186
media archiving 187
trace for server components 230
disk 8
disk space
allocating for files in SFS 139
allocating for secondary indices 175
251
disk space (continued)

reclaiming 17
reclaiming (AIX) 18
disks
deleting 183
displaying 197
ensuring functionality 36
files used as disks 9
initializing 196
units of allocation (figure) 7
displaying
backup information 207
components for servers 48
conversations 97, 98, 119, 126
disk information 210
disks 197
file information in SFS 69
file locks in SFS 74, 164
files in SFS 68
instances of resource managers 200
log identifier name exchange status 109, 125, 135
log volumes 211
logical volume information 211
logical volume information in SFS 89
logical volumes 198
LU resynchronizations 133
LUW information 131
LUWs 100, 103, 121, 122
media archiving 24, 212
OFD information 72
OFDs 70, 151, 154
physical volume information 213
PPC gateway server transactions 124
products for servers 48
resynchronizations 103, 104
ringbuffer size 53, 229
SFS server information 90
SFS servers 157
trace masks for server components 200, 214
trace output destinations 51, 199, 214
trace specifications 48, 49
transaction information 21, 73, 215
transaction lock information in SFS 166
dumping
ring buffers 52, 187
E
emptying
files in SFS 76
enabling
archive files 188
log files 189
logical volumes 190
trace for server components
entry-sequenced files
creating 63
252
230
entry-sequenced files (continued)

reorganizing 68, 140
updating (figure) 63
environment variables 235
CICS_PPC_GWY_SERVER 4
CICS_TK_SERVER 4
CICS_TK_SFS_SERVER 4
error codes 56
translating 56
evaluating
unresolved transactions 22
exchanging
log identifier names 118
expanding
files in SFS 67, 68, 139
logical volumes 191
secondary indices 175
F
fast local transport (FLT) 92
fields (SFS)
types (table) 62
file locks
displaying in SFS 164
files
backup 23
log archive 23
using as disks 9
using as volumes (figure) 10
files (SFS)
closing 76, 156
copying 66, 138
creating 59
creating clustered 65
creating entry-sequenced 63
creating relative 64
deleting 77
displaying 68
displaying locks 74, 164
emptying 76
expanding 67, 68, 139
managing 59
renaming 67, 140
reorganizing entry-sequenced 68, 140
specifying field sizes in records 62
specifying field types in records 62
types (table) 61
FLT (fast local transport) 92
flushing
logical volumes 194
media archive 194
media archives 25
forcing
exchange of log identifier names 110, 118
transaction outcomes 21, 195
formatting
trace output 56
G
generating
log archive files
24
I
indentTrace command 56
initializing
disks 196
interpretTrace command 54, 56
L
listing
components for servers 48
disks 197
files in SFS 68
instances of resource managers 200
log identifier name exchange status 109, 125
logical volumes 89, 198
LUWs 100, 103, 121, 122
OFDs 70, 151
PPC gateway server transactions 124
products for servers 48
resynchronizations 103
trace masks for server components 200
trace options 49
trace output destinations 51, 199
locks (SFS)
querying 74
log archive files 23
cached data 25
generating 24
log exchanges
determining status 108
log files 23
enabling 189
log identifier names
displaying exchange status 109, 125, 135
forcing exchanges 110, 118
log volumes
backing up 24
displaying 211
querying 31
restoring 224
logArchive directory 24
logical volumes 7
backing up 180
creating 181
deleting 184
disabling 186
displaying 89, 198
displaying information in SFS 89
enabling 190
expanding 191
logical volumes (continued)

flushing 194
flushing media archive 194
mapping AIX 204
recovering 216
recreating 37, 217
remapping AIX 220
renaming 14, 222
repairing 14
restoring 225
unmapping AIX 232
LUs
displaying log identifier name exchange status
135
displaying resynchronizations 133
LUWs
displaying 100, 103, 121, 122
identifiers 99
125,
M
managing
files in SFS 59
manipulating
trace output 51
mapping
AIX logical volumes 204
media archives
flushing 25
media archiving
disabling 187
displaying 24, 212
enabling 24, 191
media failures
diagnosing 33
protecting against 23
recovering 33
mirrors
adding 179
removing 221
repairing 39
repairing (AIX) 40
synchronizing 229
modifying
trace output destinations 51
trace specifications 51
moving
backups offline 28
physical volumes 16, 36, 205
O
OFDs
closing 76, 156
displaying 70, 151, 154
Index
253
P
pages 9
physical volumes 7
creating 182
deleting 185
displaying 199
expanding 192
moving 16, 36, 205
renaming 15, 223
PPC gateway servers
displaying transactions 124
ppcadmin cancel resync command 106, 108, 113
ppcadmin commands 113
ppcadmin destroy conv command 105, 116
ppcadmin force xln command 110, 118
ppcadmin list convs command 97, 119
ppcadmin list luws command 100, 121
ppcadmin list resyncs command 103, 122
ppcadmin list transactions command 99, 124
ppcadmin list xlns command 109, 125
ppcadmin query conv command 98, 126
ppcadmin query luw command 100, 131
ppcadmin query resync command 104, 107, 133
ppcadmin query xln command 109, 135
products
displaying for servers 48
Q
querying
backups 29
disk information 210
file locks in SFS 74, 164
files in SFS 69
log identifier name exchange status 109, 135
log volumes 31, 211
logical volume information 211
LU resynchronizations 133
LUW information 131
LUWs 100
OFDs 72, 154
physical volume information 213
SFS server information 90
SFS servers 157
trace masks for server components 214
trace output destinations 214
transaction information 73, 215
transaction lock information in SFS 166
R
reclaiming
disk space 17
disk space (AIX)
254
18
recommendations
chunk size 91
records
specifying field sizes in SFS files 62
specifying field types in SFS files 62
updating (figure) 63
recovering
from abnormal server termination 33
from media failures 33
logical volumes 216
recreating
redirecting
trace output 51, 218
region 8
relative files
creating 64
remapping
AIX logical volumes 39, 220
removing
mirrors 221
renaming
physical volumes 15, 223
secondary indices 174
reorganizing
entry-sequenced files 68, 140
repairing
mirrors 39
mirrors (AIX) 40
repairing logical volumes 14
reporting
damage during resynchronizations 110
resolving
transactions 21
resource managers
listing instances of 200
restart files 28
backing up 28
viewing 34
restoring
data 35
data volumes 40
log volumes 42, 224
logical volumes 225
canceling 106, 113
displaying 104
listing 103
reporting damage 110
retaining
ring buffer size
changing 53, 228
setting 53, 228
ring buffers 51
displaying size 53, 229
dumping 52, 187
S
secondary indices
allocating disk space 175
expanding 175
renaming 174
server restart files 28
backing up 28
servers
displaying components 48
displaying products 48
recovering from abnormal termination 33
setting checkpoint interval in SFS 92
setting environment variables 4
specifying chunk size in SFS 91
setting
checkpoint interval for SFS servers 92
environment variables for servers 4
SFS servers
displaying 157
specifying buffer pool sizes 91
sfsadmin acquire lvol command 160
sfsadmin add index command 168
sfsadmin add lvol command 163
sfsadmin commands 137
sfsadmin copy file command 66, 138
sfsadmin create clusteredfile command 141
sfsadmin create relativefile command 143
sfsadmin create sequentialfile command 145
sfsadmin deactivate index command 171
sfsadmin delete index command 170
sfsadmin destroy file command 77, 147
sfsadmin empty file command 76, 148
sfsadmin enable server command 158
sfsadmin expand file command 67, 68, 139
sfsadmin expand index command 175
sfsadmin export file command 149
sfsadmin import file command 149
sfsadmin list file command 146
sfsadmin list files command 68
sfsadmin list lvols command 158
sfsadmin list ofds command 70, 73, 151
sfsadmin query export command 157
sfsadmin query file command 69, 149
sfsadmin query filelock command 74, 164
sfsadmin query index command 173
sfsadmin query lvol command 89
sfsadmin query lvols command 159
sfsadmin query ofd command 72, 154
sfsadmin query server command 90, 157
sfsadmin query tranlock command 73, 166
sfsadmin rebuild index command 172
sfsadmin release lvols command 162
sfsadmin rename file command 67, 140
sfsadmin rename index command 174
sfsadmin reorganize file command 68, 140
sfsadmin terminate ofd command 76, 156
shared-memory-based transport 94
specifying
chunk size in SFS 91
record field sizes in SFS files 62
specifying (continued)
record field types in SFS files
thread pool sizes in SFS 92
status codes
translating 56
synchronizing
mirrors 229
syntax conventions 3
62
T
thread pool sizes
specifying in SFS 92
tkadmin abort transaction command 108, 178
tkadmin add mirror command 179
tkadmin backup lvol command 26, 180
tkadmin commands 177
tkadmin create lvol command 181
tkadmin create pvol command 38, 182
tkadmin delete disk command 18, 183
tkadmin delete lvol command 18, 38, 184
tkadmin delete pvol command 18, 185
tkadmin disable lvol command 186
tkadmin disable mediaarchiving command 187
tkadmin dump ringbuffer command 52, 187
tkadmin enable archfile command 43, 188
tkadmin enable logfile command 43, 189
tkadmin enable lvol command 190
tkadmin enable mediaarchiving command 25, 191
tkadmin expand lvol command 191
tkadmin expand pvol command 192
tkadmin flush lvol command 194
tkadmin flush mediaarchive command 194
tkadmin force transaction command 108, 195
tkadmin init disk command 16, 37, 38, 196
tkadmin list disks command 197
tkadmin list lvols command 89, 198
tkadmin list pvols command 199
tkadmin list redirect command 51, 199
tkadmin list rmi command 200
tkadmin list trace command 48, 200
tkadmin list transactions command 108, 202
tkadmin map lvol command 204
tkadmin move pvol command 37, 205
tkadmin query backup command 29, 207
tkadmin query disk command 210
tkadmin query logvol command 32, 211
tkadmin query lvol command 211
tkadmin query mediaarchiving command 25, 212
tkadmin query pvol command 213
tkadmin query redirect command 214
tkadmin query trace command 49, 214
tkadmin query transaction command 215
tkadmin recover lvols command 42, 216
tkadmin recreate lvol command 38, 217
tkadmin redirect trace command 218
tkadmin remap lvol command 15, 39, 220
tkadmin remove mirror command 17, 41, 221
tkadmin remove pvol command 17
tkadmin rename lvol command 14, 222
tkadmin rename pvol command 15, 223
Index
255
tkadmin restore logvol command 42, 224

tkadmin restore lvols command 42, 225
tkadmin retain backups command 227
tkadmin set ringbuffer size command 53, 228
tkadmin show ringbuffer size command 53, 229
tkadmin sync mirrors command 40, 229
tkadmin trace specification command 230
tkadmin unmap lvol command 15, 18, 39, 232
ToolkitTraceBuffer.pid files 51
translating 54
trace
controlling the amount of output 46
disabling for server components 230
displaying output destinations 51, 199, 214
displaying ring buffer size 53, 229
displaying specifications 48, 49
dumping ring buffers 52, 187
enabling for server components 230
formatting output 56
listing options 49
manipulating output 51
modifying output destinations 51
modifying specifications 51
opening files with WinTrace 56
output format 55
redirecting output 51, 218
Standard Trace Options (table) 46
syntax of destinations 49, 51
syntax of specifications 47
types of destinations 50
types of output 45
trace masks 46
displaying for server components 200, 214
transaction locks
displaying information in SFS 166
transactions
aborting 21, 178
displaying 99, 202
displaying information 21, 73, 215
forcing outcomes 22, 195
global TIDs 99
resolving 21
translating
error codes 56
status codes 56
ToolkitTraceBuffer.pid files 54
volumes (continued)
backing up logical 180
creating 9
creating logical 181
creating physical 182
definition 7
deleting logical 184
deleting physical 185
disabling logical 186
displaying information for logical 211
displaying information for logical in SFS 89
displaying information for physical 213
displaying logical 198
displaying physical 199
enabling logical 190
expanding logical 191
expanding physical 192
flushing logical 194
flushing media archive 194
listing logical 89
logical 7
mapping AIX logical 204
moving physical 205
physical 7
physical and logical (figure) 9
recovering logical 216
recreating logical 217
remapping AIX logical 220
renaming logical 222
renaming physical 223
restoring 40, 42
restoring log 224
restoring logical 225
specifying chunk size in SFS 91
unmapping AIX logical 232
W
WinTrace
error codes 57
formatting trace output 57
opening trace files 56
U
UNIX pipe-based transport 93
unmapping
AIX logical volumes 18, 232
updating
entry-sequenced files (figure) 63
records (figure) 63
V
Volume Service 7
volumes
backing up 24
256
SC34-6627-02

Spine information:
SFS Server and PPC Gateway Server: Advanced

Administration
Version 6.2
SC34-6627-02

TXSeries For Multiplatforms SFS Server and PPC Gateway Server - Advanced Administration Version 6.2

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TXSeries For Multiplatforms SFS Server and PPC Gateway Server - Advanced Administration Version 6.2

Uploaded by

Copyright:

Available Formats

TXSeries for Multiplatforms

SFS Server and PPC Gateway Server:

TXSeries for Multiplatforms

SFS Server and PPC Gateway Server:

Third Edition (January 2008)

Chapter 1. Introduction to the Server interfaces

Chapter 2. Creating volumes . . . .

Chapter 3. Maintaining volumes . . . . . .

Chapter 4. Managing server transactions

Chapter 5. Performing backups . . . .

Copyright IBM Corp. 1999, 2008

Querying a log volume . . . . . . . . . . . . . . . . . . . . . 31

Chapter 7. Using the CICS Toolkit Trace Facility . . .

Chapter 8. Managing SFS files . . . . . . . .

Importing SFS files . . . . . . . .

Chapter 11. Monitoring and maintaining a gateway server. . . . .

Chapter 12. The ppcadmin command

Chapter 13. The sfsadmin command

Chapter 9. Obtaining SFS volume

Chapter 10. Improving the performance of the

Chapter 14. The tkadmin command

Appendix. Environment Variables . . . . . . . . . . . . . . . . . 235

A disk and its units of allocation . . . . .

Copyright IBM Corp. 1999, 2008

Copyright IBM Corp. 1999, 2008

About this book

Who should read this book

Read about the conventions used in this

Conventions used in this book on page xiv.

Learn about the command line interfaces

Chapter 1, Introduction to the Server

Learn about how to perform volume

Chapter 3, Maintaining volumes, on page

Chapter 5, Performing backups, on page

Learn about how to recover from abnormal

Chapter 6, Recovering from failures, on

Learn about using the CICS Toolkit Trace

Chapter 7, Using the CICS Toolkit Trace

Learn how to create, copy, allocate and

Chapter 8, Managing SFS files, on page

Learn about obtaining SFS volume and

Chapter 9, Obtaining SFS volume and

Learn about improving the performance of

Chapter 10, Improving the performance of

Learn about how to monitor and maintain a

Chapter 11, Monitoring and maintaining a

Learn about the ppcadmin command

Chapter 12, The ppcadmin command, on

Copyright IBM Corp. 1999, 2008

Learn about the sfsadmin command

Chapter 13, The sfsadmin command, on

Learn about the tkadmin command

Chapter 14, The tkadmin command, on

Learn about the Environment Variables

Environment Variables, on page 235

Conventions used in this book

Indicates values that you must use literally, such as commands,

Indicates text that you must enter at a command prompt. Monospace

Encloses the names of keys on the keyboard.

Where x is the name of a key, indicates a control-character

Represents the UNIX command-shell prompt for a command that

Represents the UNIX command-shell prompt for a command that

Represents the Windows command prompt.