Beruflich Dokumente
Kultur Dokumente
SC34-6627-02
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.
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 .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xiii
xiii
xiii
xiv
xv
.
.
.
.
.
1
1
1
3
3
. 7
. 7
. 7
. 9
. . . . . . . . . . . . . . . 10
. . . . . . . . . . . . . . . 11
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
13
13
13
14
14
15
15
16
17
18
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
21
21
21
21
22
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
23
23
24
24
25
25
26
27
28
28
29
29
iii
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
33
33
33
33
34
35
36
39
40
42
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
45
45
45
46
46
46
49
51
51
51
52
54
54
56
56
56
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
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
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
|
|
|
|
|
|
|
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
77
80
85
85
86
86
87
server information .
. . . . . . . .
. . . . . . . .
. . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
89
89
89
90
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
91
91
91
91
92
92
92
92
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 97
. 97
. 97
. 98
. 99
. 99
. 100
. 100
. 102
. 103
. 104
. 105
. 106
. 108
. 109
. 109
. 110
. 110
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . 137
and
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
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 . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Contents
vii
viii
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Figures
1.
2.
3.
4.
5.
6.
7.
8.
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . . 8
. . . 9
. . . 11
. . . 24
. . . 26
. . . 55
. . . 60
. . . 63
ix
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Document organization
Table 1. Road map of CICS SFS Server and PPC Gateway Server: Advanced
Administration
If you want to...
Refer to...
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.
xiii
Table 1. Road map of CICS SFS Server and PPC Gateway Server: Advanced
Administration (continued)
If you want to...
Refer to...
xiv
Convention
Meaning
Bold
Monospace
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.
<>
<Ctrl-x>
<Return>
Refers to the key labeled with the word Return, the word Enter, or
the left arrow.
C:\>
>
Entering commands
[]
{}
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Meaning
...
IN
OUT
INOUT
$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
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).
xv
xvi
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Interface Used
Backing up volumes
tkadmin
tkadmin
sfsadmin
ppcadmin
tkadmin Commands
Backing up volumes
Comments
tkadmin Commands
Comments
Reclaiming space
Repairing mirrors
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
Command syntax
All administrative commands use the same general syntax conventions. The
following shows these conventions:
suite verb object {argument...} -option
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.
tkadmin
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
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.
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
13
Restoring or Relocating
Data Volumes
Restoring or Relocating
Log Volumes
Restart a Server in
Administrative Mode
Use cicssfs/cicsppcgwy
command
Use cicssfs/cicsppcgwy
command
(Not applicable)
(Not applicable)
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:
%
14
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
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:
%
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
You must specify the name of the CICS Toolkit logical volume for the
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:
%
Note: Use the command to determine the chunk size of a physical volume.
5. Restart the server in normal operations mode.
15
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:
%
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:
%
16
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
You must specify the name of the logical volume for the logical_volume_name
argument. For example, enter the following command to delete a logical volume
named sfslvol1:
Chapter 3. Maintaining volumes
17
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:
%
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:
%
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).
You must specify the name of the logical volume for the logical_volume_name
argument. For example, enter the following command to unmap a logical
volume named sfslvol1:
18
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
3. Use an AIX utility to delete the AIX logical volume. You can then reuse the
space previously occupied by the volume.
19
20
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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.
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.
22
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Backup files
Log
file
Time
05
6/
1/
05
5/
1/
05
4/
1/
05
3/
1/
05
2/
1/
05
1/
1/
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).
24
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
2. Use the tkadmin enable mediaarchiving command to enable media archiving for
a server. For example, enter the following command to enable media archiving:
%
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.
The following command flushes log records from the log file to log archive files:
%
25
backup. Different backups of the same volume can overlap or share files. Figure 5
illustrates how complete backups can overlap.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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:
%
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:
%
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:
tkadmin flush mediaarchive -server server_name
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.
28
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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
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.
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.
30
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
31
The following example displays information about the log volume sfs1_logVol:
%
32
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
"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)
35
You must specify the name of the disk to be initialized as the disk_name
argument.
36
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
4. Use the tkadmin move pvol command to move the physical volume. The
command syntax follows:
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. 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:
%
37
You must specify the name of the logical volume for the logical_volume_name
argument. For example, enter the following command to delete the mapping for
a logical volume named 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:
tkadmin init disk -server server_name disk_name
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:
%
5. Use the tkadmin create pvol command to create a new physical volume . The
command syntax follows:
tkadmin create pvol -server server_name physical_volume_name
chunk_size number_of_regions {{disk_name disk_offset
[-regionsize region_size]}...}
You must specify the name of the physical volume for the
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:
%
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
command syntax follows:
tkadmin recreate lvol -server server_name logical_volume_name
physical_volume_name
38
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
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 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:
tkadmin remap lvol -server server_name logical_volume_name
operating_system_logical_volume_name
You must specify the name of the CICS Toolkit logical volume for the
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:
%
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
You must specify the name of the logical volume for the 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:
%
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.
40
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
8. Restart the server in normal operations mode.
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:
1. Restart the server in administrative mode. See Using administrative mode on
page 13 for instructions.
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
physical_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:
%
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
command syntax follows:
tkadmin restore lvols -server server_name number_of_volumes
{{logical_volume_name [-backupfilenum backup_file_number]}...}
[-noresume]
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
42
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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):
%
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:
%
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:
%
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
Chapter 6. Recovering from failures
43
44
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
audit
error
fatal
entry
event
param
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.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Hex Value
C Symbolic
Constant
Type of Tracing
Enabled
trace_event
0x00000001
TRACE_EVENT
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
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 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
Chapter 7. Using the CICS Toolkit Trace Facility
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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:
%
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
Chapter 7. Using the CICS Toolkit Trace Facility
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
50
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
entry:
event:
param:
audit: [formatted,unbuffered]STREAM:stderr
dump:
error: [formatted,unbuffered]STREAM:stderr
fatal: [formatted,unbuffered]STREAM:stderr
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
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.
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:
%
52
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
The following command displays the current ring buffers total size and its segment
size, in bytes, on the standard output stream:
Chapter 7. Using the CICS Toolkit Trace Facility
53
8192
To set the ring buffer size dynamically, use the tkadmin set ringbuffer size
command. The syntax is as follows:
tkadmin set ringbuffer 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 Size: 65536
Present Ring Buffer Segment Size: 8192
Requested Ring Buffer Size: 85536
Resulting Ring Buffer Size: 90112
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.
54
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Thread ID
14
Process ID
Timestamp
Trace ID
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
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.
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:
%
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
56
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
59
60
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Access through
primary key value
Fixed or variable
length
Fixed or variable
length
232 - 10
264 - 10
Limitations on
updating records
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.
61
62
Value
unsignedInt16
signedInt16
unsignedInt32
signedInt32
unsignedInt64
signedInt64
decimal
float
double
string
nlsString
byteArray
timestamp
Value
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
shortVarLenByteArray
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.
64
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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.
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 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:
%
By default, this command copies the file and all of its indices to the volume on
which the original file resides.
66
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
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:
%
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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)
btreeClustered (KSDS)
btreeClustered (KSDS)
btreeClustered (KSDS)
btreeClustered (KSDS)
For more information about using the CICSSDT command, see the TXSeries for
Multiplatforms Administration Reference.
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
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
Chapter 8. Managing SFS files
69
For more information about using the CICSSDT command, see the TXSeries for
Multiplatforms Administration Reference.
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.
%
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
File name: Inventory
Owner: (null)
Open time: Mon May 12 11:17:37 1998
Transaction id: 65717
Number of rpcs: 1
Access mode: shared access
Authority:
insert file
inquire file
Consistency: transactional
Isolational level: serializability
Operation timeout: 30
Auto close: yes
Duplicate detection: current index
Operational force: yes
Label: (null)
70
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
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
72
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
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.
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.
%
Ofd id: 41
File name: Accounts
Owner: (null)
Open time: Mon May 18 11:31:33 1998
Transaction id: 0
Number of rpcs: 1
Access mode: exclusive access
Authority:
insert file
inquire file
exclusive 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: 131275
Ofd idle timeout: 60
Ofd idle timeout policy: sfs_destroyOfdOnConflict
The output from the sfsadmin list ofds command indicates that transaction 131275
holds one locka read lock on the file.
%
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
File name: Inventory
Index name: stocknumIndex
Key value:
0000 0002 0000 0002
........
Lock 3:
Lock mode: intention read lock
File name: Inventory.3
Index name: (null)
Key value:
656d 706c 6f79 6565 2e66 696c 65
Inventory
Lock 4:
Lock mode: read lock
File name: Inventory
Index name: stocknumIndex
Key value:
0000 0001 0000 0001
........
Lock 5:
Lock mode: write lock
File name: Accounts.3
Index name: (null)
Key value:
6169 725f 7265 732e 6669 6c65
Accounts
74
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
v Transaction id refers to the identification number of the transaction associated
with the OFD, if the OFD is transactional. If it is nontransactional, this
identification number is zero.
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.
Chapter 8. Managing SFS files
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 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.
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.
Transaction id refers to the identification number of the transaction against
which the lock is held.
Key value is the value that is locked, represented in raw hexadecimal and in
ASCII.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
For more information about using the CICSSDT command, see the TXSeries for
Multiplatforms Administration Reference.
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.
For more information about using the CICSSDT command, see the TXSeries for
Multiplatforms Administration Reference.
|
|
|
|
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.
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
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):
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
-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.
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[-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
|
|
|
|
|
|
|
|
|
|
|
|
The following command reads the exported file inventory and writes it to an SFS file
named Inventory:
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
80
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
-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.
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
[-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.
81
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[-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.
|
|
|
|
|
|
|
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.
Status code
Description
|
|
|
SFS_IE_BADLY_DELIMITED_BUFFER
|
|
|
|
SFS_IE_CHKPT_FILENAME_CONFLICT
Checkpoint file by
the same name
exists for a different
SFS file
|
|
SFS_IE_DEVICE_ERROR
|
|
|
SFS_IE_END_OF_MEDIA_ON_READ
Next segment to
read was not found
on the media.
SFS_IE_END_OF_MEDIA_ON_WRITE
|
|
SFS_IE_ERROR_IN_TRAILER
82
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
|
|
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
|
|
SFS_IE_INVALID_SEGMENT_HEADER
|
|
SFS_IE_MEDIA_TOO_SMALL_FOR_ METADATA
|
|
|
|
SFS_IE_OPERATION_IN_PROGRESS
Restart, resume, or
force needed to
continue the import
or export
|
|
|
SFS_IE_TRAILER_NOT_EXPORTED
|
|
SFS_IE_UNABLE_TO_ADD_ SECONDARY_INDEX
Cannot add a
secondary index
|
|
SFS_IE_UNABLE_TO_CLOSE_CHKPT_FILE
|
|
SFS_IE_UNABLE_TO_CLOSE_DEVICE
|
|
SFS_IE_UNABLE_TO_CLOSE_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
|
|
SFS_IE_UNABLE_TO_DELETE_CHKPT
Cannot delete
checkpoints
|
|
SFS_IE_UNABLE_TO_DESTROY_CHKPT_FILE
|
|
SFS_IE_UNABLE_TO_DESTROY_FILE
|
|
|
SFS_IE_UNABLE_TO_DETERMINE_ DATA_REP
Cannot determine
the byte order of
integers
Chapter 8. Managing SFS files
83
Table 10. Status code for file import and export (continued)
Status code
Description
|
|
SFS_IE_UNABLE_TO_EXTRACT_KEY
|
|
|
SFS_IE_UNABLE_TO_FIND_RSN_FIELD
|
|
SFS_IE_UNABLE_TO_GET_ATTRIBUTES
|
|
SFS_IE_UNABLE_TO_GET_ESN
|
|
SFS_IE_UNABLE_TO_GET_INFO
|
|
SFS_IE_UNABLE_TO_GET_RSN
|
|
|
SFS_IE_UNABLE_TO_GET_ SECONDARY_INDEX_INFO
|
|
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
|
|
SFS_IE_UNABLE_TO_LOCK_FILE
|
|
SFS_IE_UNABLE_TO_OPEN_CHKPT_FILE
|
|
SFS_IE_UNABLE_TO_OPEN_DEVICE
|
|
SFS_IE_UNABLE_TO_OPEN_FILE
|
|
SFS_IE_UNABLE_TO_POSITION_DEVICE
|
|
SFS_IE_UNABLE_TO_READ_CHKPT_FILE
Cannot read
checkpoints
|
|
SFS_IE_UNABLE_TO_READ_FILE
|
|
SFS_IE_UNABLE_TO_SET_ATTRIBUTE
|
|
SFS_IE_UNABLE_TO_SET_RANGE_ON_CHKPT_FILE
|
|
SFS_IE_UNABLE_TO_SET_RANGE_ON_SFS_FILE
|
|
SFS_IE_UNABLE_TO_UPDATE_CHKPT
Cannot update
checkpoints
|
|
SFS_IE_UNABLE_TO_SET_RANGE_ON_SFS_FILE
84
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Table 10. Status code for file import and export (continued)
Status code
Description
|
|
|
|
SFS_IE_VERSION_UNKNOWN
Version number in
export set is not
recognized
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
85
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following example places a temporary read lock on each record of the
Inventory file as it is exported:
|
|
|
|
|
|
|
|
|
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.
86
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
87
|
|
the target device by compressing relative files during an import, and preventing
RSNs from being written during an export.
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
Volumes:
sfsVol1
sfsVol2
sfsVol3
89
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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).
92
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
94
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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_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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
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
98
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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:
Chapter 11. Monitoring and maintaining a gateway server
99
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:
v Logical unit of work identifier
v Transaction identifier (local tid)
v Global transaction identifier
For example, the following command displays the LUWs and their associated CICS
Toolkit transaction identifiers for the active transactions at a gateway server:
%
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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 Transaction identifier (local tid)
v Global transaction identifier
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:
%
NETWORK1.LUALFRED:12bf45679abc:2a
See ppcadmin query luw on page 131 for a detailed description of command
output.
101
102
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
See ppcadmin list resyncs on page 122 for a detailed description of command
output.
Chapter 11. Monitoring and maintaining a gateway server
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:
%
See ppcadmin query resync on page 133 for a detailed description of command
output.
104
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Command
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:
Chapter 11. Monitoring and maintaining a gateway server
105
Destroy a conversation
Destroy the conversation. The following command destroys the specified
conversation:
%
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
Resync Responsibility
Gateway
Gateway
Gateway
Mainframe
The following command allows you to determine whether the gateway server has
resynchronization responsibility:
%
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.)
%
15432 active
%
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
%
If you wish to commit one or more prepared transactions, use the -commitdesired
option for the tkadmin force transaction command.
%
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.
%
108
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
For example, the following command displays the status of the log identifier name
exchanges at a gateway server:
%
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:
Chapter 11. Monitoring and maintaining a gateway server
109
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.
%
110
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Table 13. PPC Services audit messages concerning resynchronization damage and
errors (continued)
PPC Services Audit Message
111
112
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
ppcadmin
ppcadmin
ppcadmin
ppcadmin
query
query
query
query
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
PPC_TRAN_STATE_PREPARED
Perceived Peer (tran) State: PPC_TRAN_STATE_PENDING
Transaction is prepared and awaiting resolution at this site.
(Not finished.)
A prepare has been sent by the peer. The peer has resynchronization
responsibility towards this site.
Chapter 12. The ppcadmin command
115
Note that the gateway server does not have resynchronization responsibility so you
must explicitly finish transaction 15432.
%
15432 active
%
Related information
v
v
v
v
Synopsis
ppcadmin destroy conv -server server_name Conversation_Id
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.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
117
Examples
The following command destroys the conversation 543ab278:
%
Related information
v
v
v
v
v
ppcadmin
ppcadmin
ppcadmin
ppcadmin
ppcadmin
Synopsis
ppcadmin force xln -server server_name [-mode Mode_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.
[-mode Mode_Name]
Specifies the mode that is used by the Systems Network Architecture (SNA)
118
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
%
Related information
v
v
v
v
ppcadmin
ppcadmin
ppcadmin
ppcadmin
Synopsis
ppcadmin list convs -server server_name
Chapter 12. The ppcadmin command
119
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.
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:
%
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Related information
v
v
v
v
ppcadmin
ppcadmin
ppcadmin
ppcadmin
list luws
list transactions on page 124
query conv on page 126
query luw on page 131
Synopsis
ppcadmin list luws -server server_name
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.
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:
%
121
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
Synopsis
ppcadmin list resyncs -server server_name
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.
Description
The ppcadmin list resyncs command displays information about Logical Units of
Work (LUWs) that have pending resynchronizations.
122
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Examples
The following command displays information about pending resynchronizations:
%
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
transaction at this server.
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.
Chapter 12. The ppcadmin command
123
Related information
v ppcadmin query resync on page 133
Synopsis
ppcadmin list transactions -server server_name
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.
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:
%
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
uniquely at any participating server.
124
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Related information
v ppcadmin list luws on page 121
v ppcadmin query luw on page 131
Synopsis
ppcadmin list xlns -server server_name
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.
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:
%
Related information
v ppcadmin list resyncs on page 122
v ppcadmin query resync on page 133
v ppcadmin query xln on page 135
Synopsis
ppcadmin query conv -server server_name convid
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.
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:
%
126
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
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:
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.
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 transaction program to which the conversation is
allocated.
SyncLevel specifies the level of synchronization for a conversation, one of the
following:
- PPC_NONE
Chapter 12. The ppcadmin command
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
129
Related information
v
v
v
v
130
ppcadmin
ppcadmin
ppcadmin
ppcadmin
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Synopsis
ppcadmin query luw -server server_name LUW_Id
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.
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:
%
NETWORK1.LUALFRED:12bf45679abc:2a
2
Transaction Id:
15
Global tid:
0000000d0112010128afc9666352cdb274080009
convId:
543ab278
Executive LU:
ORDENTRY
SNA Partner LU: SNALU02
Conversation Correlator: 1710026500000008
Session Id:
f000000000000005
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
convId:
573ab478
Executive LU:
EXECLU02
SNA Partner LU: SNALU02
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
transaction at this server.
v Global tid specifies the global transaction identifier. It identifies a transaction
uniquely at any participating server.
v convId specifies the conversation identifier.
v Executive LU specifies the Logical Unit (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 all 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.
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 is prepared and awaiting resolution at this site. (Not finished.)
Transaction has finished at this site.
This site is about to abort the transaction.
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.)
A prepare has been sent to the peer. This site has resynchronization
responsibility towards the peer.
Peer is prepared and awaiting resolution of the transaction. This site has
resynchronization responsibility towards the peer.
Transaction has finished at the peer.
132
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Related information
v ppcadmin list luws on page 121
v ppcadmin list transactions on page 124
Synopsis
ppcadmin query 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. (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
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 SNA Partner LU specifies the LU alias for the mainframe LU.
v For each transaction with a pending resynchronization, the following information
is displayed:
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.
Transaction Id specifies 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.
convId specifies the conversation identifier.
Conversation Correlator uniquely identifies a conversation across all LUs.
This is used during the Compare States phase of resynchronization.
When there is a loopback from the mainframe, multiple conversations connect
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.
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.
Session Id specifies a unique identifier of the session that is used by the two
communicating LUs.
134
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
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.)
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
v ppcadmin list resyncs on page 122
135
Synopsis
ppcadmin query xln -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). (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:
%
Related information
v ppcadmin list resyncs on page 122
v ppcadmin list xlns on page 125
v ppcadmin query resync on page 133
136
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
137
Synopsis
sfsadmin copy file -server server_name source_file target_file
[-targetvolume target_volume]
[-indices number_of_indices {{index_name [-itargetvolume index_target_volume]}...}]
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.
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.
[-targetvolume target_volume]
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Synopsis
sfsadmin expand file -server server_name file_name number_of_pages
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.
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:
%
Related information
v sfsadmin copy file on page 138
v sfsadmin rename file on page 140
139
Synopsis
sfsadmin rename file -server server_name file_name new_file_name
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.
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:
%
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
Synopsis
sfsadmin reorganize file -server server_name file_name [-indices]
140
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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:
%
Related information
v sfsadmin copy file on page 138
v sfsadmin expand file on page 139
v sfsadmin rename file on page 140
|
Purpose
|
|
|
|
|
Synopsis
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.
|
|
file_name
Specifies the name of the file to be created.
|
|
|
|
141
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
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 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.
|
|
|
|
|
The names of files, fields, and indices can be any sequence of null-terminated
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.
v Field and index names must be less than or equal to 32 characters.
142
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
|
|
|
Related Information
|
|
Purpose
|
|
|
|
|
Synopsis
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.
|
|
file_name
Specifies the name of the file to be created.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
primary_index
Specifies the name of the primary index of the new relative file.
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 name of the volume for the newly created file.
|
|
[-preallocate number_of_pages]
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 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.
|
|
|
|
|
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.
v Field and index names must be less than or equal to 32 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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Privilege Required
|
|
|
Related Information
|
|
Purpose
|
|
|
|
|
Synopsis
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.
|
|
file_name
Specifies the name of the file to be created.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
primary_index
Specifies the name of the primary index of the new sequential file.
|
|
volume_name
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 that can be inserted in the file. If
-recordlimit is not specified, the record limit for sequential files is 236-10.
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 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.
|
|
|
|
|
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.
v Field and index names must be less than or equal to 32 characters.
Examples
|
|
|
|
|
|
|
|
|
|
Privilege Required
|
|
Related Information
|
|
|
Purpose
|
|
Synopsis
sfsadmin list files -server server_name
146
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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
|
|
|
|
Related Information
|
|
|
|
|
v
v
v
v
v
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
Purpose
|
|
Synopsis
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.
|
|
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.
147
Examples
|
|
Privilege Required
CICS_TK SFS administer (A) and exclusive open (E) permissions on the file.
|
|
|
|
|
|
Related Information
|
|
Purpose
Removes the contents of the specified file, leaving the record format intact.
|
|
Synopsis
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.
|
|
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
|
|
Privilege Required
CICS_TK SFS administer (A) and exclusive open (E) permissions on file.
148
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
|
|
|
|
|
|
|
|
Related Information
v
v
v
v
v
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
Purpose
|
|
Synopsis
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.
|
|
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.
|
|
149
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
v Secondary indices lists the names of any secondary indices associated with the
file.
Privilege Required
|
|
|
|
|
Related Information
|
|
Synopsis
sfsadmin list ofds -server server_name [-brief]
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.
[-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.
%
Ofd id: 33
File name: Inventory
Owner: (null)
Open time: Mon Oct 18 11:12:04 1993
Transaction id: 0
Number of rpcs: 139
Access mode: shared access
Authority:
read file
Chapter 13. The sfsadmin command
151
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
File name: Inventory
Owner: (null)
Open time: Mon Oct 18 11:17:37 1993
Transaction id: 65717
Number of rpcs: 1
Access mode: shared access
Authority:
insert file
inquire file
Consistency: transactional
Isolational level: serializability
Operation timeout: 30
Auto close: yes
Duplicate detection: current index
Operational force: yes
Label: (null)
Open transaction id: 65717
Ofd idle timeout: 60
Ofd idle timeout policy: sfs_destroyOfdOnConflict
Ofd id: 39
File name: Accounts
Owner: (null)
Open time: Mon Oct 18 11:22:08 1993
Transaction id: 65785
Number of rpcs: 35
Access mode: exclusive access
Authority:
read file
insert file
update file
delete file
inquire file
exclusive file
administer file
Consistency: transactional
Isolational level: cursor stability
Operation timeout: 45
Auto close: no
Duplicate detection: no detection
Operational force: yes
Label: (null)
Open transaction id: 65780
Ofd idle timeout: 60
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.
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
153
Related information
v sfsadmin query ofd
v sfsadmin terminate ofd on page 156
Synopsis
sfsadmin query ofd -server server_name server_ofd_number
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.
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:
%
Ofd id: 33
File name: Inventory
Owner: (null)
Open time: Mon Oct 18 11:12:04 1993
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
154
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Output
The following list explains the elements in the output of the 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 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 may 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 will take to complete before timing out.
v
v
v
v
v
v
155
Related information
v sfsadmin list ofds on page 151
v sfsadmin terminate ofd
Synopsis
sfsadmin terminate ofd -server server_name server_ofd_number
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.
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:
%
Related information
v sfsadmin query ofd on page 154
v sfsadmin query tranlock on page 166
v sfsadmin list ofds on page 151
156
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
Synopsis
sfsadmin query server -server server_name
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.
Description
The command displays the settings for a server.
Examples
The following command displays information about the 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
The following list explains the elements in the output of the command:
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.
Chapter 13. The sfsadmin command
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.
|
Purpose
|
|
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
|
|
Privilege Required
Related Information
|
|
|
|
Purpose
|
|
Synopsis
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.
158
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
|
|
Related Information
|
|
|
Purpose
|
|
Synopsis
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.
|
|
volume_name
Specifies the name of the volume about which information is being requested.
Description
|
|
|
|
|
|
159
Examples
|
|
|
|
|
|
|
|
|
|
|
|
Privilege Required
|
|
|
Related Information
|
|
Purpose
|
|
Synopsis
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.
|
|
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.
160
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 (Other platforms or AIX with CICS_TK logical volume
management)
The following commands map the logical volume sfsVol1 on the server;
|
|
|
|
/.:/branch1/server/sfs1:
% 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
161
Privilege Required
|
|
|
|
|
|
Related Information
v sfsadmin add lvol on page 163
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
|
|
|
|
|
|
Purpose
|
|
Synopsis
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.
|
|
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.
|
|
|
|
|
|
|
|
|
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.
162
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
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
/.:/branch1/server/sfs1:
Privilege Required
|
|
|
|
|
Related Information
|
|
|
|
|
|
v
v
v
v
v
v
v
v
Purpose
|
|
Synopsis
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_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
/.:/branch1/server/sfs1:
163
Privilege Required
|
|
|
|
|
|
Related Information
v
v
v
v
v
v
v
|
|
Synopsis
sfsadmin query filelock -server server_name file_name
-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.
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.
%
164
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
3030 3035
ofd id: 2
transaction id: 0
openTid: 39
open lock mode: shared access
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
open lock mode: shared access
file locks:
lock 1:
lock mode:
intention read lock
consistency: nontransactional
transaction id: 57
record locks:
lock 1:
lock mode:
read lock
consistency: nontransactional
index:
primary
transaction id: 57
key value:
3030 3034
0005
0004
Output
The following list explains the output of the command:
v Ofd id is the identification number used by the server for the OFD.
v Transaction id refers to the identification number of the transaction associated
with the OFD, if the OFD is transactional. If it is nontransactional, this
identification number is zero.
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 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 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.
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.
Transaction id refers to the identification number of the transaction against
which the lock is held.
Key value is the value that is locked, represented in raw hexadecimal and in
ASCII.
Related information
v
v
v
v
v
Synopsis
sfsadmin query tranlock -server server_name tid
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.
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.
%
Ofd id: 41
File name: Accounts
Owner: (null)
Open time: Mon Oct 18 11:31:33 1993
Transaction id: 0
Number of rpcs: 1
Access mode: exclusive access
Authority:
insert file
inquire file
exclusive file
Consistency: non-transactional
Isolational level: non-tran accumulate
166
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Operation timeout: 20
Auto close: no
Duplicate detection: no detection
Operational force: no
Label: (null)
Open transaction id: 131275
Ofd idle timeout: 60
Ofd idle timeout policy: sfs_destroyOfdOnConflict
%
Lock 1:
Lock mode: read lock
File name: Accounts.5
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
File name: Inventory.3
Index name: (null)
Key value:
656d 706c 6f79 6565 2e66 696c 65
Inventory
Lock 2:
Lock mode: write lock
File name: Inventory
Index name: stockNumIndex
Key value:
0000 0002 0000 0002
........
Lock 3:
Lock mode: intention read lock
File name: Inventory.3
Index name: (null)
Key value:
656d 706c 6f79 6565 2e66 696c 65
Inventory
Lock 4:
Lock mode: read lock
File name: Inventory
Index name: stockNumIndex
Key value:
0000 0001 0000 0001
........
Lock 5:
Lock mode: write lock
File name: Accounts.3
Index name: (null)
Key value:
6169 725f 7265 732e 6669 6c65
Accounts
Output
The following list explains the elements in the output of the 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 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
|
Purpose
|
|
|
|
|
|
|
|
|
|
|
Synopsis
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.
|
|
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.
|
|
|
|
|
|
|
|
|
[-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
168
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
|
|
[-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.
|
|
|
|
[-preallocate number_of_pages]
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
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.
Chapter 13. The sfsadmin command
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
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
|
|
|
|
Purpose
|
|
Synopsis
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.
|
|
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:
170
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Privilege Required
CICS_TK SFS administer (A) and exclusive open (E) permissions on the file.
|
|
Related Information
|
|
|
|
|
|
|
|
sfsadmin
sfsadmin
sfsadmin
sfsadmin
Purpose
|
|
Synopsis
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.
|
|
|
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.
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
CICS_TK SFS administer (A) and exclusive open (E) permissions on the file.
|
|
|
|
Related Information
|
|
|
|
|
sfsadmin
sfsadmin
sfsadmin
sfsadmin
Purpose
|
|
Synopsis
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.
|
|
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
|
|
172
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Purpose
|
|
Synopsis
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.
|
|
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
|
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
Related Information
|
|
|
|
|
|
|
|
|
|
|
|
|
|
v
v
v
v
v
v
v
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
sfsadmin
Synopsis
sfsadmin rename index -server server_name file_name index_name new_index_name
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.
file_name
Specifies the name of the file containing the index to be renamed.
174
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
Synopsis
sfsadmin expand index -server server_name file_name index_name number_of_pages
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.
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:
%
175
Related information
v sfsadmin rename index on page 174
176
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
tkadmin
177
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Synopsis
tkadmin add mirror -server server_name logical_volume_name physical_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
logical_volume_name
Specifies the logical volume to be mirrored.
physical_volume_name
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
Chapter 14. The tkadmin command
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:
%
Related information
v tkadmin sync mirrors on page 229
v tkadmin remove mirror on page 221
Synopsis
tkadmin backup lvol -server server_name logical_volume_name
[-fileprefix file_prefix] [-filesize file_size] [-nfiles number_of_files]
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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.
[-nfiles number_of_files]
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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):
%
Related information
v tkadmin enable mediaarchiving on page 191
v tkadmin query backup on page 207
v tkadmin query lvol on page 211
Synopsis
tkadmin create lvol -server server_name logical_volume_name physical_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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.
physical_volume_name
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:
%
Related information
v tkadmin delete lvol on page 184
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 server affected by the command. This should be the name that
was specified when the server was configured.
physical_volume_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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
%
Note: Do not use this command if you are using AIX logical volume management.
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
v tkadmin init disk on page 196
Synopsis
tkadmin delete disk -server server_name disk_name
183
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Note: Do not use this command if you are using AIX logical volume management.
Windows
The following command deletes the logical disk \\.D::
C:\> tkadmin delete disk \\.\D:
Related information
v tkadmin delete pvol on page 185
v tkadmin init disk on page 196
Synopsis
tkadmin delete lvol -server server_name logical_volume_name
184
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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.
Note: Do not use this command if you are using AIX logical volume management.
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:
%
Related information
v tkadmin disable lvol on page 186
v tkadmin init disk on page 196
Synopsis
tkadmin delete pvol -server server_name physical_volume_name
185
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
physical_volume_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).
Note: Do not use this command if you are using AIX logical volume management.
Examples
The following example deletes the physical volume pvol3:
%
Related information
v tkadmin create pvol on page 182
v tkadmin delete lvol on page 184
Synopsis
tkadmin disable lvol -server server_name logical_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
Related information
v tkadmin enable lvol on page 190
Synopsis
tkadmin disable mediaarchiving -server server_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Related information
v tkadmin enable mediaarchiving on page 191
v tkadmin query mediaarchiving on page 212
Synopsis
tkadmin dump ringbuffer -server server_name file_name [-binary] [-overwrite]
187
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Related information
v tkadmin set ringbuffer size on page 228
Synopsis
tkadmin enable archfile -server server_name archive_file_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
189
Synopsis
tkadmin enable logfile -server server_name log_file_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Related information
v tkadmin recover lvols on page 216
Synopsis
tkadmin enable lvol -server server_name logical_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
Related information
v tkadmin disable lvol on page 186
Synopsis
tkadmin enable mediaarchiving -server server_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Related information
v tkadmin disable mediaarchiving on page 187
v tkadmin query mediaarchiving on page 212
Synopsis
tkadmin expand lvol -server server_name logical_volume_name new_size
191
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Related information
v tkadmin expand pvol
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 server affected by the command. This should be the name that
was specified when the server was configured.
physical_volume_name
Specifies the physical volume to be expanded.
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.
192
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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.
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
specified for each region.
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.
%
Note: Do not use this command if you are using AIX logical volume management.
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
v tkadmin create pvol on page 182
v tkadmin init disk on page 196
Synopsis
tkadmin flush lvol -server server_name [-lvolname logical_volume_name]
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
[-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.
%
Synopsis
tkadmin flush mediaarchive -server server_name
194
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Related information
v tkadmin enable mediaarchiving on page 191
v tkadmin query mediaarchiving on page 212
Synopsis
tkadmin force transaction -server server_name tid [-commitdesired] [-finish]
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.
[-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
Chapter 14. The tkadmin command
195
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:
%
Related information
v tkadmin list transactions on page 202
v tkadmin abort transaction on page 178
Synopsis
tkadmin init disk -server server_name disk_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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).
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.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
Note: Do not use this command if you are using AIX logical volume management.
Windows
The following command initializes the logical disk drive \\.\D::
C:\> tkadmin init disk \\.\D:
Related information
v tkadmin delete disk on page 183
Synopsis
tkadmin list disks -server server_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
\\.\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).
197
Examples
Open Systems
The following command lists all disks initialized by the server:
%
/dev/rsd1e
/dev/rsd1f
Note: Do not use this command if you are using AIX logical volume management.
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
Synopsis
tkadmin list lvols -server server_name [-enabled]
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
[-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:
%
lvol1
lvol2
Related information
v tkadmin query lvol on page 211
198
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Synopsis
tkadmin list pvols -server server_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
pvol1
pvol2
Related information
v tkadmin query pvol on page 213
Synopsis
tkadmin list redirect -server server_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
error: [formatted,unbuffered]STREAM:stderr
fatal: [formatted,unbuffered]STREAM:stderr
Related information
v tkadmin query redirect on page 214
v tkadmin redirect trace on page 218
Synopsis
tkadmin list rmi -server server_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
Description
The tkadmin list rmi command lists information on RMIs currently registered by a
server.
Synopsis
tkadmin list trace -server server_name [-product product_name]
[-component component_name]
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
[-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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
server, sfs, ppc, and private. For example, exec (CICS Toolkit Executive)
includes several components such as threadTid, trdce and trpc.
[-component component_name]
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:
%
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:
%
The following command displays the trace mask for the tran component:
%
Related information
v tkadmin query trace on page 214
v tkadmin trace specification on page 230
Synopsis
tkadmin list transactions -server server_name [-originator application]
[-participant application] [-global identifier]
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
[-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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Chapter 14. The tkadmin command
203
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.
%
Related information
v tkadmin abort transaction on page 178
v tkadmin force transaction on page 195
Synopsis
tkadmin map lvol -server server_name logical_volume_name
operating_system_logical_volume_name chunk_size
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
logical_volume_name
Specifies the CICS Toolkit logical volume to be created by mapping it to an AIX
logical volume.
operating_system_logical_volume_name
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Before issuing this command, take the following cautions into consideration:
v You should not change the name of the AIX logical volume after mapping it to an
CICS Toolkit logical volume.
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:
%
Related information
v tkadmin unmap lvol on page 232
v tkadmin remap lvol on page 220
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 server affected by the command. This should be the name that
was specified when the server was configured.
physical_volume_name
Specifies the physical volume to be moved.
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.
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
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 a Windows system, you must
ensure that the physical disk does not contain any configured partitions.
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
specified for each region.
Note: If you are using an entire physical disk on a Windows system, you must
ensure that the physical disk does not contain any configured partitions.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Note: Do not use this command if you are using AIX logical volume management.
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 create pvol on page 182
v tkadmin expand pvol on page 192
Synopsis
tkadmin query backup -server server_name logical_volume_name
[-backupfilenum backup_file_number] [-count count] [-all]
207
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
208
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
log/logvol.LA.92
Earliest log archive file required to restore the log volume can
be determined via the tkadmin query logvol command.
The following command displays information about all backups of the volume Lvol:
%
The following command displays information about the last two complete,
independent backups of the volume Lvol:
%
209
Related information
v tkadmin backup lvol on page 180
Synopsis
tkadmin query disk -server server_name disk_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Note: Do not use this command if you are using AIX logical volume management.
Windows
The following command displays information for the disk \\.\D::
210
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Related information
v tkadmin list disks on page 197
Synopsis
tkadmin query logvol -server server_name log_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
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:
%
211
Synopsis
tkadmin query lvol -server server_name logical_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Related information
v tkadmin list lvols on page 198
Synopsis
tkadmin query mediaarchiving -server server_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Examples
The following command displays the media archiving status for a server:
%
Related information
v tkadmin enable mediaarchiving on page 191
v tkadmin disable mediaarchiving on page 187
Synopsis
tkadmin query pvol -server server_name physical_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
physical_volume_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.
%
Note: Do not use this command if you are using AIX logical volume management.
Windows
In the following example, the sfsDataPvol physical volume is queried.
C:\> tkadmin query pvol sfsDataPvol
213
Related information
v tkadmin list pvols on page 199
Synopsis
tkadmin query redirect -server server_name
{entry | event | param | audit | dump | error | fatal | trace}
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
{entry | event | param | audit | dump | error | fatal | trace}
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:
%
error: [formatted,unbuffered]STREAM:stderr
Related information
v tkadmin list redirect on page 199
v tkadmin redirect trace on page 218
214
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Synopsis
tkadmin query trace -server server_name component_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
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
Synopsis
tkadmin query transaction -server server_name tid [-state] [-originator]
[-participants] [-global] [-start]
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.
Chapter 14. The tkadmin command
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.
%
The following command displays state information, only, for transaction 65536 :
%
commitcomplete
The following command displays the start time, only, for transaction 65536 :
%
Related information
v tkadmin abort transaction on page 178
v tkadmin force transaction on page 195
v tkadmin list transactions on page 202
216
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Synopsis
tkadmin recover lvols -server server_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
Synopsis
tkadmin recreate lvol -server server_name logical_volume_name physical_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
logical_volume_name
Specifies the logical volume to re-create.
physical_volume_name
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:
%
Related information
v tkadmin delete lvol on page 184
Synopsis
tkadmin redirect trace -server server_name
{entry | event | param | audit | dump | error | fatal | trace}
[-destination destination]
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
{entry | event | param | audit | dump | error | fatal | trace}
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
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:
%
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.
%
The following command redirects trace entry, event, and param output to the
stdout stream without buffering:
%
Synopsis
tkadmin remap lvol -server server_name logical_volume_name
operating_system_logical_volume_name chunk_size
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
logical_volume_name
Specifies the logical volume to be created by remapping the AIX volume.
220
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
operating_system_logical_volume_name
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
Before issuing this command, take the following cautions into consideration:
v You should not change the name of the AIX logical volume after mapping it to a
CICS Toolkit logical volume.
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:
%
Related information
v tkadmin map lvol on page 204
v tkadmin unmap lvol on page 232
221
Synopsis
tkadmin remove mirror -server server_name logical_volume_name physical_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
logical_volume_name
Specifies the logical volume for which the mirror is being removed.
physical_volume_name
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.
Note: Do not use this command if you are using AIX logical volume management.
Examples
In the following example, the pvol3 mirror of the data stored on the lvol8 logical
volume is removed:
%
Related information
v tkadmin delete lvol on page 184
v tkadmin remove mirror on page 221
Synopsis
tkadmin rename lvol -server server_name old_name new_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
old_name
Specifies the logical volume to be renamed.
222
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
Related information
v tkadmin expand lvol on page 191
Synopsis
tkadmin rename pvol -server server_name old_name new_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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.)
Note: Do not use this command if you are using AIX logical volume management.
223
Examples
The following command renames physical volume pvol3 to pvol3.new:
%
Synopsis
tkadmin restore logvol -server server_name log_volume_name archive_device_name
archive_file_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Synopsis
tkadmin restore lvols -server server_name number_of_volumes {{logical_volume_name
[-nobackup] [-backupfilenum backup_file_number]}...} [-noresume]
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
Before issuing this command, take the following cautions into consideration:
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.
%
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
v tkadmin backup lvol on page 180
v tkadmin query backup on page 207
Synopsis
tkadmin retain backups -server server_name logical_volume_name number_of_backups
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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:
%
As the output indicates, backup files 0 through 4 are no longer needed and can be
deleted safely.
Related information
v tkadmin backup lvol on page 180
v tkadmin query backup on page 207
Synopsis
tkadmin set ringbuffer size
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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 Size: 65536
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
Synopsis
tkadmin show ringbuffer size -server server_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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 Size: 65536
Present Ring Buffer Segment Size:
8192
Related information
v tkadmin dump ringbuffer on page 187
v tkadmin set ringbuffer size on page 228
Synopsis
tkadmin sync mirrors -server server_name logical_volume_name
229
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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.
Note: Do not use this command if you are using AIX logical volume management.
Examples
In the following example, the physical volumes backing the lvol8 logical volume (an
up-to-date copy and a new mirror) are synchronized.
%
Related information
v tkadmin remove mirror on page 221
Synopsis
tkadmin trace specification -server server_name specification
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
The following example adds parameter tracing to the current trace mask for the
trpc component:
%
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:
Chapter 14. The tkadmin command
231
The following example disables event tracing only for the trpc component:
%
Related information
v tkadmin list trace on page 200
v tkadmin query trace on page 214
Synopsis
tkadmin unmap lvol -server server_name logical_volume_name
Arguments
-server server_name
Specifies the server affected by the command. This should be the name that
was specified when the server was configured.
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
Before issuing this command, take the following cautions into consideration:
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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:
%
Related information
v tkadmin map lvol on page 204
v tkadmin remap lvol on page 220
233
234
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
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).
|
|
setenv CICS_TK_ADMIN_THREADS 2
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
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:
@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.
|
|
|
filename
The initial part of the file name used to hold the dump. Normally, this is
set to the program name.
|
|
%d
|
|
%s
|
|
%d
|
|
|
|
|
|
|
|
|
CICS_TK_BDE_STACK_SIZE
Specifies the stack size, in bytes, for threads created by CICS_TK applications.
The default value varies by platform.
|
|
|
|
|
|
|
|
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.
|
|
|
|
setenv CICS_TK_DEFAULT_THREAD_POOL_QUEUE_LENGTH 5
236
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
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.
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
CICS_TK_FLT_INACTIVE_TIMEOUT
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
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
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
|
|
|
setenv CICS_TK_TPOOL_SIZE 8
238
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
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).
|
|
|
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.
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.)
String value
Expression
trace_event
trace_entry
trace_param
trace_internal_entry
trace_internal_param
|
|
|
|
trace_global
|
|
trace_export
trace_dump
trace_dump_selected
trace_all
|
|
all
|
|
|
|
|
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
|
|
|
|
|
|
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).
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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).
|
|
|
|
|
|
|
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.
|
|
CICS_TK_TRACE_VERBOSE
Redirects trace output to either the standard error stream (stderr) or the
Appendix. Environment Variables
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.
|
|
|
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.
|
|
|
|
|
|
|
|
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
Values
Events to be traced
audit
critical
dump
entry
error
event
Trace events
fatal
param
Trace parameters
serious
Same as critical
|
|
|
trace
|
|
|
CICS_TK_TRAN_TUNING
The CICS_TK_TRAN_TUNING environment variable sets TRAN tuning
parameters.
|
|
|
|
|
|
|
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.
|
|
|
|
242
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
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).
|
|
|
|
|
|
|
|
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.
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:
|
|
|
|
|
|
|
|
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 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
|
|
|
|
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
|
|
|
|
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.
|
|
|
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...]]
|
|
|
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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
244
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
Copyright IBM Corp. 1999, 2008
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.
CICS/400
248
AIX
CICS
CICS/6000
CICS/ESA
CICS/MVS
CICS/VSE
CICSPlex
C-ISAM
Database 2
DB2
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
System/390
TXSeries
TCS
VisualAge
VSE/ESA
VTAM
WebSphere
z/OS
Other company, product, and service names may be trademarks or service marks
of others.
Notices
249
250
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
Index
A
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
Copyright IBM Corp. 1999, 2008
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
physical volumes 185
destroying
conversations 105, 116
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
E
emptying
files in SFS 76
enabling
archive files 188
log files 189
logical volumes 190
media archiving 24, 191
trace for server components
entry-sequenced files
creating 63
252
230
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 information 69
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
G
generating
log archive files
24
I
indentTrace command 56
initializing
disks 196
interpretTrace command 54, 56
L
listing
components for servers 48
conversations 97, 119
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
physical volumes 199
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
transactions 99, 202
locks (SFS)
displaying information 166
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 211
displaying information in SFS 89
enabling 190
expanding 191
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
AIX logical volumes 39
backups offline 28
physical volumes 16, 36, 205
O
OFDs
closing 76, 156
displaying 70, 151, 154
displaying information 72
Index
253
P
pages 9
physical volumes 7
creating 182
deleting 185
displaying 199
displaying information 213
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
backup information 207
backups 29
conversations 98, 126
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
media archiving 24, 212
OFDs 72, 154
physical volume information 213
resynchronizations 104
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
logical volumes 37, 217
redirecting
trace output 51, 218
region 8
relative files
creating 64
remapping
AIX logical volumes 39, 220
removing
mirrors 221
renaming
AIX logical volumes 15
files in SFS 67, 140
logical volumes 14, 222
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
resynchronizations 102
canceling 106, 113
displaying 104
listing 103
reporting damage 110
retaining
backup information 227
ring buffer size
changing 53, 228
setting 53, 228
ring buffers 51
displaying size 53, 229
dumping 52, 187
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
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
displaying information 90
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
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
TXSeries for Multiplatforms: SFS Server and PPC Gateway Server: Advanced Administration
SC34-6627-02
TXSeries for Multiplatforms
Spine information:
Version 6.2
SC34-6627-02