Airline Control System Version 2
Documentation Changes for
Data Event Control Block (DECB) Support
APAR AQ54564
SH19-6742-06
IBM
Airline Control System Version 2
Documentation Changes for
Data Event Control Block (DECB) Support
APAR AQ54564
SH19-6742-06
ii
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Contents
Introduction
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 1. ALCS Version 2 concepts and facilities
1.2 Standard record and storage block sizes . . . .
1.3 Multiprogramming and multiprocessing
. . . . .
Chapter 2. ALCS database file management
2.1 The ALCS real-time database . . . . . . .
2.2 General files and general data sets
. . .
2.3 Record addressing . . . . . . . . . . . . .
2.4 Allocatable space overview . . . . . . . .
2.5 Record header . . . . . . . . . . . . . . . .
2.6 Virtual file access . . . . . . . . . . . . . .
2.7 Spill file on predecessor ALCS systems .
2.8 The ALCS test database facility . . . . . .
2.9 The ALCS DASD configuration data set .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 3. Entry management . . . . . . . . . . . . .
3.1 How ALCS creates entries . . . . . . . . . . . . . .
3.2 How ALCS dispatches entries . . . . . . . . . . . .
3.3 How entries lose control . . . . . . . . . . . . . . .
. . . . . . .
3.4 Input/output counter and wait service
3.5 Delay and defer processing . . . . . . . . . . . . .
3.6 Communication between entries . . . . . . . . . .
3.7 Transactions that create multiple entries . . . . . .
3.8 Entries using SQL, CPI-C, APPC, MQI and TCP/IP
Chapter 4. Storage management
4.1 Storage layout . . . . . . . . .
4.2 Entry storage
. . . . . . . . .
4.3 High-level language storage .
. . . . . . . . .
4.4 Storage units
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 5. ALCS services . . . . . . . . . . .
5.1 ALCS services for communication . . . . .
5.2 ALCS services for DASD processing . . . .
5.3 ALCS services for sequential file processing
5.4 ALCS entry management services . . . . .
5.5 ALCS storage management services . . . .
5.6 ALCS services for global area processing .
5.7 ALCS services for program linkage . . . . .
Chapter 6. Overview of ALCS . . . . . . . .
6.1 What ALCS provides . . . . . . . . . . . .
6.2 Agent sets . . . . . . . . . . . . . . . . . .
6.3 Functions performed by ALCS
. . . . . .
6.4 Processing a message . . . . . . . . . . .
6.5 Using information from previous messages
6.6 Application programs in ALCS
. . . . . .
6.7 Direct access files . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xii
1
7
9
15
16
22
23
27
33
34
35
36
40
42
42
44
46
47
47
48
50
51
54
54
55
56
57
60
60
61
62
63
64
65
66
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
67
67
68
68
69
73
74
75
Contents
iii
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.8 Sequential files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.9 Communication with users, other systems, and other applications
6.10 ALCS applications . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 7. Data in ALCS . . . . . . . . . .
7.1 Using direct access files . . . . . . . . .
7.2 Reading and writing DASD records . . .
7.3 Serialization . . . . . . . . . . . . . . . .
7.4 Using sequential files . . . . . . . . . . .
7.5 Global records and fields
. . . . . . . .
7.6 Globals — compatibility with TPF . . . .
7.7 Using Structured Query Language (SQL)
7.8 Designing databases for use with ALCS
7.9 Organizing data . . . . . . . . . . . . . .
7.10 Record classes
. . . . . . . . . . . . .
7.11 Commit and backout . . . . . . . . . .
7.12 Utility programs . . . . . . . . . . . . .
|
|
|
|
|
|
. . . . . . . . . . . . . . . . . . .
80
80
81
82
82
. 84
. 87
. 98
101
107
109
111
114
114
117
121
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 8. The entry control block (ECB) and other entry storage
8.1 Format of the ECB . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2 ECB work areas 1 and 2 . . . . . . . . . . . . . . . . . . . . . . . .
8.3 ECB local program work area . . . . . . . . . . . . . . . . . . . . .
8.4 ECB data levels and storage levels
. . . . . . . . . . . . . . . . .
8.5 Entry origin fields . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.6 User register save areas . . . . . . . . . . . . . . . . . . . . . . . .
8.7 ECB error indicators . . . . . . . . . . . . . . . . . . . . . . . . . .
8.8 ECB user area reserved for system-wide fields . . . . . . . . . . .
8.9 TCP/IP socket descriptor . . . . . . . . . . . . . . . . . . . . . . . .
8.10 The routing control parameter list (RCPL) area . . . . . . . . . .
8.11 ECB areas reserved for ALCS use . . . . . . . . . . . . . . . . .
8.12 Accessing the ECB . . . . . . . . . . . . . . . . . . . . . . . . . .
8.13 Other entry storage . . . . . . . . . . . . . . . . . . . . . . . . . .
8.14 ECB user data collection area . . . . . . . . . . . . . . . . . . . .
8.15 Automatically-allocated storage . . . . . . . . . . . . . . . . . . .
8.16 Storage blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.17 Local save stack . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.18 Data event control blocks (DECBs) . . . . . . . . . . . . . . . . .
Chapter 9. Error conditions and error processing
9.1 Error conditions . . . . . . . . . . . . . . . . . . .
9.2 The ALCS wait mechanism and error processing
9.3 Dealing with errors . . . . . . . . . . . . . . . . .
9.4 Sequential file errors . . . . . . . . . . . . . . . .
9.5 Application program logic errors
. . . . . . . . .
9.6 Error recovery . . . . . . . . . . . . . . . . . . . .
Chapter 10. Using the ALCS trace facility . . .
10.1 Destinations . . . . . . . . . . . . . . . . . .
10.2 Tracing to the system macro trace block . .
10.3 Tracing to the ALCS diagnostic file . . . . .
10.4 Tracing to the MVS generalized trace facility
10.5 Workstation trace . . . . . . . . . . . . . . .
10.6 TPFDF macro trace . . . . . . . . . . . . . .
10.7 Conversational tracing
. . . . . . . . . . . .
iv
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
123
123
124
126
127
128
128
130
130
130
130
131
131
132
132
132
133
136
136
146
146
148
152
156
159
159
162
162
164
165
168
169
170
171
10.8 Running a conversational trace . . . .
10.9 ADSTOP — Address stop . . . . . . . . .
10.10 ANYSTOP — Any stop . . . . . . . . . .
10.11 BRANCH — Branch to address . . . . .
10.12 Display internal TPFDF macro calls .
10.13 DISPLAY — Display fields . . . . . . .
10.14 EXIT — Exit current entry . . . . . . .
10.15 FLUSH — Flush current entry . . . . .
10.16 HELP — Display trace help information
10.17 PROCESS — Process message
. . . .
10.18 REFSTOP — Reference stop . . . . . .
10.19 REGSTOP — Register stop . . . . . . .
10.20 SET — Set fields . . . . . . . . . . . .
10.21 SKIP — Skip next instruction or macro
10.22 STEP — Control instruction stepping .
10.23 SWAP — Swap current entry . . . . . .
Chapter 11. Maintaining ALCS
. . . .
11.1 MVS diagnostic facilities . . . . . .
11.2 Problem determination in ALCS . .
11.3 Performance monitoring and control
11.4 Improving application performance
11.5 Applying corrective service . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
| Chapter 12. Macros and callable services
. . . . . . . . . . . . . . . . . . . . . . . .
12.1 ATTAC – Attach a previously detached storage block . . . . . . . . . . . . . . . . .
12.2 CRUSA – Release storage blocks from specified levels . . . . . . . . . . . . . . . .
| 12.3 DECBC – Manage data event control blocks . . . . . . . . . . . . . . . . . . . . . . .
12.4 DETAC – Detach a storage block . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
| 12.5 FAC8C – Compute an online 8-byte file address . . . . . . . . . . . . . . . . . . . .
| 12.6 FA4X4C – Convert a file address . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.7 FILEC – Write a DASD record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.8 FILNC – Write a DASD record and retain the attached storage block . . . . . . . .
12.9 FILSC – Write a single copy of a DASD record . . . . . . . . . . . . . . . . . . . .
12.10 FILUC – Write a DASD record and unhold the file address . . . . . . . . . . . . .
12.11 FINDC – Read a DASD record . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.12 FINHC – Read a DASD record and hold the file address . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
12.13 FINSC – Read a single copy of a DASD record
12.14 FINWC – Read a DASD record and wait for I/O completion . . . . . . . . . . . . .
12.15 FIWHC – Read a DASD record, hold the file address, and wait for I/O completion
12.16 FNDPC – Read a DASD record with control fields . . . . . . . . . . . . . . . . . . .
12.17 GDSNC – Open or close a general data set . . . . . . . . . . . . . . . . . . . . . .
12.18 GDSRC – Compute a general data set record file address . . . . . . . . . . . . . .
12.19 GETCC – Get a storage block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.20 GETFC – Get a pool-file record address . . . . . . . . . . . . . . . . . . . . . . . .
12.21 HLDTC – Test if file address is held . . . . . . . . . . . . . . . . . . . . . . . . . . .
| 12.22 IDECB – Data event control block DSECT . . . . . . . . . . . . . . . . . . . . . . .
| 12.23 IFAC8 – FAC8C parameter block DSECT . . . . . . . . . . . . . . . . . . . . . . .
12.24 LEVTA – Test a storage level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.25 LISTC – Generate a storage list for SNAPC or SERRC . . . . . . . . . . . . . . . . .
12.26 RCRFC – Release a pool-file record address and storage block
. . . . . . . . . .
12.27 RCUNC – Release a storage block and unhold a file address . . . . . . . . . . . .
12.28 RELCC – Release a storage block . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.29 RELFC – Release a pool-file record address
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
Contents
176
182
183
184
186
187
190
191
192
193
194
195
196
199
200
203
204
204
209
243
245
246
249
250
252
254
257
259
261
263
265
267
269
271
274
277
279
281
284
287
291
293
297
301
303
304
305
307
309
311
313
315
v
12.30 SONIC – Get symbolic file address information
12.31 UNFRC – Unhold a file address . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 13. Summary of ALCS macros and callable services .
13.1 Explanatory notes . . . . . . . . . . . . . . . . . . . . . . . . . .
13.2 Using and defining macros . . . . . . . . . . . . . . . . . . . . .
13.3 List of macros and callable services intended for customer use
13.4 Macro group names . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 14. ALCS C programming conventions and facilities
14.1 C language compatibility . . . . . . . . . . . . . . . . . . . .
14.2 Structure of C programs . . . . . . . . . . . . . . . . . . . .
14.3 Function names . . . . . . . . . . . . . . . . . . . . . . . . .
14.4 Requirements for reentrant programs . . . . . . . . . . . . .
14.5 Defining structures
. . . . . . . . . . . . . . . . . . . . . . .
14.6 Time and date functions . . . . . . . . . . . . . . . . . . . .
14.7 Input message formats . . . . . . . . . . . . . . . . . . . . .
14.8 Routing of messages . . . . . . . . . . . . . . . . . . . . . .
14.9 ALCS header files . . . . . . . . . . . . . . . . . . . . . . . .
14.10 <c$amsg.h> . . . . . . . . . . . . . . . . . . . . . . . . . .
14.11 <c$cm1cm.h> . . . . . . . . . . . . . . . . . . . . . . . . . .
14.12 <c$coic.h> . . . . . . . . . . . . . . . . . . . . . . . . . .
| 14.13 <c$decb.h> . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.14 <c$ebeb.h> . . . . . . . . . . . . . . . . . . . . . . . . . .
14.15 <c$globz.h> . . . . . . . . . . . . . . . . . . . . . . . . . .
14.16 <c$rcpl.h> . . . . . . . . . . . . . . . . . . . . . . . . . .
14.17 <c$stdhd.h> . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.18 <tpfapi.h> . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.19 <tpfeq.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.20 <tpfglbl.h>
. . . . . . . . . . . . . . . . . . . . . . . . . .
| 14.21 <tpfio.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.22 <tpftape.h>
. . . . . . . . . . . . . . . . . . . . . . . . . .
|
|
|
|
|
|
|
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
Chapter 15. ALCS API functions — reference . . . . . . . . . . . .
15.2 Common parameters . . . . . . . . . . . . . . . . . . . . . . . . .
15.3 attac_ext — Attach a previously detached storage block . . . .
15.4 attac_id — Attach a previously detached storage block . . . . .
15.5 crusa — Release storage blocks from specified levels . . . . . .
15.6 detac_ext — Detach a storage block . . . . . . . . . . . . . . . .
15.7 detac_id — Detach a storage block
. . . . . . . . . . . . . . . .
15.8 file_record_ext — Write a DASD record, with extended options
15.9 find_record_ext — Read a DASD record, with extended options
15.10 gdsnc — Open or close a general data set . . . . . . . . . . . .
15.11 gdsrc — Compute the file address of a general data set record
15.12 getcc — Get a storage block . . . . . . . . . . . . . . . . . . . .
15.13 getfc — Get a pool-file record address . . . . . . . . . . . . . .
15.14 getfc_alt — Get a pool-file record address . . . . . . . . . . .
15.15 levtest — Test a storage level . . . . . . . . . . . . . . . . . .
15.16 rcunc — Release a storage block and unhold a file address
.
15.17 relcc — Release a storage block . . . . . . . . . . . . . . . . .
15.18 relfc — Release a pool-file record address . . . . . . . . . . .
15.19 sonic — Get symbolic file address information
. . . . . . . . .
15.20 tpf_decb_create — Create a data event control block . . . . .
15.21 tpf_decb_locate — Locate a data event control block . . . . .
vi
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
317
319
322
322
324
325
331
332
332
332
333
334
336
337
337
337
338
338
339
340
342
342
342
342
345
346
347
349
349
350
351
351
353
355
357
359
361
363
366
370
373
375
378
381
383
385
387
389
391
394
396
|
|
|
|
|
|
|
15.22
15.23
15.24
15.25
15.26
15.27
15.28
tpf_decb_release — Release a data event control block
. . . . . . . . . . . . .
tpf_decb_swapblk — Swap a storage block between an ECB level and a DECB
tpf_decb_validate — Validate a data event control block . . . . . . . . . . . . .
tpf_fac8c — Compute an online 8-byte file address . . . . . . . . . . . . . . . .
tpf_fa4x4c — Convert a file address . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . .
tpf_rcrfc — Release a pool-file address and storage block
unfrc_ext — Unhold a file address, with extended options . . . . . . . . . . . .
. . . . . . . .
398
400
402
404
406
408
410
. . . . . . . . . . . . . .
412
Chapter 17. Customizing ALCS . . . . . . . . . . .
17.1 ALCS services for installation-wide monitor exits
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
422
422
Chapter 18. System error codes: 000000–000FFF
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
435
Chapter 16. C library functions available under ISO-C, ALCS, and TPF
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . . . . . . . . . . . .
439
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
440
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
446
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
465
Chapter 19. Responses to ALCS commands: DXC8000–DXC8999
Appendix A. Acronyms and abbreviations
Glossary
Index
. . . . . . . .
. . . . . . . .
Contents
vii
Figures
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
| 15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
viii
Input message processing: ALCS checks the routing for a message . . . . . . . . . . . . . . . . . 1
Example of routing for an airline application system . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Data gathering transactions: The application stores a message and discards the ECB . . . . . . 3
Data gathering transactions: The application stores each intermediate message and discards each
ECB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
The ALCS terminal hold facility
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
Scrolling moves a screen-sized window over a large response message . . . . . . . . . . . . . . 5
Output message processing: ALCS translates the EBCDIC data to the line code and passes it to
VTAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Output message processing: ALCS translates the EBCDIC data to the line code and adds it to an
SLC queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
VSAM control interval format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
ALCS record in a VSAM control interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Storage block sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Some entry-control-block areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Installation-wide ECB user fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
ECB levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
DECB level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
ALCS DASD files: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Where to find more information about ALCS direct-access file management . . . . . . . . . . . . 15
ALCS direct-access files: Fixed files
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
ALCS direct-access files: Standard forward chains . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
ALCS direct-access files: Backward chains
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
ALCS direct-access files: Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
ALCS direct-access files: Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
ALCS file address: Compressing the class, type, and ordinal . . . . . . . . . . . . . . . . . . . . . 24
ALCS file address formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
File address: Different formats for TPF and ALCS . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Allocatable pool: Initial allocation
Allocatable pool: Dispensing from LT-pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Allocatable pool: After some fixed files are deleted (and purged) . . . . . . . . . . . . . . . . . . . 28
. . . . . . . . . . . . . . . . . . . . . . . . . 29
Allocatable pool: After changing to type-2 dispensing
Allocatable pool: Records in use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Allocatable pool: Using and reusing allocatable pool . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Algorithm file addressing: Class, type, and ordinal to data set and RBA . . . . . . . . . . . . . . . 30
Table-based file addressing: Class, type, and ordinal to data set and RBA . . . . . . . . . . . . . 31
Record header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Virtual file access (VFA) overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Test database: Read a record from the test database . . . . . . . . . . . . . . . . . . . . . . . . . 36
Test database: Write a record to the test data set
. . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Test database: Read and write on the test data set
. . . . . . . . . . . . . . . . . . . . . . . . . . 37
Test database: Shared testdata base, separate test data sets . . . . . . . . . . . . . . . . . . . . 38
Test database: Copy record to test data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Test database: Incorrect overflow file address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Entry dispatcher work list (schematic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Passing data between entries: parameter areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Passing data between entries: storage blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Multiple entries: create-type services in loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Protected storage locations and characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Unprotected storage locations and characteristics
. . . . . . . . . . . . . . . . . . . . . . . . . . . 55
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
| 64.
65.
66.
67.
68.
|
|
|
|
|
|
|
|
|
|
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.
99.
Entry storage: Prime and overflow storage units
. . . . . . . . . . . . . . . . . . . . . . . . . . .
ALCS operating environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Agent presses the ENTER key to send a message . . . . . . . . . . . . . . . . . . . . . . . . . .
ALCS creates an ECB for the message
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ALCS selects a program for the ECB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Program requests data from a DASD record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Program receives data from a DASD record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Program transfers control to another program . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ALCS sends a message to the terminal
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Block sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fixed file ordinals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
Fixed-file record containing a file address of a single pool-file record
Fixed-file record addressing a chain of pool-file records . . . . . . . . . . . . . . . . . . . . . . .
Example ALCS applications and their constituent programs . . . . . . . . . . . . . . . . . . . . .
Standard record header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents of an ECB data level before a DASD read request . . . . . . . . . . . . . . . . . . . .
Data level and storage level after a successful DASD read . . . . . . . . . . . . . . . . . . . . .
Data level and storage level before a DASD write request . . . . . . . . . . . . . . . . . . . . . .
Reading DASD records without holding the file address - updates performed by either entry can
be lost.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading DASD records and holding the file address – updates performed by either entry are
recorded. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ALCS services for processing DASD records . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Two entries accessing the same general sequential file . . . . . . . . . . . . . . . . . . . . . . .
Macros and functions for processing sequential files . . . . . . . . . . . . . . . . . . . . . . . . .
ALCS global area directory – logical view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing headers to create a logical global record
. . . . . . . . . . . . . . . . . . . . . . . . .
TPF global areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ALCS global areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating global area fields in TPF-compatible programs . . . . . . . . . . . . . . . . . . . . . . .
An SQL UPDATE statement — assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
An SQL UPDATE statement — C language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a new structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating a new structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Format of the ALCS ECB (schematic)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Names of work area fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Names of local program work area fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Labels for the general register save area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the general register save area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Labels for the floating-point register save area
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the floating-point register save area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Detaching and attaching a storage block – assembler . . . . . . . . . . . . . . . . . . . . . . . .
Detaching and attaching a storage block – C language . . . . . . . . . . . . . . . . . . . . . . .
Format of the ALCS DECB application area (schematic) . . . . . . . . . . . . . . . . . . . . . . .
Allocating a DECB – assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Allocating a DECB – C++ language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Computing an 8-byte file address – assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Computing an 8-byte file address – C++ language . . . . . . . . . . . . . . . . . . . . . . . . . .
Requesting a FIND-type service using a DECB – assembler . . . . . . . . . . . . . . . . . . . .
Requesting a FIND-type service using a DECB – C++ language . . . . . . . . . . . . . . . . . .
Creating a new DECB – assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a new DECB – C++ language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locating a DECB – assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
58
67
69
70
70
71
72
72
73
74
74
76
77
78
81
83
85
86
86
.
87
.
88
98
100
101
102
103
108
108
109
111
111
119
120
124
125
126
129
129
129
130
135
135
137
142
142
142
143
143
143
143
143
144
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Figures
ix
|
|
|
|
|
|
|
100.
101.
102.
103.
104.
105.
106.
107.
108.
109.
110.
111.
112.
113.
114.
115.
116.
117.
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
128.
129.
130.
| 131.
| 132.
133.
134.
135.
136.
137.
138.
139.
140.
141.
142.
143.
144.
145.
146.
147.
148.
149.
150.
151.
152.
153.
x
Locating a DECB – C++ language . . . . . . . . . . . . . . . . .
Requesting a FILE-type service using a DECB – assembler
.
Requesting a FILE-type service using a DECB – C++ language
Releasing a DECB – assembler . . . . . . . . . . . . . . . . . .
Releasing a DECB – C++ language . . . . . . . . . . . . . . . .
.
Requesting a FILE-type service using a DECB – assembler
Requesting a FILE-type service using a DECB – C++ language
Read using an implied-wait service . . . . . . . . . . . . . . . .
Wait after a required-wait read service . . . . . . . . . . . . . .
Multiple reads followed by an implied-wait read . . . . . . . . .
Summary of ALCS I/O services . . . . . . . . . . . . . . . . . .
Reporting of I/O errors with ALCS service . . . . . . . . . . . .
Error indicators in the ECB . . . . . . . . . . . . . . . . . . . . .
Symbols for error conditions . . . . . . . . . . . . . . . . . . . .
Read two DASD records and test for errors – assembler . . .
Read two DASD records and test for errors – C language . . .
Multiple implied-wait services
. . . . . . . . . . . . . . . . . . .
Processing multiple I/O errors – C language . . . . . . . . . . .
Test for sequential file errors – C language . . . . . . . . . . .
Test for several sequential file errors – assembler program . .
Test for several sequential file errors – C language . . . . . . .
Tracing to the ALCS diagnostic file: The D= parameter
. . . .
Tracing to an ALCS terminal: The D= parameter . . . . . . . .
Standard system error dump format (with offsets) . . . . . . . .
Standard system error dump format (with tags) . . . . . . . . .
Examples of system error dump header . . . . . . . . . . . . .
Example of a general register dump
. . . . . . . . . . . . . . .
Example of an area addressed by PSW dump
. . . . . . . . .
Example of areas addressed by general registers dump . . . .
Example of a storage unit block list descriptor dump . . . . . .
Example of an entry control block descriptor dump . . . . . . .
Example of a DECB descriptor dump . . . . . . . . . . . . . . .
Example of a DECB application areas dump
. . . . . . . . . .
. . . . . . . . .
Example of an entry control block prefix dump
Example of an entry macro trace block dump . . . . . . . . . .
Example of an entry control block dump . . . . . . . . . . . . .
Example of an entry control block dump . . . . . . . . . . . . .
. . . . . . . . . .
Example of an attached storage block dump
Example of an application program dump . . . . . . . . . . . .
Example of a system diagnostic work area dump . . . . . . . .
Example of a system macro trace block dump
. . . . . . . . .
Example of a monitor keypoint record (CTKB) dump . . . . . .
Example of a resource hold table dump . . . . . . . . . . . . .
Example of a CRET table dump . . . . . . . . . . . . . . . . . .
Example of a macro trace control area dump . . . . . . . . . .
Example of a program control tables dump
. . . . . . . . . . .
Example of a pool file control tables dump . . . . . . . . . . . .
Example of an ALCS entry dispatcher work lists dump . . . . .
Example of a block list descriptors dump . . . . . . . . . . . . .
Example of an I/O control block dump . . . . . . . . . . . . . .
Example of a monitor interface area dump . . . . . . . . . . . .
Example of a monitor work areas dump . . . . . . . . . . . . .
Example of an application global area dump . . . . . . . . . . .
Example of an entry storage dump . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
144
144
144
144
144
145
145
148
149
149
150
150
152
153
154
155
155
156
156
157
158
166
173
219
219
220
222
222
222
222
223
223
224
224
224
225
225
226
226
227
227
228
228
229
229
230
230
231
231
232
232
233
233
234
154.
155.
156.
157.
158.
159.
160.
161.
162.
163.
164.
165.
166.
167.
168.
169.
170.
171.
| 172.
| 173.
| 174.
175.
Example of a VFA control areas dump . . . . . . . . . . . . . . . . . . . .
Example of a VFA buffer headers dump . . . . . . . . . . . . . . . . . . .
Example of an SLC link and channel keypoint dump . . . . . . . . . . . .
ISPF panel: ALCS Primary Menu . . . . . . . . . . . . . . . . . . . . . . .
ISPF panel: Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
Opening a general data set
ALCS macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Macro group names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calls between programs in the same load module . . . . . . . . . . . . .
Default alignments of fields in structures . . . . . . . . . . . . . . . . . . .
Comparison of C library functions available under ISO-C, ALCS, and TPF
Callable service linkage conventions . . . . . . . . . . . . . . . . . . . . .
Example: UCNTINC incrementing the system counter . . . . . . . . . . .
Example usage of UCOMCHG . . . . . . . . . . . . . . . . . . . . . . . . .
Example: UCOMGET using a CRI . . . . . . . . . . . . . . . . . . . . . . .
Example: UCOMGET using a CRN . . . . . . . . . . . . . . . . . . . . . .
Example: UCOMGET using an LEID . . . . . . . . . . . . . . . . . . . . .
Example: UCOMGET for an SLC terminal . . . . . . . . . . . . . . . . . .
Example: UDLEVGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: UDLEVREL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: UDLEVVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: UDISP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
Figures
235
236
236
247
247
289
325
331
333
336
412
428
429
429
430
430
431
432
433
433
433
434
xi
Introduction
This book contains the main sections of the ALCS documentation that have changed as a consequence of
issuing PTF UQ66601 (APAR AQ54564), the ALCS DECB support.
There is sufficient here to enable you to use DECBs should you wish to do so. However, the content of
this book will eventually be added to the various ALCS publications along with some minor changes not
significant enough to be included here.
The Chapters included are
5 Concepts and Facilities
Chapter
Chapter
Chapter
Chapter
Chapter
1
2
3
4
5
ALCS Version 2 concepts and facilities (Chapter 1)
ALCS database file management (Chapter 4)
Entry management (Chapter 6)
Storage management (Chapter 7)
ALCS services (Appendix D)
5 Application Programming Guide
Chapter
Chapter
Chapter
Chapter
6
7
8
9
Overview of ALCS (Chapter 1)
Data in ALCS (Chapter 3)
The entry control block (ECB) and other entry storage (Chapter 4)
Error conditions and error processing (Chapter 6)
5 Operations and Maintenance
Chapter 10 Using the ALCS trace facility (Chapter 4)
Chapter 11 Maintaining ALCS (Chapter 5)
5 Application Programming Reference - Assembler
Chapter 12 Macros and callable services (Chapter 2)
Chapter 13 Summary of ALCS macros and callable services (Appendix A)
5 Application Programming Reference - C
Chapter 14 ALCS C programming conventions and facilities (Chapter 1)
Chapter 15 ALCS API functions - reference (Chapter 2)
Chapter 16 C library functions available under ISO-C, ALCS, and TPF (Appendix A)
5 Installation and Customization
Chapter 17 Customizing ALCS (Chapter 6)
5 Messages and Codes
Chapter 18 Responses to ALCS commands: DXC8000–DXC8999 (Chapter 9)
Chapter 19 System error codes: 000000–000FFF (Chapter 10)
xii
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
General description
Chapter 1. ALCS Version 2 concepts and facilities
1.1.1 Application program processing
Input message routing
When ALCS receives an input message, it creates a new entry to process the message. Then the ALCS
router passes control to an application program called an input-message editor. There is an
input-message editor for each application, but they do not have to be unique; several applications can use
the same input-message editor.
The ALCS router checks whether there is input routing for the terminal. If there is, it routes the input
message to the corresponding input message editor. If there is not, it routes the input message to the
ALCS command processor.
Input-message
editors
┌──────────────┐
┌───────────────┐ ┌────────┐ ┌;│ Application │
A─;│ Communication │ │
├─┘ │ for A
│
B─;│ Input
├;│ Router │
└──────────────┘
C─;│
│ │
├─┐ ┌──────────────┐
└───────────────┘ └────┬───┘ └;│ Application │
│
│ for B
│
│
└──────────────┘
│
│
┌──────────────┐
└──────;│ ALCS Command │ ALCS routes the message
│ Processor
│ to here if no input
└──────────────┘ routing is found.
Figure 1. Input message processing: ALCS checks the routing for a message
The input-message routing for a terminal can be specified by:
5 The COMDEF macro in the ALCS communication generation
5 The ZROUT command
5 The ZACOM command
Using program function (PF) keys to enter messages
If a terminal has program function (PF) keys, you can use these to enter messages. ALCS automatically
converts the resulting input into normal input messages or commands.
ALCS provides standard conversion for PF keys (which is the same as ALCS/MVS/XA). You can provide
an installation-wide exit to override these PF key settings, for example to adhere to IBM's Common User
Access* (CUA)* recommendations. ALCS Installation and Customization describes the ALCS
installation-wide exits.
Also, end users can use the ZAKEY command to customize their own PF key settings. This is described in
ALCS Operation and Maintenance.
Input messages beginning with Z
ALCS normally assumes that any input message starting with Z is an ALCS command (or possibly a user
command added using an installation-wide exit) and passes the message directly to the ALCS command
processor.
You can override this default processing if your application expects some input messages to begin with
Chapter 1. ALCS Version 2 concepts and facilities
1
General description
Z. For example, a check-in application might require a passenger name as an input message. If you do
this, your application input-message editor must identify messages that really are ALCS commands and
pass them on to the ALCS command processor (otherwise the end user will not be able to use the ALCS
commands).
Figure 2 shows a possible routing arrangement for an airline application system. The system has two
applications, reservations and message switching. Each application has its own input-message editor.
Input-message
Output message
editors
editors
┌──────────────┐
┌──────────────┐
┌───────────────┬────────┐ ┌;│ Message
│── ─ ─ ─ ─ ;│ Message
├─┐
A─;│ Communication │
├─┘ │ Switching
│
│ Switching
│ │
B─;│ Input
│ Router │
└──────────────┘
└──────────────┘ │
┌────────┬───────────────┐
C─;│
│
├─┐ ┌──────────────┐
┌──────────────┐ └─────;│
│ Communication ├; A
└───────────────┴────┬───┘ └;│ Reservations │── ─ ─ ─ ─ ;│ Reservations ├───────;│ Router │ Output
├; B
│
│
│
│
│ ┌─────;│
│
├; C
│
└─────┬────────┘
└──────────────┘ │
└────────┴───────────────┘
│
D
│
│
┌─────── ──────┐
┌──────────────┐ │
└──────;│ ALCS Command │── ─ ─ ─ ─ ;│ ALCS Command ├─┘
│ Processor
│
│ Processor
│
└──────────────┘
└──────────────┘
Figure 2. Example of routing for an airline application system
Note that in Figure 2 there is a connection from the reservations input-message editor to the ALCS
command processor. That is because the reservations input-message editor accepts input messages that
begin with the character Z. The reservations input-message editor checks these input messages to see
whether they are ALCS commands. If they are commands it enters (passes control to) the ALCS
command processor.
This checking process is one example of the type of processing that an input-message editor can perform.
Input messages — general processing
In general, the input-message editor decides how to process the input message. To do this it can:
5 Check the address of the originating terminal. If it is not authorized to use the application, the
input-message editor can reject the input message, in which case it must send a response to the
originator. The input-message editor can enter an output-message editor to do this.
5 Check the type of the originating terminal. The input-message editor can carry out message editing
that depends on the originating terminal type. For example, International Programmed Airlines
Reservation System (IPARS) input messages from WTTY terminals do not use the same format as
input messages from IBM 3270 terminals.
5 Check the input message to see what function the message requests. One application can support a
number of different functions. Different input messages can request different functions. For example,
the IPARS reservations application supports functions such as:
– Display flights to a destination at a specific time
– Reserve seats on a flight
– List the passengers who have reservations on a flight
The IPARS input-message editor uses the first 1 or 2 characters of the input message to identify the
function that the message requests. These are called the primary action code and the secondary
action code respectively.
5 Check that the end user terminal is authorized to request the function.
ALCS checks that the terminal is authorized to use ALCS.
2
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
General description
End users may have to satisfy additional authorization requirements before they can use certain
applications, or particular functions of an application. The application can conveniently perform this
authorization checking during input-message editing.
When the input-message edit processing completes, the input-message editor enters the application
program that starts to process the input message. Typically the input-message editor decides which
application program to enter, depending on the function that the input message requests.
Processing continues through one or more application programs. For most terminals, the application
programs must send a response message to the originating terminal. To do this, the application programs
construct the response message, and finally enter the output-message editor.
Data gathering transactions
ALCS creates a new entry to process each input message. However, some applications require several
physical input messages to perform a single logical function. For example, the IPARS reservations
application builds a record called a passenger name record (PNR) that contains information about a
passenger. The end user enters separate input messages for separate pieces of information about the
passenger. One message can specify the passenger's name, another the passenger's telephone number,
and so on.
This type of processing, where consecutive input messages from the same terminal operate together to
perform a single logical function, is called a data gathering transaction.
Because each input message is a separate entry, the entries must save information about the partially
complete data gathering transaction. Each entry saves more information until all the data is available.
The final input message of the data gathering transaction checks that all the information is available, and
that it is consistent.
The IPARS agents assembly area
One way to implement data-gathering transactions is to use fixed-file records to save information about
partially completed transactions. For example, IPARS uses a fixed-file record called the agents assembly
area (AAA). Figure 3 and Figure 4 on page 4 show how a record is built from separate input messages.
ECB
┌──────────┐
│
D────────────────────;┌───────────────────┐ Storage Block
│
D1──────────┐
│ Intermediate
│
│ RCPL
│
│
│ message data
│
│
CRI │
│
└─────────┬─────────┘
└──────────┘
│
│
└─────────;┌─────────D─────────┐ Record used to collect the information
│ Name nnnnnnnnnnnn │ (One AAA record for each terminal)
│ Addr1
│
│ Addr2
│
│ Tele
│
└───────────────────┘
Figure 3. Data gathering transactions: The application stores a message and discards the ECB
Chapter 1. ALCS Version 2 concepts and facilities
3
General description
ECB
┌──────────┐
│
D────────────────────;┌───────────────────┐ Storage Block
│
D1──────────┐
│ Intermediate
│
│ RCPL
│
│
│ message data
│
│
CRI │
│
└─────────┬─────────┘
└──────────┘
│
│
└─────────;┌─────────D─────────┐ Record used to collect the information
│ Name nnnnnnnnnnn │ (One AAA record for each terminal)
│ Addr1 aaaaaaaaaaa │
│ Addr2 aaaaaaaa
│
│ Tele ttttttt
│
└───────────────────┘
Figure 4. Data gathering transactions: The application stores each intermediate message and discards each ECB
IPARS allocates one AAA record for each terminal. The fixed-file record ordinal number is directly
associated with a terminal ordinal number (communication resource ordinal).
The ALCS terminal hold facility
Some types of terminal can enter another input message before they receive the response to a previous
message. If the application uses a fixed-file record to save information about partially completed
transactions, two input messages can update the record at the same time. To prevent this, the application
can use the record hold facility. However, the record should not be held for the duration of a whole input
message. To avoid this, the application can use the ALCS terminal hold facility (also called AAA hold).
To use the terminal hold facility, the input-message editor sets terminal hold on and the output-message
editor sets it off. They use the COMCC monitor-request macro (or the comcc C language function) to set
terminal hold on and off.
Output-message
editor
┌─── Input-message editor ───┐
┌────────────┐
┌───────────────┬────────┐ ┌─────────────┐ ┌───────────┐ ┌────────────┐ │ Send reply │ ┌────────┬───────────────┐
A─;│ Communication │
│ │ Terminal
│No│ Use COMCC │ │ Update AAA │ │ Use COMCC │ │
│ Communication │
B─;│ Input
│ Router ├─;│ held?
├──┤ to hold
├─┤ record
├─┤ to release ├;│ Router │ Output
├;A
C─;│
│
│ │ (use COMIC) │ │ terminal │ │
│ │ terminal
│ │
│
│
└───────────────┴────────┘ └──────┬──────┘ └───────────┘ └────────────┘ └────────────┘ └────────┴───────────────┘
D Yes
┌────────────────┐
│ Ignore message │
└────────────────┘
Figure 5. The ALCS terminal hold facility
Before the input-message editor sets terminal hold on, it checks (with the COMIC monitor-request macro or
comic C language function) to see whether it is already on. If terminal hold is already on, the application
is still processing a previous input message; the input-message editor ignores the second input message
(it does not even send a reply).
Output message processing by application programs
After the application programs construct the response message, they enter an output-message editor. As
with input-message editors, each application can have its own output-message editor, or several
applications can use the same output-message editor.
Figure 2 on page 2 shows a possible routing arrangement for an airline application system. The system
has two applications, reservations and message switching. Each application has its own output-message
editor.
4
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
General description
The output-message editor eventually issues a SEND-type (SENDC or ROUTC) monitor-request macro.
These macros transmit the response to the originating terminal.
In addition to issuing these macros and functions, the output-message editor can provide functions such
as:
Canned messages: The application program does not provide the text of the message. Instead, it
provides a code that identifies a particular standard message (called a canned message) from a list of
standard messages. The output-message editor constructs and sends the response.
Scrolling ALCS allows an application to construct a response message that contains:
5 More columns than the output terminal supports
5 More lines than the output terminal supports
5 A combination of both
The output-message editor saves the whole response message (in pool records) if it cannot fit on one
screen. It then builds and sends a new output message that fits on one screen. The output-message
editor also supports ALCS commands that scroll the screen over a large message. Figure 6 shows the
effect of scrolling.
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdn fnlknvknmdfddadad
saksals,ma,adasdn fnlknvknmdfddadad
saksals,ma,adasdn fnlknvknmdfddadad
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfd
saksals,ma,adasdnfnlknvknmdfd
saksals,ma,adasdnfnlknvknmdfd
sals,ma,adasdnfnlknvknmdfddadadskvfenbv
sals,ma,adasdnfnlknvknmdfddadadskvfenbv
sals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adanlknvknmdfddadadskvfenbv
saksals,ma,adanlknvknmdfddadadskvfenbv
saksals,ma,adanlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
saksals,ma,adasdnfnlknvknmdfddadadskvfenbv
Figure 6. Scrolling moves a screen-sized window over a large response message
Some applications provide scrolling facilities, but ALCS provides a monitor service for scrolling which you
can use instead. It is implemented using the DISPC monitor-request macro and the ZSCRL command.
These are described ALCS Application Programming Reference – Assembler and ALCS Operation and
Maintenance.
1.1.2 Output message processing by the ALCS online monitor
ALCS application programs construct response messages and then call an output-message editor that
uses a SEND-type monitor-request macro to request transmission of the message.
To process one of these macros or functions, the ALCS online monitor first checks that the message is in
the standard ALCS output message format (for example, that the character count is correct, and that the
CRI in the output message or RCPL is valid).
IBM 3270 terminals on a VTAM network
The CRI determines the routing information in the format required by VTAM. The online monitor then
uses a VTAM SEND macro to transmit the message to the terminal.
Chapter 1. ALCS Version 2 concepts and facilities
5
General description
ALC terminals on a VTAM network (ALCI or AX.25)
The CRI determines the routing information in the format required by VTAM.
The online monitor translates the message text from the EBCDIC code used by ALCS applications to the
transmission code used on the high-level network (HLN).
Figure 7. Output message processing: ALCS translates the EBCDIC data to the line code and passes it to VTAM
The online monitor then uses a VTAM SEND macro to transmit the message to the local HLN switching
center, which forwards it to the remote terminal.
Terminals on an SLC high-level network
The CRI determines which SLC link is used for transmitting the message. It also determines the routing
information, as required by the HLN.
The online monitor:
5 Translates the message text from the EBCDIC code used by ALCS applications, to the transmission
code used on the high-level network.
5 Adds the message text and routing information to the output queue for the SLC link.
Figure 8. Output message processing: ALCS translates the EBCDIC data to the line code and adds it to an SLC
queue
When a channel (for this SLC link) is free, ALCS transmits the highest priority message from the queue for
this SLC link.
6
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
General description
In this way, ALCS transmits the message to the local HLN switching center, which forwards it to the
remote terminal.
1.2 Standard record and storage block sizes
ALCS supports up to eight standard sizes for records on DASD. These sizes are called L1, L2, and so
on, up to L8. ALCS supports the same standard sizes for sequential file records, plus another standard
size called L0. ALCS storage management allocates blocks of storage to entries in these same standard
sizes. Application programs can use these standard size storage blocks for reading and writing DASD
and sequential file records or for other purposes (such as for work areas).
When you define the characteristics of your ALCS installation in the ALCS generation, you specify which
of these sizes your ALCS system will support, and what the actual sizes (in bytes) are. When you are
deciding which of the nine sizes to support, and what actual sizes (in bytes) they are, you need to be
aware of:
5 How ALCS stores DASD records
5 ALCS minimum requirements
5 Application portability and TPF compatibility
1.2.1 How ALCS stores DASD records
This section describes how ALCS stores DASD records its own data sets. It does not describe how (for
example) DATABASE 2 stores its relational data base.
ALCS stores records on DASD in VSAM control intervals. Although VSAM supports a variety of control
interval formats, ALCS imposes the following restrictions:
5 The control interval size must be the same as the physical record size.
5 Each control interval must contain one and only one record.
5 Within any one cluster, all records must be the same size.
Figure 9 shows the format of a VSAM control interval. Notice that VSAM requires the control interval size
to be a multiple of 512 bytes (for large CIs, the CI size must be a multiple of 2KB). In addition to the
record itself, the VSAM control interval contains a record definition field (RDF) and a control interval
definition field (CIDF) which together occupy the last eight bytes of the control interval. (Although ALCS
does not exploit this, VSAM allows there to be unused space between the end of the VSAM logical record
and the 8-byte RDF/CIDF.)
K─────────────── VSAM control interval (CISIZE) ──────────────;
(multiples of 512)
K──────────── VSAM logical record ─────────────────; K─── 8 ──;
┌────────────────────────────────────────────────────┬──────────┐
│
│ RDF/CIDF │
└────────────────────────────────────────────────────┴──────────┘
Figure 9. VSAM control interval format
Offline programs which access ALCS general files (general data sets) read (VSAM GET) and write (VSAM
PUT) VSAM logical records. But online application programs read (find service) or write (file service)
standard size ALCS records (L1, L2, and so on). ALCS stores the standard size ALCS record at the start
of the VSAM logical record, and reserves the last 56 bytes of the VSAM logical record to contain ALCS
control information. Typically, there are some unused bytes between the end of the standard size ALCS
record and the start of the 48-byte reserved area. Figure 10 on page 8 shows this layout.
Chapter 1. ALCS Version 2 concepts and facilities
7
General description
K─────────────── VSAM control interval (CISIZE) ──────────────;
(multiples of 512)
K──────────── VSAM logical record ─────────────────; K─── 8 ──;
┌──────────────────────┬─────────┬───────────────────┬──────────┐
│ ALCS standard record │ Unused │ 48 bytes reserved │ RDF/CIDF │
└──────────────────────┴─────────┴───────────────────┴──────────┘
Figure 10. ALCS record in a VSAM control interval
For example, a 512-byte control interval contains a 504-byte VSAM logical record. Because ALCS
reserves 48 bytes, this allows a maximum of 456 bytes for the ALCS standard size record. Most ALCS
installations define size L1 as 381 bytes which leaves 75 bytes unused.
1.2.2 ALCS minimum requirements for standard sizes
All ALCS systems must support at least sizes L0, L1, L2, and L3. ALCS itself uses sizes L1, L2, and L3.
ALCS assumes that these are greater than or equal to the following minimum sizes in bytes:
L1
L2
L3
381 bytes
1055 bytes
4000 bytes
Note: You cannot change size L0, it is always 127 bytes.
1.2.3 Application portability and TPF compatibility
When you define the standard record and block sizes for your ALCS system, consider that:
5 You may want to buy applications developed to run on other systems (TPF or ALCS). These
applications may contain dependencies on the standard sizes defined on the vendor's system.
5 You may want to sell applications that you develop. It may be difficult to port your application if it
contains dependencies on standard sizes that are not defined, or are defined differently on your
customer's system.
TPF only supports sizes L0, L1, L2, and L4 for application program use, and it does not allow these sizes
to vary from installation to installation. Many applications developed for use with TPF depend on these
TPF record sizes; they might not work unless you define the sizes as follows:
L0
L1
L2
L4
127 bytes
381 bytes
1055 bytes
4095 bytes
You should also consider using these sizes for L0, L1, L2, and L4 if you plan to develop new ALCS
applications. This will make your application easier to port if you ever sell it to a TPF user, or install TPF
yourself.
Note that you can greatly enhance portability of applications that you develop by exploiting the IBM
TPFDF product. TPFDF helps you to write applications that do not contain dependencies on the actual
sizes of records that you access.
1.2.4 Recommendations and requirements for record and block sizes
Figure 11 summarizes the ALCS requirements and recommendations for standard record and block sizes.
8
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Multiprogramming and multiprocessing
Figure 11. Storage block sizes
Storage
reference
Number of bytes of
application data
Notes
L0
127
Fixed by ALCS
L1
381
Recommended for TPF compatibility
L2
1055
Recommended for TPF compatibility
L3
4000
Minimum
L4
4095
Recommended for TPF compatibility
L5
Up to 32K
As required
L6
Up to 32K
As required
L7
Up to 32K
As required
L8
Up to 32K
As required
TPF compatibility
If your application program must be compatible with TPF, do not use sizes L3 and L5–L8 explicitly.
You can, however, use these sizes through the IBM TPFDF program. TPFDF allows you to use any
record size (decided by the database administrator) without explicitly specifying the size in your
application programs.
1.2.5 Sequential file records
ALCS provides services that allow application programs to read and write standard size sequential file
records (L0, L1, and so on). Sequential file records are stored in conventional record formats, without
additional ALCS or VSAM control information.
ALCS also provides services that allow application programs to read and write arbitrary size sequential file
records.
1.3 Multiprogramming and multiprocessing
Entries: An input message is an example of an ALCS entry. An entry is a unit of work, similar to an
MVS task. ALCS can process entries independently of each other. It can use:
Multiprogramming
Interleaves the processing of several entries on the same processor
If an application program that is processing one entry waits (for example, for I/O), ALCS can
start or resume processing another entry. In this way, ALCS can interleave the processing of
several entries on the same processor.
Multiprocessing
Processes several entries at the same time on different processors
If ALCS runs on a multiprocessor it can process entries simultaneously on different processors.
For example, on a four-way multiprocessor, ALCS can process four entries simultaneously.
Relationship between entries and tasks: ALCS does not ATTACH a new MVS task for each entry.
Several ALCS entries can run under the same MVS task. To process entries, ALCS ATTACHes one or
more MVS tasks during ALCS initialization. The number of tasks is a run-time option; it determines the
Chapter 1. ALCS Version 2 concepts and facilities
9
Multiprogramming and multiprocessing
number of processors that ALCS can use to process entries (each task can run on a separate processor).
Each of these tasks can start or resume processing of any entry. One entry can start processing under
one task, wait, then resume under another task.
1.3.1 Re-entrant application programs
One ALCS application program often processes more than one entry. For example, several end users
can request a time display at the same time. Each request (input message) is a separate entry, but there
is only one program that generates the time display response (output message).
If one application program processes several entries, ALCS uses the same copy of the program for all
entries. Because of this, ALCS application programs must be reentrant. A reentrant program does not
modify itself; for example, it does not contain work areas or switches that it modifies during execution.
If an ALCS application program is not reentrant, it can fail unpredictably. ALCS terminates any application
program that attempts to modify itself.
1.3.2 Entry control block
Because application programs must be reentrant, they cannot use internal data areas and switches.
Instead, they must use storage that is associated with an entry, not with a program. ALCS provides an
area of storage for each entry. This storage area is called the entry control block (ECB). The ALCS
online monitor creates a new ECB for each new entry.
Figure 12 on page 11 shows the ECB format. The figure shows some assembler symbols such as:
5 EBW000 (in a user work area)
5 CE1FA0 (a storage level)
5 EBROUT (an entry-origin field)
For assembler programs, the ALCS EBEB macro generates the EB0EB DSECT that defines these labels.
Similarly for C-language programs, the c$ebeb header file generates the ebeb struct that defines the
labels.
Note: The $ character is the national currency symbol (X'B5').
Other high-level language programs (for example COBOL) do not have direct access to the ECB.
10
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Multiprogramming and multiprocessing
:
:
:
:
├──────────────────────────────────────────────────────────────────────┤
│ ECB work area 1 (EBW─EBW13)
│
│
┌───────────────────────────────────┤
│
│ Work area 1 switch bytes
│
├──────────────────────────────────┴───────────────────────────────────┤
:
:
├──────────────────────────────────────────────────────────────────────┤
│ Entry origin fields (CE1EID, CE1FLG, EBROUT, CE1TRC, and so on)
│
├──────────────────────────────────────────────────────────────────────┤
:
:
:
:
│ User save area for general registers 14,15,-7 (CE1URA─CE1UR7)
│
├──────────────────────────────────────────────────────────────────────┤
│ ECB work area 2 (EBX─EBX13)
│
│
┌───────────────────────────────────┤
│
│ Work area 2 switch bytes
│
├──────────────────────────────────┴───────────────────────────────────┤
:
:
├──────────────────────────────────────────────────────────────────────┤
│ ECB local program work area (EBL─EBL13)
│
│
┌───────────────────────────────────┤
│
│ LPW switch bytes
│
├──────────────────────────────────┴───────────────────────────────────┤
:
:
├──────────────────────────────────────────────────────────────────────┤
│ Routing control parameter list area (CE1RCPL)
│
├──────────────────────────────────────────────────────────────────────┤
:
:
:
:
└──────────────────────────────────────────────────────────────────────┘
Figure 12. Some entry-control-block areas
An application program can safely store information about a particular message in the ECB. Information
about another message does not overwrite it because each message is a separate entry and has its own
ECB.
User-defined ECB fields
ALCS application programs can use the ECB work areas for any purpose. The areas are:
5 Work area 1 (EBW000 through EBW103) and its switch bytes
5 Work area 2 (EBX000 through EBX103) and its switch bytes
Programs typically use these areas for intermediate results, for passing parameters between programs,
and so on.
ALCS also provides a local program work area (EBL000 through EBL103 and its switch bytes) which is
“local” to the program. It is cleared to binary zeros on entry to the program and the contents are
saved/restored across enter/back.
TPF compatibility
Do not use the local program work area in programs that must be compatible with TPF
Note: ALCS does not provide local program work area support for C language programs.
However, unrelated programs (programs which do not call each other) can, and often do, use ECB work
area fields for different purposes. Therefore, fields defined within the ECB work areas are usually specific
to a particular program or group of programs.
ALCS provides a special area (CE1USA) in the ECB, where the system programmer can define fields
which are installation-wide.
Chapter 1. ALCS Version 2 concepts and facilities
11
Multiprogramming and multiprocessing
:
:
│ ECB work area 2 (EBX─EBX13)
│
│
┌───────────────────────────────────┤
│
│ Work area 2 switch bytes
│
:
└───────────────────────────────────┤
:
:
├──────────────────────────────────────────────────────────────────────┤
│ User area reserved for installation-wide fields (CE1USA)
│
├──────────────────────────────────────────────────────────────────────┤
:
:
Figure 13. Installation-wide ECB user fields
Installation-wide fields can contain the same information for all entries, regardless of which application
programs are using the ECB.
ECB levels and attached storage blocks
Application programs that read or write records do not use the ECB to store the records. Instead, they
use additional storage called storage blocks. Application programs can also use storage blocks for work
areas if they need more storage than the ECB itself.
Storage levels
To obtain a storage block, an application program uses a monitor-request macro or C language function.
The monitor-request macro specifies an ECB field called a storage level. The ALCS ECB contains 16
storage levels for application program use. The monitor-request macro obtains a storage block and
attaches the block to the storage level; that is, it saves information such as the block address and block
size in the storage level.
:
:
├──────────────────────────────────────────────────────────────────────┤
│ ECB work area 1 (EBW─EBW13)
│
│
┌───────────────────────────────────┤
│
│ Work area 1 switch bytes
│
├──────────────────────────────────┴───────────────────────────────────┤
:
:
├──────────────────────────────────────────────────────────────────────┤
│ Data levels (CE1FA-CE1FAF)
│
├──────────────────────────────────────────────────────────────────────┤
:
:
├──────────────────────────────────────────────────────────────────────┤
│ Storage levels (CE1CR─CE1CRF)
│
├──────────────────────────────────────────────────────────────────────┤
:
:
:
:
└──────────────────────────────────────────────────────────────────────┘
Figure 14. ECB levels
Some storage blocks can be associated with an entry but not attached to a storage level. These include:
5 Detached storage blocks
5 Automatic storage blocks
Detached storage blocks: Application programs can use the DETAC monitor-request macro (detac C
function) to detach a storage block from a storage level. They can then obtain another storage block and
attach it at that storage level. A detached storage block is still associated with the entry (application
programs can use the ATTAC (attac C function) macro to re-attach it).
Automatic storage blocks: Assembler application programs can use the ALASC monitor-request macro to
obtain an automatic storage block. An automatic storage block is associated with an entry, but it is not
attached at a storage level. The BACKC monitor-request macro releases automatic storage blocks.
See ALCS Application Programming Guide for a description of how to obtain and use storage blocks.
12
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Multiprogramming and multiprocessing
Data levels
The ALCS ECB includes 16 fields called data levels. Each data level is associated with a corresponding
storage level. Some monitor-request macros use a data level and the associated storage level. For
example, the FILEC macro writes the contents of a storage block to DASD. The storage level contains
information about the storage block and the data level contains information about where to write the
record.
|
1.3.3 Data event control blocks (DECBs)
|
|
|
|
|
A data event control block (DECB) contains a storage level and data level. An application program can
use a DECB as an alternative to using a storage level or data level in the ECB. Although a DECB does
not physically reside in an ECB, the DECB fields specify the same information as those in the ECB. An
application program can dynamically acquire a DECB by using the DECBC FUNC=CREATE monitor-request
macro (tpf_decb_create C function).
|
|
|
|
|
|
|
|
|
|
|
|
|
┌────────────────────────────────────────────────────────────────────────┐
│ DECB name: IDECNAM (idecnam)
│
├────────────────────────────────────────────────────────────────────────┤
:
:
├────────────────────────────────────────────────────────────────────────┤
│ Storage level: IDECCRW (ideccrw)
│
│
IDECDAD (idecdad), IDECCT (idecct), IDECDLH (idecdlh) │
├────────────────────────────────────────────────────────────────────────┤
│ Data level: IDECFRW (idecfrw)
│
│
IDECRID (idecrid), IDECRCC (idecrcc), IDECFA (idecfa)
│
├────────────────────────────────────────────────────────────────────────┤
:
:
└────────────────────────────────────────────────────────────────────────┘
| Figure 15. DECB level
| For Assembler programs, the ALCS IDECB macro generates the IDECB DSECT that defines the labels for
| the fields in a DECB.
| Similarly for C-language programs, the c$idecb header file generates a C data structure defined as type
| TPF_DECB that defines the labels.
| Note: The $ character is the national currency symbol (X'B5').
| See ALCS Application Programming Guide for more information on the use of DECBs.
1.3.4 Data collection area
Each ECB has an associated data-collection area.
During the life of an entry, the ALCS online monitor accumulates statistics in fields in this area. If data
collection is active, the data-collection routines write these statistics to the data-collection sequential file
when the ECB exits. If a data-collection file is not defined, ALCS writes the information to the diagnostic
file. There is an optional extension to this area which installations can use.
You can use offline programs such as:
5 The ALCS statistical report generator (SRG)
5 The Service Level Reporter (SLR).
to process the statistics and produce reports that show how entries use ALCS resources.
Chapter 1. ALCS Version 2 concepts and facilities
13
Multiprogramming and multiprocessing
1.3.5 Serialization – forcing exclusive access to resources
| Each ALCS entry has its own ECB, its own DECBs and its own attached and detached storage blocks (or
heap and stack for high-level languages), which all belong exclusively to that entry. ALCS application
programs can therefore use the storage without interference from other entries.
However, all ALCS entries can share other resources, in particular:
5 Database records
5 The application global area
5 Sequential files.
In order to allow application programs to share these resources without inadvertently overwriting their
contents, ALCS allows programs to force exclusive access to a resource while they are using it, as
follows:
5 Force exclusive access to the resource
5 Perform instructions that use the resource
5 Release the resource so that other entries can use it.
While one entry has exclusive access to a resource, ALCS queues any other entries that want to use it
until the first entry releases it.
14
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data sets
Chapter 2. ALCS database file management
This section describes the ALCS direct-access files. ALCS provides two types of direct-access file for
application use:
5 ALCS real-time database, for online transactions
5 General-file, to transfer data between the online and the offline system. Application programmers
further classify general files into:
– General file
– General data set (GDS)
Figure 16 shows the basic types of direct-access data sets that ALCS supports.
Figure 16. ALCS DASD files: Overview
ALCS uses a third type of direct access file to contain configuration information. Application programs
cannot access the configuration data set.
Figure 17 shows where you can find more information about ALCS files and data sets.
Figure 17. Where to find more information about ALCS direct-access file management
Type.
Allocatable
space
2.4, “Allocatable space overview” on page 27
Fixed files
“Fixed files” on page 17
General files
2.2, “General files and general data sets” on page 22
Pool files
“Pool files” on page 18
Configuration
data set
2.9, “The ALCS DASD configuration data set” on page 40
Chapter 2. ALCS database file management
15
Data sets
2.1 The ALCS real-time database
ALCS applications that do not need to share data with non-ALCS applications normally keep data on the
ALCS real-time database.
ALCS application programs can access real-time database records at all times. ALCS provides a number
of facilities that make the real-time database particularly suitable for transaction processing applications,
including:
5 Duplication of data to protect against DASD equipment failure (this is sometimes called mirroring).
5 Distribution of records across DASD actuators to avoid hot spots (this is sometimes called striping).
5 In-memory caching of highly accessed records (VFA).
5 Short processor pathlengths (few instructions) to access database records on DASD.
These facilities combine to provide high-speed data access with a high level of data integrity.
The real-time database consists of a number of data sets. There are one or more data sets for each
record size, and there can be up to eight record sizes (L1 through L8). The system programmers chose
these sizes when they install ALCS.
2.1.1 Organization of the database
The ALCS real-time database organization is designed to optimize DASD performance and avoid hot
spots. ALCS allows you to have multiple data sets for each record size (and record type within this
record size). Records of any one record type can reside on more than one DASD volume.
To help to balance the number of I/O operations (accesses) for any record type, ALCS spreads the
records across these data sets. This means that there will be approximately the same number of
accesses to each of the data sets for a record size.
2.1.2 Duplicated database
If you wish, you can use the dual copy facility of the IBM 3990 DASD controller to duplicate the ALCS
database (and any other data sets) as well as (or instead of) the ALCS facilities.
The ALCS duplicated database facility
ALCS optionally supports a duplicated database. The DUPLEX parameter of the DBGEN macro specifies
whether the database is duplicated.
A duplicated database has two copies of every real-time database data set, including any spill data sets.
The two copies are called copy 1 and copy 2.
A duplicated database provides some protection against the consequences of equipment failures. Without
database duplication, ALCS can execute only when all real-time database data sets are available. With
database duplication, ALCS can execute when some database data sets are not available, provided one
copy of each data set is available.
You should allocate the copy 1 and copy 2 data sets on different DASD volumes (preferably attached by
different paths) so that failure of a single hardware element does not make both copies unavailable. -Heading 'HOWDUPE' unknown -- describes this facility in more detail.
16
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data sets
2.1.3 Record classes – fixed file, short-term pool, and long-term pool
There are three different classes of records on the ALCS real-time database:
5 Fixed file
5 Short-term pool file
5 Long-term pool file
Short-term pool file and long-term pool file are sometimes referred to collectively as pool file or just pool.
Fixed files
ALCS application programs access fixed files in much the same way that any applications access
direct-access files (sometimes called random-access files).
ALCS application programs do not use data set names or file names for fixed files. Instead, they use a
special token called the:
Fixed-file record type in ALCS (the FACE ID in TPF).
To access a particular record, the application specifies the file (by type) and a relative record number.
The relative record number is called the:
Fixed-file record ordinal number in ALCS (the FACE ordinal in TPF).
Before actually reading or writing a fixed-file record, ALCS application programs use an ALCS service to
convert the fixed-file record type and ordinal into a 4-byte token called the file address. Figure 18 shows
the ALCS fixed files and file address.
Class
Fixed file
Type
# XYZAB
Figure 18. ALCS direct-access files: Fixed files
ALCS application programs cannot create or delete fixed files, and they cannot change the number of
records in a fixed file. The system programmer or database administrator makes these changes.
Miscellaneous file: One type of fixed-file record that an installation often defines is a miscellaneous
file. A miscellaneous file contains fixed-file records that can be made available to applications without
system programmer having to define a new fixed-file record type. The system programmer allocates a
range of ordinal numbers to one application and other ranges of ordinal numbers to other applications.
Chapter 2. ALCS database file management
17
Data sets
Miscellaneous files usually have names (fixed-file record type symbols) such as #MISC1, #MISC2, and so
on, where the last digit in the name indicates the record size (L1, L2, and so on).
Pool files
In addition to the fixed files, ALCS supports a number of large pools of records. ALCS application
programs cannot specify the file and the relative record number of a particular pool file record. ALCS
application programs must use an ALCS monitor service to acquire a record from one of these pools.
This service is called dispense.
The monitor service returns a file address that the application stores as a pointer in another record. For
example, an application program can use a pool-file record as an overflow record by storing its file
address in the prime record. 2.1.6, “Overflow and chaining” on page 19 describes this process.
Alternatively, 2.1.7, “Lists and indexes” on page 21 describes how an application program can store the
file address in a list or index record.
Note: It is not important to an application program which pool record ALCS allocates. It only important
that the record is not already in use for some other purpose.
Subsequently, application programs access the record using the stored file address.
When the data contained in the record is no longer needed, the application program clears the saved file
address to zeros and uses an ALCS monitor service to return the record to the available pool. This
service is called release.
Note: If the file address is saved in more than one place, the application must clear all of them.
Short-term pool file: Application programs can use short-term pool-file records to store data for short
periods of time (a few seconds or minutes).
An application must release a short-term pool record within (at most) a few hours after the dispense. If
the application does not release a short-term pool record within a reasonable time (typically 24 hours) then
ALCS assumes that there is a programming error and releases the record itself.
The actual amount of time before ALCS itself releases a short-term pool record depends on the rate at
which the short-term pool is dispensed and released.
Your system programmer or database administrator can allocate one short-term pool file for each record
size. For example, your installation may have four short-term pool files, one for each of the sizes L1, L2,
L3, and L4.
Long-term pool file: Application programs can use long-term pool-file records to store data for long
periods of time (days, weeks, or years).
Like short-term pool-file records, the application should release a long-term pool record when the
information it contains is no longer required. There is no time limit within which your application must
release a long-term pool record. A long-term pool record does not become available immediately after the
release, it is available for reuse only when the ALCS space-recovery utility (Recoup) confirms that there
are no pointers to the record saved in the ALCS database.
Your system programmer or database administrator can allocate one long-term pool file for each record
size. For example, your installation may have four long-term pool files, one for each of the sizes L1, L2,
L3, and L4.
18
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data sets
Minimum pool-file record requirement for ALCS: ALCS requires a minimum allocation of the
L3LTPOOL and L3STPOOL. ALCS Installation and Customization lists all the record requirements for
ALCS
2.1.4 Long-term pool integrity
Applications must use long-term pool-file records to store data that has a life longer than a few minutes.
ALCS protects long-term pool-file records against possible loss or damage. Such loss or damage can
arise in a number of ways as follows:
5 Equipment failure can prevent the correct update of the DASD copy of a pool file directory record. If
this happens, the directory can indicate some records as available when they are actually in use. If
ALCS dispenses these records again, the application loses the data they contain.
5 Equipment failure or program errors can result in some records never being released. Without some
method of recovering these records (lost addresses), the number of available records in the pool could
eventually reduce to zero. ALCS does not redispense these records (as it does with short-term pool
records).
5 Application program errors can result in the release of some records even though the application (or
other applications) still requires the data they contain.
2.1.5 Pool dispense rate monitor
The pool file management routines monitor the dispense rates of the long-term pools. If any dispense rate
exceeds the appropriate pool dispense rate threshold value, they send an Attention message to the RO
CRAS. You can use the ZPOOL command to review the threshold values set by ALCS and, if necessary, to
alter them; see ALCS Operation and Maintenance.
Each time ALCS calculates a long-term pool dispense rate, it also checks that there are enough available
file records in the pool to sustain the rate of dispense for at least twelve hours. If not, the pool file
management routines send a message to the RO CRAS, stating the estimated time until pool depletion.
2.1.6 Overflow and chaining
In many cases, the amount of data you want to hold in a record varies dynamically. For example, an
airline seat reservation application might keep a list of the passengers booked on each flight. This list will
grow dynamically as more and more passengers make reservations for the flight.
Standard forward chaining
To allow for this, it is usual to start building the list in one record (the prime record). When this record is
full, the application obtains an additional record (an overflow record) in which to continue the list. This
process can continue for as long as required. As each overflow record fills, the application obtains
another overflow record. This process is called standard forward chaining.
The prime record and its overflow records are usually chained together by storing a pointer to the first
overflow record in the prime record, storing a pointer to the second overflow record in the first overflow
record, and so on. The actual pointers are 4-byte tokens called file addresses (file addresses are
explained in more detail in 2.3, “Record addressing” on page 23) You can conveniently indicate the end of
a chain by setting the pointer in the last record to binary zeros (which is an invalid file address).
Figure 19 on page 20 shows how an application chains overflow records.
Chapter 2. ALCS database file management
19
Data sets
Figure 19. ALCS direct-access files: Standard forward chains
Note: Figure 34 on page 33 shows where the forward-chain pointer is stored in a record header.
Standard backward chaining
There are two potential problems with standard forward chaining:
5 To add an item to an existing chain, the application program must read all the records in the chain.
For chains which contain many records this can be a substantial overhead and can degrade the
performance of the application.
5 If any record in the chain is overwritten (for example by program error) it is impossible to find the
remaining records in the chain.
A common way to avoid these problems is to use standard backward chaining (as well as forward
chaining). The prime record holds a pointer to the last overflow record. The first overflow record holds a
pointer to the prime record and so on.
Figure 20 shows how an application creates forward and backward chains.
Figure 20. ALCS direct-access files: Backward chains
Note: Figure 34 on page 33 shows where the backward-chain pointer is stored in a record header.
20
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data sets
By convention, if there are no overflow records both the forward and backward chain fields in the prime
record contain binary zeros.
By using standard backward chaining, an application program can locate the last overflow record using the
pointer stored in the prime record – this avoids reading all the records in the chain.
Also, if one record in the chain is overwritten, it is possible to find all the records before the corrupted one
by following the forward chain pointers, and all the records after the corrupted one by following the
backward chain pointers.
2.1.7 Lists and indexes
You can use chains to create list structures. For example, you can hold a list of names in a chain of
records (prime and overflow). Each entry in the list points to another record.
Figure 21 shows a list structure where names are grouped alphabetically (but not sorted) in chain. Each
entry contains a pointer to a record which contains details about that person. One of the records has an
overflow record to contain more information. This structure shows standard forward chaining for both the
list records and the detail records. You could also use standard backward chaining for either (or both) if
required.
Figure 21. ALCS direct-access files: Lists
If the list contains many names (and pointers) an application program may need to read the prime list
record and many overflow list records before it finds the pointer for the required detail record.
You may be able to reduce the number of reads by using an index structure. Figure 22 on page 22
shows an index structure based on the 26 letters of the English alphabet. Each of the 26 entries on the
index record contains a pointer to a list record which contains all the names that begin with the letter. The
list records contain a pointer to the detail records.
Chapter 2. ALCS database file management
21
Data sets
Figure 22. ALCS direct-access files: Indexes
2.2 General files and general data sets
General files can be used to transfer data to or from application programs that do not run under the
control of the ALCS monitor. -- Heading 'SHARGDS' unknown -- gives an overview of sharing files.
General files are single-extent VSAM entry-sequenced data sets. There can be a maximum of 256
general files, each identified by a decimal number in the range 0 through 255.
Note: ALCS reserves general file 0 for its own use.
There is one data set for each ALCS general file. Application programs can access a general file only if
the data set is allocated to ALCS. In some predecessor systems, general files and general data sets are
different and application programs must access a file as either a general file or a GDS. In ALCS they are
physically identical, but ALCS supports both methods of access. Application programmers identify:
5 General files by the general file number
5 General data sets by the data set name
However to the system programmer general files and general data sets are the same. In this book the
term general file is used to mean either general file or general data set.
ALCS provides the ZDASD command to allocate and deallocate general files and data sets. ALCS
Operation and Maintenance describes the ALCS ZDASD command.
22
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Record addressing
2.3 Record addressing
ALCS application programs use a 4-byte file address to refer to records in:
5 The real-time database
5 General files or general data sets (GDS)
This file address is different from ALCS/VSE and TPF file addresses (see 2.3.3, “Multiple file address
format support” on page 26).
|
|
|
|
|
|
|
TPF compatibility
Applications that require compatibility with TPF can use an 8-byte file address, by using a DECB data
level. ALCS applications that use a DECB data level must use an 8-byte file address in 4x4 format.
You can obtain an 8-byte file address by specifying a DECB address when you request a monitor
service to get a file address, or by requesting the FA4X4C monitor-request macro (tpf_fa4x4c C
function) to convert an existing 4-byte file address to an 8-byte file address in 4x4 format. For more
information about the 8-byte file address in a DECB see ALCS Application Programming Guide.
2.3.1 Constructing the file address
ALCS provides monitor services that application programs can use to construct the file address from:
Class
Type
Ordinal
Fixed file or general file (or GDS)
Fixed file record type or general file number
Record ordinal (relative record number within type).
Notes:
1. Application programs do not construct a file address for pool file records. Application programs
request a pool-file record and ALCS gives the file address.
2. Application programs do not construct a file address for configuration data sets or system fixed-file
records. These records are not intended for application use.
General files and general data sets (GDS) are the same thing. Applications that use RAISA call them
general files, applications that use GDSNC and GDSRC call them general data sets. Figure 23 on page 24
summarizes the ALCS class, type, and ordinal to file address compression technique.
Chapter 2. ALCS database file management
23
Record addressing
Figure 23. ALCS file address: Compressing the class, type, and ordinal
ALCS provides the RONIC monitor-request macro to determine the class, type, and ordinal from the file
address.
ALCS also provides C language functions that perform similar services. See ALCS Application
Programming Reference – C Language for further details.
2.3.2 File address format
The file address format that ALCS uses is called the band format. A band format file address consists of
two parts (that is, two binary numbers). The two parts are the band and the band ordinal. For any one
band, there is a maximum band ordinal. Different bands can have different maximum band ordinals.
┌───────┐
│ band │
└───────┘
┌───────────────┐
│ band ordinal │
└───────────────┘
The ALCS generation allocates one or more bands for each record type. It never allocates the same band
to more than one record type. The ALCS generation must allocate more than one band if the number of
records of that type is greater than the maximum band ordinal for the first band.
If there is only one band for a record type, ALCS constructs the file address using the band, with the band
ordinal equal to the record ordinal. If there is more than one band for a record type, ALCS uses the first
band for record ordinals up to the maximum band ordinal, and it uses the second band with band ordinals
starting from 0, and so on.
Suppose, for example, that you decide to allocate band number 4387 (X'1123') to a particular record
type. If there are 5000 records of this type, then ALCS forms the file addresses like this:
24
Record Ordinal
Band
Band ordinal
0
X'1123'
0
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Record addressing
Record Ordinal
Band
Band ordinal
1
X'1123'
1
2
X'1123'
2
...
...
...
4999
X'1123'
4999
Note that in this case, band ordinals greater than 5000 are unused – the corresponding file addresses are
not valid.
Band number 4387 has a maximum band ordinal number of 65 535 – allowing up to 65 536 records. If
there are 80 000 record of the type then you might allocate two band numbers, for example 4387 and
4388 (X'1123' and X'1124'), then ALCS forms the file addresses like this:
Record Ordinal
Band
Band ordinal
0
X'1123'
0
1
X'1123'
1
2
X'1123'
2
...
...
...
65 535
X'1123'
65 535
65 536
X'1124'
0
65 537
X'1124'
1
...
...
...
79 999
X'1124'
14 463
Allocating bands
ALCS Installation and Customization describes how to select and allocate ALCS bands.
How bands and band ordinals appear in the file address
The ALCS file address contains the 1, 2, or 3 bytes of the band in reverse order starting at byte 3 of the
file address. The remaining bytes of the file address are the band ordinal as an unsigned binary number
(see Figure 24).
|
byte byte 1
byte 2
byte 3
┌────────────────┬────────────────┬────────────────┬────────────────┐
│ band ordinal │ band byte 2
band byte 1
band byte │
└────────────────┴────────────────┴────────────────┴────────────────┘
(up to 256 ordinals)
3-byte
band
┌─────────────────────────────────┬────────────────┬────────────────┐
│
band ordinal
│ band byte 1
band byte │
└─────────────────────────────────┴────────────────┴────────────────┘
(up to 65 536 ordinals)
2-byte
band
┌──────────────────────────────────────────────────┬────────────────┐
│
band ordinal
│ band byte │
└──────────────────────────────────────────────────┴────────────────┘
(up to 16 777 216 ordinals)
1-byte
band
Figure 24. ALCS file address formats
Chapter 2. ALCS database file management
25
Record addressing
For example, if you decide to allocate band number 4387 (X'1123') to a record type, then ALCS forms
the file address for the record ordinal number 500 (X'1F4') as follows:
Band
Band ordinal
File address
X'1123'
X'1F4'
X'01F42311'
2.3.3 Multiple file address format support
Records in an ALCS database can contain references to other records. These references are usually file
addresses. Typical examples include chains of pool records, where each pool-file record contains the file
address of the next pool-file record in the chain. It is possible, but less common, for a record to contain
the file address of another fixed file or general file record.
When a database migrates from TPF or ALCS/VSE, the records contain file addresses that are valid in the
migrate-from database (TPF or ALCS/VSE).
TPF and ALCS/VSE do not use the ALCS file-address format (band format), they use:
5 File-address format 3 (FARF3), 4 (FARF4), and 5 (FARF5) for TPF
5 Record-ordinal-number (RON) format file addresses for ALCS/VSE
TPF also supports two obsolete file address formats that can coexist with FARF3, they are:
5 Module, cylinder, head, record (MCHR)
5 Symbolic ordinal number (SON)
Some TPF users implement other file address formats. Figure 25 summarizes the different file addressing
schemes that have evolved.
TPF
ALCS
Figure 25. File address: Different formats for TPF and ALCS
To simplify migration from TPF and ALCS/VSE, ALCS can support more than one file address format.
That is, at the same time it can support the ALCS band format file address, and one of:
RON
26
ALCS supports ALCS/VSE RON format file addresses, provided that the fixed-file type values
are the same for ALCS/VSE and ALCS. If the fixed-file type values are different, ALCS can
support the file addresses only as user-defined format (see below).
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Allocatable space
FARF3
ALCS supports TPF FARF3 format file addresses provided that:
5 The fixed-file type values are the same for TPF and ALCS.
5 Fixed file FARF3 addresses contain the fixed-file type in bits 1 through 12.
5 There are no 4KB pool FARF3 addresses
If not, ALCS can support the file addresses only as user-defined format (see below).
user
Any user-defined format (or TPF FARF4 and FARF5 file address formats). ALCS can support:
5 A file address format that coexists with the ALCS band format.
5 A file address format that cannot coexist (for example FARF4).
ALCS supports these by calling an installation-wide exit routine. ALCS Installation and
Customization describes how to use the USRFAR installation-wide exit routine.
File addresses returned to applications
The DBGEN generation macro specifies the file address formats ALCS supports.
Applications normally use band format file addresses. ENTRC FACE, GETFC, RAISA, and so on always return
the band format file address. However FIND and FILE macros, RELFC, and so on, can use either the band
format file address or another file address format (for example, FARF3).
The record hold facility works correctly with multiple file address formats. That is, a record hold using one
file address format correctly, holds against another record hold that uses a different file address format for
the same record (see -- Heading 'RHOLD' unknown --).
Because ALCS monitor-request macros can use both file address formats, almost all ALCS functions can
specify either format. For example, the ALCS ZDFIL and ZAFIL commands can specify either file address
format. The ALCS ZDATA and ZRSTR commands can load data from magnetic tapes that ALCS/VSE or TPF
create (provided that the format is compatible).
TPF duplicated and nonduplicated pools
TPF supports three pool types for each record size: short-term, long-term duplicated, and long-term
nonduplicated. ALCS/VSE and ALCS only support two pool types, short-term and long-term.
ALCS multiple file address format support interprets both long-term duplicated and long-term
nonduplicated FARF3 addresses as the same type – long-term. To do this, ALCS partitions long-term
pool into two ranges of ordinal numbers. It then uses one range for long-term duplicated FARF3 ordinals,
and the other for long-term nonduplicated FARF3 ordinals. The POOLMIG parameter of the DBGEN macro
controls this partitioning.
2.4 Allocatable space overview
Figure 26 on page 28 shows (schematically) the initial allocation for:
5 Fixed file
5 Short-term pool
5 Long-term pool
This is the way the ALCS generation allocates your ALCS Version 2 Release 2.1 (or ALCS Version
2 Release 1.3) database initially (before you add or delete records). If you are migrating from a
predecessor ALCS version (or release), this layout is identical to your existing (predecessor) layout.
Figure 26 on page 28 shows some space that is not available (addressable). The extra space exists
because the VSAM clusters which contain the ALCS database comprise an integral number of DASD
Chapter 2. ALCS database file management
27
Allocatable space
cylinders. The cluster allocation process rounds up the number of records defined in the ALCS generation
to the next higher whole number of cylinders.
1.2.1, “How ALCS stores DASD records” on page 7 describes how ALCS uses VSAM control intervals. -Heading 'DATASET' unknown -- describes how ALCS uses VSAM clusters.
Figure 26. Allocatable pool: Initial allocation
Figure 27 shows the following records dispensed from long-term (LT) pool:
5 System fixed-file dispensed for ALCS purposes
5 Fixed-file records
5 Short-term pool
It also shows some fixed-file records which are marked for deletion. These records cannot be recovered
(undeleted) until they are purged.
Figure 27. Allocatable pool: Dispensing from LT-pool
Figure 28 shows the situation when the fixed-file records are purged from the database. This database
space is not available for re-use until you start to use type-2 long-term pool support.
Figure 28. Allocatable pool: After some fixed files are deleted (and purged)
When you change to type-2 dispensing, the previously-unavailable space (including the space occupied by
the purged fixed-files) is now available (allocatable). Figure 29 on page 29 shows this new allocatable
space.
28
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Allocatable space
Figure 29. Allocatable pool: After changing to type-2 dispensing
ALCS type-2 long-term pool support uses the same dispense mechanism to obtain records for any class
of ALCS record on the real-time database. ALCS does not use contiguous space for each class of record,
it treats records in allocatable pool as either:
5 Allocatable (available for dispensing)
5 In use for one of the following:
– Fixed file (FF)
– Short-term pool (ST)
– Long-term pool (LT)
– System fixed file (SF)
When ALCS dispenses a record from allocatable pool, it marks the record as in use for that class.
Note: Figure 30 shows the same database as Figure 29, but from the perspective of records in use.
Figure 30. Allocatable pool: Records in use
Figure 31 shows how the record classes are distributed over the allocatable pool space. In particular it
shows:
1. Long-term pool records in what were previously fixed-file records.
2. Fixed-file and short-term records in what were previously long-term pool records.
3. Short-term pool records in space that was previously not available.
Figure 31. Allocatable pool: Using and reusing allocatable pool
Chapter 2. ALCS database file management
29
Allocatable space
2.4.1 Algorithm-based addressing
Predecessor ALCS systems use an algorithm to convert a file address to a data set name, and a relative
byte address (RBA) within the data set to perform an I/O operation.
ALCS continues to support algorithm addressing. The algorithm uses the DASD configuration tables
produced by the ALCS DASD generation. Figure 32 shows algorithm addressing.
Class
Type
Record
Class
Class
Type
Type
Algorithm
Class and
Type
A
Class and
Type
B
Class and
Type
C
Class and
Type
D
Figure 32. Algorithm file addressing: Class, type, and ordinal to data set and RBA
30
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Class and
Type
E
Allocatable space
2.4.2 Table-based addressing
ALCS uses tables to convert file addresses into the corresponding data set and RBA information to locate
the physical record.
Note: ALCS still supports algorithm-based addressing, but uses tables for added records. Figure 33
gives an overview of the two types of file addressing.
Class
Type
Record
Table
addressing
Algorithm
Allocatable
pool space
L2LTPOOL
Figure 33. Table-based file addressing: Class, type, and ordinal to data set and RBA
Every record on the real-time database has an allocatable-pool file address. These are conventional
ALCS band-format file addresses with one or more bands defined for each record size. There is, of
course, only one allocatable pool type for each record size.
Note: When you are migrating from ALCS/MVS/XA or ALCS Version 2 Release 1.1, you must define
additional bands for the allocatable-pool types (sizes).
The index tables exist in memory and are built up using:
5 Fixed-file directories
5 Segment tables
Chapter 2. ALCS database file management
31
Allocatable space
Fixed-file directories
The fixed-file directories exist on the real-time database as chains of allocatable-pool records. Application
programs cannot access these system records. Any attempt is treated as an invalid file address. When
ALCS is executing, they also exist as in-memory tables.
Some of the real-time database records are used for fixed-file, short-term pool, and system records.
Application programs access these records using the corresponding fixed-file or pool-file address. If an
ECB-controlled program attempts to update a fixed-file or short-term pool record using its allocatable-pool
file address, ALCS treats this as an invalid file address.
System records cannot be updated by ECB-controlled programs. If an ECB-controlled program attempts
to update a system record using its allocatable-pool file address, ALCS treats this as an invalid file
address.
The remainder of the real-time database records are available for use as long-term pool records.
Application programs can access these records using the allocatable-pool file address. Databases
migrated from ALCS/MVS/XA or ALCS Version 2 Release 1.1, require the following special considerations:
5 The existing records contain embedded references to long-term pool. ALCS allows application
programs to access these records using the algorithm file addresses (ALCS/MVS/XA or ALCS Version
2 Release 1.1).
5 Fall back to the predecessor system (ALCS/MVS/XA or ALCS Version 2 Release 1.1). Long-term pool
file records can be dispensed with the predecessor system file addresses until fallback capability is no
longer required.
Fixed-file directories (which are also used for short-term pool) map each valid fixed-file or short-term pool
file address into the corresponding allocatable-pool file address.
Segment tables
In TPF and previous versions and releases of ALCS, addressability of records on the real-time database is
a natural consequence of the algorithms used to convert file addresses.
For old fixed-file and pool-file records (ALCS/MVS/XA or ALCS Version 2 Release 1.1), the conversion
uses algorithm file addressing. For fixed-file and short-term pool records added since migration, the
conversion uses the fixed-file directories.
The allocatable-pool record ordinal numbers are then mapped on to physical record locations using
segment tables. The segment tables map segments of addressability on to portions of the database
data sets. Each segment of addressability comprises 65 536 consecutive allocatable-pool ordinal
numbers, and maps onto 65 536 consecutive records within one database data set.
32
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Record header
This addressing scheme has the following important effects:
5 Addressability can be allocated independent of the actual number of physical records. Normally, at
least enough addressability must be allocated to equal or exceed the number of physical records. But
excess addressability can be allocated to allow for planned increases in the number of records (any
file address that does not correspond to a real physical address is treated as invalid).
5 Long-term pool dispense cannot dispense allocatable pool by scanning consecutive ordinal numbers
(like ALCS Version 2 Release 1.1 does). Such a mechanism would create unacceptable hot spots
because consecutive dispenses would come from the same data set. Instead, it explicitly strobes the
database data sets so that consecutive dispenses come from different data sets.
5 Adding addressability in the form of additional data sets can have the effect of unbalancing the even
distribution of records previously provided by striping. To correct this there is a restripe facility (ZDASD
STRIPE) which redistributes parts of the data base evenly over all the real-time datasets.
2.5 Record header
Each DASD record contains a header which ALCS applications use for the following purposes:
5 Record identification
5 Audit information (program stamp)
5 Chain information (if record chaining is used)
Figure 34 shows the layout of the ALCS standard record header.
Record ID
│
Record code check
│
│
Control byte
D
D
D
Optional fields
┌───┬───┬─────┬───┬───┬───┬───┬───┐┌ ─ ┬ ─ ┬ ─ ┬ ─ ┐┌ ─ ┬ ─ ┬ ─ ┬ ─ ─┐
│ i d │ rcc │ c │ program name │ Forward chain
Backward chain
└───┴───┴─────┴───┴───┴───┴───┴───┘└ ─ ┴ ─ ┴ ─ ┴ ─ ┘└ ─ ┴ ─ ┴ ─ ┴ ─ ─┘
┌────────────────────────────────────────────────────────────────────┐
│
Area for user data
│
:
:
│
│
└────────────────────────────────────────────────────────────────────┘
Figure 34. Record header
ALCS defines a standard 16-byte header format for DASD records. The header consists of a mandatory
8-byte part with optional extensions to 12 bytes (if standard forward chaining is used) or 16 bytes (if
standard backward chaining is used).
| In assembler programs use the STDHD DSECT macro to reference the fields in the standard record header.
| See ALCS Application Programming Guide) for details.
| In C programs use the header file <c$stdhd.h> to reference the standard record header. See the ALCS
| Application Programming Reference – C Language for details.
| Note: The $ character is the national currency symbol (X'B5').
The IBM program TPFDF uses an extended header for DASD records.
The standard header contains the following fields:
Record ID
A 2-byte field that identifies the type of data in the record.
Record code check (RCC)
A 1-byte field that (optionally) distinguishes between records that contain the same type of data (the
record ID is the same) but that are on different chains.
Chapter 2. ALCS database file management
33
VFA
Control byte
A 1-byte field that (optionally) contains the characteristics of the record (for example, record size, type
of record chaining, and so on). ALCS does not access the record control byte.
Program name
The 4-byte program name of the application program that last filed the record.
Chain fields
By convention, for records that use chaining (forward or backward), a 4-byte forward chain field and a
4-byte backward chain field complete the standard header.
2.1.6, “Overflow and chaining” on page 19 describes record chaining.
The system programmer can change the default attributes of a record type.
2.5.1 Record ID and RCC checking
When an application program reads a DASD record, it can specify the expected record ID (or record ID
and RCC). ALCS checks that the actual ID (or ID and RCC) matches the expected ID (or ID and RCC).
Application programs can suppress these checks.
When an application program writes a DASD record, it must specify the expected record ID (and optionally
the RCC). ALCS checks that the actual ID (or ID and RCC) matches the expected ID (or ID and RCC).
2.6 Virtual file access
ALCS reduces the number of I/O operations by using virtual file access (VFA) to process all FIND and
FILE macros issued by application programs. VFA holds the most recently used database records in
buffers (caches) in processor storage. Figure 35 gives an overview of VFA.
Figure 35. Virtual file access (VFA) overview
The more VFA buffers of each size that are specified at generation time, the greater the benefits in DASD
and processor performance.
VFA combines the required level of data integrity and the minimum number of I/O operations by handling
FILE macros according to the record VFA option specified at generation time. Different types of record
have VFA options to determine whether changed records should be written to DASD at once, deferred for
a short time, or held in the buffer.
For example, IPARS AAA records are referred to and perhaps updated several times for every transaction
by the associated terminal. Holding these records in VFA buffers provides a faster response and greatly
reduces the physical I/O for active terminals. The record is not written to DASD until the buffer is required
34
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
VFA
by more active records. All updated records, regardless of VFA option, are written out when ALCS
terminates.
The number of I/O operations to DASD depends on the size of the VFA buffer area. With large numbers
of VFA buffers, VFA processes many FIND and FILE macros without doing any DASD I/O. This results in
a reduced load on the DASD subsystem, and a lower processor utilization at a given message rate,
because of the reduced number of I/O instructions and I/O interruptions. Use the VFABUF parameter of the
ALCS SCTGEN macro to specify the number of VFA buffers during the ALCS generation.
VFA satisfies FILE macros by copying data records from the application's storage to a VFA buffer. It
schedules the I/O operation to write the record to DASD from the VFA buffer, depending on the VFA
options.
ALCS has the option of using hiperspace to provide additional buffering for DASD I/O.
If specified, ALCS will write the contents of VFA buffers that are about to be reused to hiperspace. This
could further reduce DASD I/O if a subsequent FIND request for a record can be satisfied from its
hiperspace copy.
ALCS Installation and Customization describes the VFAOPT parameter of the ALCS database generation
macros to specify the characteristics of VFA. You can specify:
5 The filing frequency
– Immediate
– Delayed (only when a buffer is required)
– Time-initiated (flagged records are filed periodically)
5 Permanence
– Permanently resident (the buffer is never re-used)
– Not permanently resident (VFA re-uses the buffer with the longest time since last referenced)
5 New or update record
– Update mode (VFA ensures that the VFA buffer contains the old record contents). This action is
used for update logging; see -- Heading 'DBULOG' unknown --.
– Not update mode (VFA gets a new buffer and stores the record if necessary).
5 Expanded Storage Option
– Use Hiperspace backing to hold reused VFA buffers
– No Hiperspace backing
5 Online and offline access to the same general file
– Forced read (always reads the record from DASD to use the latest copy of the record)
– Not forced read (reads the record from DASD only if it is not in VFA buffers or Hiperspace)
2.7 Spill file on predecessor ALCS systems
Predecessor ALCS systems use spill data sets to reduce the need for frequent database reorganizations.
These systems use spill data sets to extend (add records) to the database without moving any existing
records.
For example, to add a new record type that is size L2, or to add more records to an existing record type
that is size L2, ALCS uses one or more additional size L2 spill data sets.
Chapter 2. ALCS database file management
35
Test database facility
ALCS Version 2 Release 2.1 supports any spill data sets (from predecessor ALCS systems) and allows
you to add more spill data (using algorithm addressing) until you no longer need to fall back to a previous
version of ALCS, or have migrated to type-2 long-term pool support.
You can then start to use the table-based addressing to extend the database.
2.8 The ALCS test database facility
New and changed application programs can contain errors capable of damaging the database. They
must, therefore, be tested in such a way as to avoid damage to the existing database, while ensuring
realistic testing.
One way of doing this is to copy all or part of the existing database to a test database; but the number of
test databases for testing different programs could exceed the hardware available. This is especially true
because ALCS allows any number of test systems to be in operation at one time, so that application
programmers can test their different programs simultaneously and independently. The ALCS test
database facility allows many application programmers (or groups of programmers) to have their own test
system without needing multiple copies of the entire test database.
Note: Do not use the test database facility if your configuration data set is not initialized. The note in
“Creating DASD configuration data sets” on page 40 explains this in more detail.
2.8.1 How the test database facility works
The ALCS test database facility gives a program read-only access to a database.
Figure 36. Test database: Read a record from the test database
When the program updates a record, ALCS writes it to a separate data set (the test data set) instead of
updating the database from which it was read.
36
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Test database facility
Figure 37. Test database: Write a record to the test data set
When the program next reads the record, ALCS gets it from the test data set. Thus the application seems
to have normal read-write access to the database, which however remains unchanged.
Figure 38. Test database: Read and write on the test data set
The ALCS test database facility makes it safe to test programs using the production database. However,
most users prefer to use this facility with a stable test database that meets all the testing requirements of
the programmers, with minimum impact on production work and without excessive demands on DASD
space.
2.8.2 Benefits
Some of the benefits of the test database facility are:
Recovering from database damage
During a test, an application program can write bad data that makes the database unusable. If this
happens, it is not necessary to restore the test database. Deleting all the records in the test data set has
the same effect. An easy way of doing this is to delete the test data set and allocate a new (empty) data
set.
Chapter 2. ALCS database file management
37
Test database facility
If a series of tests takes several days or weeks, it is possible to back up the test data set at convenient
times. If a particular test writes bad data, then it is easy to recover by restoring a backup of the test data
set.
Sharing the test database
Several programmers may need a test database. The test database facility allows them all to share the
same copy of the test database. If each programmer (or group of programmers) has a separate test data
set, they can run tests simultaneously without interfering with one another.
Figure 39. Test database: Shared testdata base, separate test data sets
Also, programmers who are running a series of tests do not put other tests at risk by changing or
damaging their data.
A programmer can create a new test data set by copying an existing test data set. In this way,
programmers can run tests against a database that already includes updates from previous testing. For
example, one programmer might initialize a number of records, then a second programmer might copy the
test data set. Both programmers can then run tests that use these records.
You can also use the ZRELO command to move records from a sequential file to your test database. This
is described in ALCS Operation and Maintenance.
38
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Test database facility
2.8.3 Test pool files
If your test database is a copy of all or part of your production database then you may wish to update it
from time to time by making a new copy from the production database. But if you do this, you may find
that some pool file addresses (both long-term and short-term) that were available when you made your
previous copy from the production database have since been dispensed on both the production database
and on one or more test data sets. This can cause some strange effects – for example:
Suppose that at the time you made a copy of the production database pool-file record L1LTPOOL(200)
was available. A program running on the production system dispenses the record for use as an overflow
for the fixed-file record #FIXEDA(20). It saves the address of L1LTPOOL(200) in #FIXEDA(20).
Meanwhile, a program running on a test system dispenses the record for use as an overflow for the
fixed-file record #FIXEDB(30). It saves the address of L1LTPOOL(200) in #FIXEDB(30). Figure 40
shows the two versions of the pool record.
Figure 40. Test database: Copy record to test data set
If you now make a new test database from the production system, there are two “versions” of record
L1LTPOOL(200). The one on the test data set is an overflow for the fixed-file record #FIXEDA(20), the
one on the test database is an overflow for the fixed-file record #FIXEDB(30).
If a program running on the test system needs to access the overflow record for #FIXEDB(30) then it will
read L1LTPOOL(200) and find the data that it expects. But if the program needs to access the overflow
for #FIXEDA(20) – assuming that #FIXEDA(20) has not been updated on the test system – then it will
read L1LTPOOL(200) and find the overflow for #FIXEDB(30). Figure 41 on page 40 shows the two
versions of the pool record.
Chapter 2. ALCS database file management
39
Test database facility
Figure 41. Test database: Incorrect overflow file address
To avoid these strange effects, you can partition pools to reserve pool records for test database use.
For example, you can reserve 1 percent of pool records for test database use, and leave 99 percent for
production use.
This avoids the problem of incorrect pool addresses between the test database and the production
database, because it is impossible to dispense the same record on both the test system and the
production system.
See ALCS Installation and Customization for more information about the PARTITION parameter of the
DBGEN macro.
2.9 The ALCS DASD configuration data set
Unlike ALCS/MVS/XA and ALCS Version 2 Release 1.1 when you start ALCS Release 2 Version 2.1,
ALCS obtains the DASD configuration information from the configuration data set. ALCS still loads the
configuration table in order to get the data set name of the configuration data set. The process of creating
and updating the configuration data sets is entirely online.
Creating DASD configuration data sets
When ALCS starts, it loads the DASD configuration table which contains the names of both copies of the
configuration data set, and attempts to read them.
If they are newly allocated, ALCS automatically preformats them. Initially, neither copy contains DASD
configuration information and ALCS copies across the information from the configuration table. If either
copy contains valid DASD configuration information then ALCS uses that copy.
Note: ALCS cannot preformat your configuration data set if you are using the test database facility. This
is because the data set is opened as read only. In this situation you need to run once without the test
database facility. Once the configuration data set has been preformatted you can then use the test
database facility.
40
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Test database facility
Updating the DASD configuration data sets
When you wish to update the data configuration you create a new DASD configuration table and load it
using the ALCS command ZDASD LOAD.
Chapter 2. ALCS database file management
41
Entry management: Creating entries
Chapter 3. Entry management
An entry is an ALCS unit of work. ALCS can create and dispatch entries. This section describes how
ALCS creates and dispatches entries. See also 1.3, “Multiprogramming and multiprocessing” on page 9.
3.1 How ALCS creates entries
To create entries, ALCS uses the following:
5
5
5
5
Input messages
Create-type monitor-request macros (CREMC, CREDC, CRETC, CREXC)
Monitor-created entries
The time available supervisor (TAS)
Input messages: ALCS creates a new entry for every input message; that is, whenever ALCS receives
an input message. To create this new entry the online monitor does the following (not necessarily in this
order):
5 Initializes storage to contain an ECB and an attached storage block. The attached storage block
contains the input message on ECB level 0.
5 Updates internal counters and control fields to indicate that there is one more entry.
5 Indicates that the entry is an input message entry and saves origin information in the ECB and the
ECB descriptor. This origin information includes the communication resource identifier (CRI) of the
originating communication resource.
5 Adds the entry to the input list. The input list is a queue of entries that are new input messages. It is
one of the ALCS entry dispatcher work lists. Figure 42 on page 45 shows the structure of an ALCS
entry-dispatcher work list.
Create-type services: ALCS provides services that allow application programs to create new entries.
When an entry requests one of these services, ALCS creates a new entry as follows (not necessarily in
this order):
5 Initializes storage to contain the new ECB. If the create-type macro passes storage block contents,
ALCS initializes attached storage blocks as required.
5 Updates internal counters and control fields to indicate that there is one more entry.
5 Indicates that the entry is a created entry and copies origin information from the creating entry to the
ECB and the ECB descriptor.
5 Adds the entry to one of the ALCS entry dispatcher work lists described in 3.2, “How ALCS dispatches
entries” on page 44.
42
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry management: Creating entries
In the same way, ALCS creates new entries for other services that can create new entries. These include:
5 System error macros (SYSRA and SERRC). These services can create a new entry that sends a system
error dump message to RO CRAS.
5 Send-type monitor-request macros. Some send services create a new entry that processes the output
message. SENDC T (that is, SENDC with the T parameter) is an example.
Monitor-created entries: ALCS sometimes creates new entries that do not arise from input messages or
create-type services. For example, the monitor timer routines create a new entry every minute. The new
entry is for application-dependent timer functions.
These new entries are called monitor-created entries. ALCS creates them as follows (not necessarily in
this order):
5 Initializes storage to contain the new ECB and attaches storage blocks as required.
5 Updates internal counters and control fields to indicate that there is one more entry.
5 Indicates that the entry is a monitor-created entry and clears origin information in the ECB and the
ECB descriptor.
5 Adds the entry to one of the ALCS entry dispatcher work lists described in 3.2, “How ALCS dispatches
entries” on page 44.
Time available supervisor: ALCS supports a facility called time available supervisor (TAS). TAS
allows an entry to create other entries with very low priority. To use TAS, entries issue the TASTC and
TASBC monitor services TASTC starts TAS (and makes TAS active) and TASBC stops it (makes it inactive).
Unlike the create-type services, TASTC does not create a new entry and add it to an ALCS entry dispatcher
work list. TASTC sets a switch to indicate that there is low priority work waiting. The entry dispatcher
checks the switch when there is no other work that ALCS can dispatch. If the switch is set, ALCS creates
a new entry and dispatches it immediately. See 3.2, “How ALCS dispatches entries” on page 44 for more
information. ALCS does this as follows (not necessarily in this order):
5 Initializes storage to contain an ECB.
5 Updates internal counters and control fields to indicate that there is one more entry.
5 Indicates that the entry is a TAS-created entry and clears origin information in the ECB and the ECB
descriptor.
5 Dispatches the new entry by transferring control to the application program TIA1.
ALCS continues to create and dispatch new entries in this way while TAS is active (that is, until an entry
requests TASBC monitor service). In this way, an entry can create a number of low priority entries.
Chapter 3. Entry management
43
Entry management: Dispatching entries
3.2 How ALCS dispatches entries
This section contains Diagnosis, Modification, and Tuning Information. Do not use this information as a
programming interface.
This section summarizes the normal way in which ALCS dispatches entries. Do not develop application
programs that depend on the way that ALCS dispatches entries. Programs that depend on the ALCS
dispatching method can fail unpredictably.
For example, do not develop application programs that depend on the priority order of the ALCS entry
dispatcher work lists. In some situations the ALCS entry dispatcher checks work lists in a different order.
To dispatch an entry, the ALCS entry dispatcher (often called the CPU loop) checks lists of entries, called
ALCS entry dispatcher work lists. Each list contains only entries that are dispatchable. For example, if
an entry waits for an I/O operation to complete, ALCS does not add the entry to an ALCS entry dispatcher
work list until the I/O completes.
All the entry dispatcher tasks check the same set of work lists.
The ALCS entry dispatcher checks its work lists in sequence. In this way, each list corresponds to a
priority. The ALCS entry dispatcher work lists are, in order of priority:
IOCB list
ALCS uses the IOCB list internally to dispatch system functions.
Ready list
ALCS uses this list mainly for entries that can resume processing after I/O completion. For
example, if an entry requests a FINWC monitor service to read a DASD record, it loses control
until I/O completes. When I/O completes, ALCS adds the entry to the ready list.
Delay list
ALCS uses this list mainly for entries that request DEFRC or DLAYC monitor services. Entries
request monitor services to avoid monopolizing resources. Refer to 3.5, “Delay and defer
processing” on page 47.
Input list
ALCS uses this list mainly for new entries. For example, when ALCS receives an input
message, it creates a new entry and adds the new entry to the input list.
Defer list
ALCS uses this list mainly for entries that request DEFRC or DLAYC monitor services. Entries
request monitor services to avoid monopolizing resources. Refer to 3.5, “Delay and defer
processing” on page 47.
Deferred IOCB list ALCS uses the deferred IOCB list internally to dispatch system functions.
44
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry management: Dispatching entries
If the ALCS entry dispatcher can dispatch an entry from the first list, it does so, and does not check
subsequent lists. If it cannot dispatch an entry from the first list, it normally checks the second list, and so
on. However, if the system load is heavy the ALCS entry dispatcher does not service the delay, input, or
defer lists. Regardless of load, the ALCS entry dispatcher does not service the delay and defer lists in
certain situations described in 3.5, “Delay and defer processing” on page 47.
Figure 42 shows the format of an ALCS entry dispatcher work list.
List header
Block descriptor
┌──────────────────────────────;┌───────┬─────────┬──
┌───│───┬───────┬───────┬───────┐
│ Chain │ Pointer │
│ First │
│ Last │
│
├───┬───┴────│────┘
└───────┴───────┴───│───┴───────┘
│
D
└─────────────────;┌─────────────────
│
┌───────┬─────────┬──
│ Entry storage
│
│ Chain │ Pointer │
│ (includes ECB)
│
├───┬───┴────│────┘
│
│
D
└──────────────;┌─────────────────
└────────────────────;┌───────┬─────────┬──
│ Entry storage
│
│ Pointer │
│ (includes ECB)
├───────┴────│────┘
│
└───────────;┌─────────────────
│ Entry storage
│ (includes ECB)
Figure 42. Entry dispatcher work list (schematic)
An ALCS entry dispatcher work list is a first-in-first-out (FIFO) queue. That is, ALCS adds an entry to the
bottom of an ALCS entry dispatcher work list; the ALCS entry dispatcher starts checking at the top of the
list.
However on a multiprocessor, the ALCS entry dispatcher cannot always dispatch the first entry on a list.
For example, the first entry might need exclusive control of a global area field that is already controlled by
another entry in shared or exclusive mode. If the ALCS entry dispatcher cannot dispatch the first entry on
a list, then it checks the next entry, and so on.
When ALCS adds an entry to an ALCS entry dispatcher work list, it saves the address of the
post-interrupt routine in the ECB descriptor. To dispatch an entry, the ALCS entry dispatcher removes
the entry from the work list and branches to the post-interrupt routine. Generally, the post-interrupt routine
does one of the following:
5 Add the entry to another ALCS entry dispatcher work list and branch to the ALCS entry dispatcher.
5 Exit the entry and branch to the ALCS entry dispatcher.
5 Transfer control to an application program.
In the last case, eventually the application program must request a monitor service that loses control. The
macro service routine branches to the ALCS entry dispatcher.
If the ALCS entry dispatcher cannot dispatch any entry, it enters the MVS task wait state. When an event
makes an entry dispatchable, ALCS posts the ALCS entry dispatcher tasks. The ALCS entry dispatcher
then checks the work lists again.
Chapter 3. Entry management
45
Entry management: Losing control
3.2.1 Entry processing limits
ALCS can detect and cancel (exit) entries that monopolize or misuse resources. For example, if an entry
dispenses too many pool file record addresses, then ALCS cancels the entry with a system error dump.
To do this, ALCS uses entry processing limits specified by the generation parameters ENTxxxx of the
SCTGEN macro.
ALCS Installation and Customization describes the SCTGEN macro.
ALCS can also detect application programs that loop without losing control, see 3.3.1, “Application loop
timeout”.
3.3 How entries lose control
Many multiprogramming systems invoke the dispatcher at every interrupt. In these systems, a task can
lose control at any time (unless the task can mask the processor against interrupts). This is because an
interrupt can make a higher priority task dispatchable. If it does, the multiprocessing system stops
processing the active task and dispatches the higher priority task instead. This is called preemptive
dispatching.
ALCS does not use preemptive dispatching. Instead, ALCS invokes its entry dispatcher only when an
application program requests a monitor service. If an interrupt makes an entry dispatchable, ALCS adds it
to an ALCS entry dispatcher work list; the active entry continues to execute. This is called
non-preemptive dispatching. Whether or not ALCS invokes the entry dispatcher depends on which
service the entry requests. Each service does one of the following:
5 Always loses control; that is, invokes the entry dispatcher (for example, the DEFRC monitor service).
5 Never loses control (for example, the TIMEC monitor service).
5 Sometimes loses control (for example, the ENTRC monitor service loses control only when the global
serialization requirements for the entering program and for the entered program differ).
ALCS Application Programming Reference – Assembler and ALCS Application Programming Reference –
C Language contain descriptions of all assembler and C language services respectively. These
descriptions indicate whether the service causes the entry to lose control (that is, whether or not the
routine invokes the entry dispatcher).
3.3.1 Application loop timeout
An ALCS entry does not normally lose control until it requests a monitor service. However, an entry can
monopolize a processor when it goes into a loop and does not request any monitor service (or requests
only monitor services that do not lose control).
To prevent this, ALCS imposes a maximum time for an entry to execute before it must lose control. If an
entry does not lose control within this time limit, then ALCS cancels (exits) the entry with a system error
dump. This procedure is called application loop timeout.
Do not develop application programs that depend on the exact size of the application loop timeout.
Instead, ensure that entries lose control at least after every 10 000 instructions.
46
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry management: Delay and defer processing
3.4 Input/output counter and wait service
ALCS provides monitor services that request input/output (I/O) operations. For example, FILEC requests a
write to a DASD data set, TPRDC requests a read from a sequential file (physical sequential data set), and
so on. Generally the I/O can proceed independently; the entry can continue processing while the I/O
takes place. An entry that requests an input operation must ensure that the data input completes
successfully before it uses the data. To do this, the entry uses the ALCS wait service. The wait service:
5 Suspends the entry until the I/O completes
5 Tests for I/O errors
If an entry requests input when a buffer already contains the data, the wait service does not suspend the
entry. Even so, the entry must always request the wait service. The entry cannot know that a buffer
already contains the data.
The ALCS WAITC monitor service and the waitc C language function request the wait function. Some
other monitor services and C language functions request both I/O and the wait service. For example,
FINWC requests a DASD read followed by the wait service.
ALCS does not support the wait service for all monitor services that request I/O. For example, FILEC
requests a DASD write. The wait service does not wait for I/O that FILEC requests. Also, the wait service
does not test for FILEC I/O errors. So there are two types of monitor service or C language function that
request I/O:
5 The I/O request requires the wait service. The entry must request the wait service to check that the
I/O completes successfully.
5 ALCS does not support the wait service for the I/O request (to reduce response time). The entry
cannot check that the I/O completes successfully.
The description of each service in ALCS Application Programming Reference – Assembler and ALCS
Application Programming Reference – C Language indicates whether or not it requires the wait function.
3.5 Delay and defer processing
Delay and defer list service: 3.2, “How ALCS dispatches entries” on page 44 describes how the ALCS
entry dispatcher services the ALCS entry dispatcher work lists in the following order of priority:
1.
2.
3.
4.
Ready list
Delay list
Input list
Defer list
It only checks the input list when it cannot dispatch any entry on the ready list, and so on. Also, the ALCS
entry dispatcher does not service the input, delay, and defer lists if ALCS is too busy.
Sometimes the ALCS entry dispatcher does not service the delay and defer lists even when there are no
other dispatchable entries and ALCS is not too busy. This allows other MVS tasks to have priority over
ALCS entries that are on the delay and defer lists. It also allows time for write operations to complete
before the ALCS entry dispatcher redispatches an entry that requests a DEFRC monitor service.
In particular, once the ALCS entry dispatcher has serviced the defer list, it does not do so again until 0.2
seconds later.
Attention
Chapter 3. Entry management
47
Entry management: Communication
You should be aware of the dangers of defer/delay loops waiting for some external event that never
happens. You can overcome these dangers either by using EVNTC, EVNWC, and POSTC, or by incorporating a
check to limit the amount of time spent in the defer/delay loop.
Entry write limits: Some ALCS monitor services request output operations that proceed independently
of the entry. See 3.4, “Input/output counter and wait service” on page 47. For example, FILEC requests a
DASD output operation (write) but the entry does not wait for the output to complete. However an entry
can use all the available DASD I/O buffers if it goes into a loop that requests a FILEC monitor service.
To prevent this, ALCS requires entries to request DEFRC monitor service (or DLAYC). DEFRC and DLAYC
suspend processing of an entry to allow other entries to proceed. The ENTWRT= parameter of the SCTGEN
macro specifes two limits (ew1 and ew2) to regulate this.
The ew1 value is the maximum number of writes that an entry can request before it must defer. When an
entry requests more than ew1 writes without issuing a DLAYC or DEFRC macro, ALCS forces the entry to
defer. That is, for one write in every ew1 writes, ALCS adds the entry to the defer list during the write
monitor service. This gives a time delay (on average 0.2 seconds) that allows the writes to complete.
When the entry continues to request writes, ALCS forces it to defer again after the next ew1 writes, and
so on.
An entry can prevent these forced defers by issuing DLAYC or DEFRC more often than every ew1 writes.
When an entry requests DLAYC or DEFRC monitor service, the other limit of the pair, ew2, decides whether
ALCS puts the entry on the delay list or the defer list. If there have been ew2 (or more) writes since the
entry lost control, ALCS adds the entry to the defer list during the DLAYC or DEFRC monitor service. This
gives a time delay (approximately 0.2 seconds) to allow any writes to complete.
When an entry requests a write and requests a DEFRC monitor service every time round a loop, for
example:
LOOP
..
.
EQU
V
FILEC D1
DEFRC ,
..
.
B
LOOP
then ALCS puts the entry on the delay list each time round the loop, except that every ew2 times round
the loop ALCS puts the entry on the defer list.
TPF compatibility
TPF implements DLAYC and DEFRC slightly differently from ALCS. The differences are not normally
significant to application programmers, but do not request DEFRC monitor service with records held if
you wish to maintain compatibility with TPF.
3.6 Communication between entries
Sometimes entries need to communicate with other entries. That is, they must pass data to or share data
with other entries. But an ALCS entry must not access ECB fields or storage blocks that belong to
another entry.
48
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry management: Communication
3.6.1 How entries pass data
ALCS provides monitor services that allow an entry (the creating entry) to create a new entry (the created
entry). These are the create-type services. Create-type services have parameters that allow the creating
entry to pass data to the created entry. The creating entry can specify:
5 The address and length of a parameter area. ALCS copies the contents of the parameter area into
the ECB work area of the created entry.
Creating entry
Created entry
┌────────────────┐
┌────────────────┐
Addr─;├─────────────┐ │
├─────────────┐ │
│ppppppppppp ────────────────────────────────;│ ppppppppppp │ │
├─────────────┘ │ The create macro specifies ├─────────────┘ │
│K──── L ────;
│ the address and length of │
│
│
│ the parameter area.
│
│
└────────────────┘
└────────────────┘
Parameters in EBW
Figure 43. Passing data between entries: parameter areas
5 One or more storage blocks attached to the ECB of the creating entry. ALCS copies the contents of
the storage blocks into the new storage blocks attached to the ECB of the created entry.
Creating entry
Created entry
┌────────────────┐
┌────────────────┐
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
├────────────────┤
├────────────────┤ New blocks attached
│ Data levels
│
│ Data levels
│ to contiguous levels
│ D D1 D2 .. DF │
│ D D1 D2 .. DF │
└─┬─────┬────────┘
└─┬──┬───────────┘
│
│
Storage blocks
│ │ Storage blocks
│
└────;┌────────────┐ Copy contents
│ └─;┌────────────┐
│
│ abcdefghij │── ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ;│ abcdefghij │
│
└────────────┘
│
└────────────┘
└──────────;┌────────────┐
└────;┌────────────┐
│ xxxyyyzzz │── ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ;│ xxxyyyzzz │
└────────────┘
└────────────┘
Figure 44. Passing data between entries: storage blocks
ALCS Application Programming Reference – Assembler and ALCS Application Programming Reference –
C Language explain how to use these services and their parameters.
3.6.2 How entries share data
Creating entries can share data with created entries.
The main types of data that ALCS entries can share are:
5 Application global area
5 DASD records
ALCS supports facilities designed to help entries to share data.
ALCS supports an area of storage that entries can share. This is called the application global area.
This area is not protected; any entry can store information in the global area.
It can be complex to use the application global area in a multiprocessor environment for anything except
constants. It is much simpler to store variable data in DASD records (appropriate use of virtual file access
(VFA) makes physical I/O unnecessary).
Chapter 3. Entry management
49
Entry management: Multiple entries
However, if you cannot avoid using the application global area, ALCS Installation and Customization
describes how to use the application global area.
-- Heading 'RHOLD' unknown -- describes facilities that help entries to share DASD records.
3.7 Transactions that create multiple entries
Many transactions require only one entry each for their processing – that is, they do not need to request
create-type services. But you may find it more efficient to implement some complex transactions by
creating a number of entries that can process in parallel.
For these transactions, the original entry (called the parent entry) creates a number of child entries, which
can run parallel with each other and with the parent entry.
The child entries can in turn create more grandchild entries, and so on.
Application programs that create child and grandchild entries in this way can efficiently exploit ALCS's
multiprogramming and multiprocessing capabilities – but these types of program can cause serious
problems unless they are carefully designed. When designing new programs or installing purchased
programs of this type, you should observe the following points:
Avoiding too many create-type services
In most ALCS configurations, ALCS services create-type services in preference to new input transactions.
This is to ensure that in-flight transactions complete even when there is a high input message rate.
Otherwise an in-flight transaction that requests a create-type monitor service might have to wait while
ALCS processes new input transactions, which might in turn request create monitor services, and so on.
This could cause a deadlock in ALCS.
But because of this, a parent entry that creates many child and grandchild entries can flood ALCS with
entries, and so lock out new transactions. Application programs can avoid this by regulating their use of
create-type services with the LODIC monitor service (or the lodic C language function). But note that
transactions that create only one or two entries should not use LODIC in this way.
Avoiding create-type services in loops
Parent entries that create many child entries typically do this by issuing a create-type macro in a loop.
The parent entry can lose control if there are too many entries in the system. There may be too many
entries because the parent entry is issuing many create-type services. This situation is compounded if the
child entries themselves loop creating grandchild entries.
Other, unrelated, entries that request create monitor services may also be forced to wait in this situation.
50
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry management: SQL, CPI-C, APPC, MQI and TCP/IP
Parent entry │
┌────────;│
│ ┌───────┴──────┐
│ │ Processing
│
│ └───────┬──────┘
Child entries (one for each iteration of the parent loop)
│ ┌───────┴──────┐
┌───────────┐┌───────────┐┌ ─ ─ ─ ─ ─ ┐┌ ─ ─ ─ ─ ─ ┐
│ │ Create entry │── ─ ─; │
││
│
│ └───────┬──────┘
│
││
││
││
│
└─────────┘
│
││
│
│
││
││
││
│
└───────────┘└───────────┘└ ─ ─ ─ ─ ──┘└ ─ ─ ─ ─ ─ ┘
┌────────;│
│ ┌───────┴──────┐
│ │ Processing
│
│ └───────┬──────┘
│ ┌───────┴──────┐
Grandchild entries created by each child entry
│ │ Create entry │── ;┌───────────┐┌───────────┐┌ ─ ─ ─ ─ ─ ┐
│ └───────┬──────┘
│
││
│
└─────────┘
│
││
││
│
│
││
│
│
││
││
│
└───────────┘└───────────┘└ ─ ─ ─ ─ ─ ┘
Figure 45. Multiple entries: create-type services in loops
In this way, the ALCS system can be flooded with entries, all of which are trying to request create-type
services – but they cannot do so because there are already too many entries in the system.
You can avoid this problem by ensuring that the parent entry regulates its use of create-type services with
LODIC, and the child entries do not request more than one or two create-type monitor services. Grandchild
entries should not request create monitor services at all.
Holding resources for too long
If a parent entry is holding a record or other resource (or has a general sequential file assigned) while it is
looping, creating child entries, it may lose control because there are already too many entries in the
system. This is similar to, but worse than, the situation shown in Figure 45.
In additon to the danger that other entries might also be waiting to request create-type services, a queue
of entries can build up, all waiting to hold the record or resource or to assign the general sequential file.
This is particularly likely to occur if child or grandchild entries need to hold the record or resource, or to
assign the general sequential file.
Generally, it is wise for application programs to unhold records or other resources (or reserve general
sequential files) before requesting create-type services – especially large numbers of create-type services.
3.8 Entries using SQL, CPI-C, APPC, MQI and TCP/IP
3.8.1 Normal and abnormal termination
SAA defines some automatic processes that occur as part of normal or abnormal termination when
application programs use SAA common programming interfaces such as SQL and CPI-C.
ALCS performs these processes when an entry terminates.
Normal termination: ALCS defines normal termination as any of:
5 Assembler language EXITC monitor-request macro
5 Assembler language BACKC monitor-request macro when there is no calling program.
Chapter 3. Entry management
51
Entry management: SQL, CPI-C, APPC, MQI and TCP/IP
5 C exit function
5 C return function when there is no calling program.
Abnormal termination: ALCS defines abnormal termination as any system error with exit, including:
5 Monitor detected errors that exit the entry.
5 Assembler language SERRC, SYSRA, or SNAPC macro, with exit option.
5 C serrc_op or snapc function, with exit option.
3.8.2 SQL threads and application processes
DATABASE 2 publications refer to threads. Corresponding SAA publications refer to application
processes. Threads and application processes are the same, and correspond to ALCS entries.
For example, SQL associates a cursor with a thread or application process. Similarly, it associates a unit
of recovery with a thread or application process.
In ALCS, SQL cursors and units of recovery are associated with entries. An SQL cursor or unit of
recovery is preserved across ENTER/BACK linkages for one entry, but cannot be passed between entries.
The first SQL statement that an entry executes identifies the entry as an SQL thread. When the entry
terminates, that SQL thread ceases to exist. A normal termination implies a COMMIT for any unit of
recovery not yet terminated; an abnormal termination implies a ROLLBACK for any unit of recovery not yet
terminated (see 3.8.1, “Normal and abnormal termination” on page 51).
ALCS and DATABASE 2 restrict the number of SQL threads that can exist at the same time (within one
ALCS).
See the description of the DB2 parameter in SCTGEN macro in ALCS Installation and Customization.
3.8.3 CPI-C and APPC transaction programs
CPI-C and APPC/MVS publications refer to LU 6.2 conversations between transaction programs,
application programs, or programs. These are all the same, and correspond to ALCS entries (not to
ALCS application programs). An LU 6.2 conversation is preserved across ENTER/BACK linkages for one
entry, but cannot be passed between entries.
Entries that initiate or accept LU 6.2 conversations should deallocate them explicitly before exiting. If they
do not, ALCS takes the following action:
5 When an entry terminates normally, ALCS deallocates any conversations that are still allocated
(provided they are in the correct state).
5 When an entry terminates abnormally, ALCS deallocates with an abend condition (Deallocate_abend)
any conversations that are still allocated.
3.8.4 MQI transaction programs
In MQSeries for OS/390, an open object is identified by its object handle. In ALCS, object handles are
associated with entries. An object handle is preserved across ENTER/BACK linkages for one entry, but
cannot be passed between entries.
Entries that open MQSeries objects should close them explicitly before exiting. If they do not, ALCS
closes any objects that are still open.
52
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry management: SQL, CPI-C, APPC, MQI and TCP/IP
3.8.5 TCP/IP Sockets transaction programs
In TCP/IP for MVS, a socket is identified by its socket descriptor. In ALCS, socket descriptors are
associated with entries. A socket descriptor is preserved across ENTER/BACK linkages for one entry, but
cannot be passed between entries.
Entries that create TCP/IP sockets should close them explicitely before exiting. If they do not, ALCS
closes any sockets that are still open.
Chapter 3. Entry management
53
Storage layout
Chapter 4. Storage management
This section describes ALCS entry and high level language storage management.
4.1 Storage layout
ALCS runs as a single MVS region. The storage associated with the region includes:
Home-address space Contains:
5
5
5
5
5
MVS
ALCS
ALCS application programs
All storage accessible by ALCS application programs
Most of the ALCS tables (including VFA)
Dataspaces
ALCS uses dataspaces to hold tables that it cannot conveniently keep in the
home address space. Application programs cannot access these tables.
Hiperspaces
ALCS can (optionally) use Hiperspace to provide additional buffering for DASD
I/O. This Hiperspace buffering is in addition to the buffering provided by VFA.
The remainder of this section describes the storage in the home address space.
ALCS requests MVS to make the address space non-swappable. After obtaining storage with the MVS
GETMAIN macro, or loading a module, ALCS requests the MVS PGSER macro to fix the storage.
The PAGE parameter of the ALCS generation macro SCTGEN can override this action for some storage
areas. Figure 46 shows where the PAGE parameter can be used, and how the ALCS initialization process
formats the user area of the MVS address space.
Figure 46 (Page 1 of 2). Protected storage locations and characteristics
Below
16MB
Page
fixed
Monitor
ALCS monitor program
Monitor work areas
Monitor tables area
System configuration table
Area for I/O control blocks
Yes
Yes
Yes
No
No
Yes
Yes
Yes
Yes
Yes
DASD I/O
DASD configuration table
Data set descriptor blocks
VFA record locator table
VFA buffer headers
VFA data buffers
Sequential file configuration table
Sequential file buffers
No
Yes
No
No
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Communication
Communication configuration table
Communication hash tables
SLC control blocks, including I/O buffers (Note 1)
SLC I/O message buffers (Note 1)
No
No
Yes
No
No
No
Yes
No
54
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
PAGE= override
ALL or VFA
Storage layout
Figure 46 (Page 2 of 2). Protected storage locations and characteristics
Below
16MB
Page
fixed
PAGE= override
SLC link and channel keypoints (see Figure 47 on page 55)
APPC data and vector table
No
Yes
Application programs
Program configuration table
Module load table
Program hash table
Program control table
Application program load modules
No
No
No
No
Note 2
Yes
Yes
Yes
Yes
Yes
Below
16MB
Page
fixed
PAGE= override
Application storage
Application global area 1
Application global area 2
Application global area 3
Storage units
Note 3
Note 3
No
Note 4
Yes
Yes
Yes
Yes
ALL
ALL
ALL
ALL
Communication
SLC link and channel keypoints (Note 1)
No
No
ALL or PROGRAM
Figure 47. Unprotected storage locations and characteristics
or
or
or
or
GLOBAL
GLOBAL
GLOBAL
STORE
Notes:
1. Storage is allocated only if there is an SLC network.
2. Specify AMODEnn at link-edit time for ALCS to load programs:
Below 16MB, AMODE24 (24-bit addressing)
Above 16MB, AMODE31 (31-bit addressing).
3. Global areas 1 and 2 are below 16MB if you specify AMODE31=(FORCE,NOTGLOBAL) in SCTGEN, or omit
AMODE31. They can be anywhere if you specify:
AMODE31=(FORCE,GLOBAL) or
AMODE31=FORCE
in SCTGEN.
4. Storage units can be anywhere if you specify AMODE31=FORCE.
4.2 Entry storage
1.3.2, “Entry control block” on page 123 describes how each entry requires an area of storage for its ECB.
During processing, the entry requires additional areas of storage; for example, to contain an input
| message, to read or write a DASD record, to contain DECBs, to construct and send a response message,
and so on. The storage for the ECB, together with these additional areas of storage, is called entry
storage.
The ALCS online monitor allocates additional storage to the entry in blocks of a predetermined length,
called storage blocks. ALCS allows up to nine different storage block sizes (Figure 11 on page 8 shows
Chapter 4. Storage management
55
Storage layout
these sizes). For size L0, the block size is the same as the block size for size L1, but only 127 bytes are
available to the application program.
4.3 High-level language storage
ALCS provides services that allow C language application programs to obtain, use, and release standard
size storage blocks (L0, L1, and so on). C language application programs can also access fields in the
ECB. But ALCS does not provide these services for other high-level languages.
The usual way for high-level language (including C) programs to obtain and use storage is by using
dynamic variables. C language programs also obtain storage using the malloc, calloc, and related
functions.
At execution time, high-level language programs obtain and manage storage to contain dynamic variables
and to satisfy C language malloc, calloc, and related function calls. They also obtain and manage
storage for register save areas, for library routines to use as work areas, and so on.
Application programmers do not need to understand in detail how their programs obtain and manage this
storage at execution time. The compiler generates code that obtains the storage, as required, by
requesting ALCS services. The services allocate entry storage so that different transactions use different
storage even when the same program is executing. Note that these services are intended for use only by
compiler-generated code – application programmers should not attempt to invoke the services directly.
4.3.1 Initial storage allocation
When an ALCS ENTER-type service transfers control to a high-level language program, the high-level
language application program obtains a storage area called the initial storage allocation (ISA).
The size of the ISA depends on the version and release of the compiler and library environment, but is on
the order of 100KB.
The ISA storage is released when the high-level language program returns to the calling program, or if it
exits without returning control.
Note that the compiler automatically generates code to obtain and release the ISA. The high-level
language source code does not include any instructions to do these things.
4.3.2 Stack and heap storage
High-level language programs use stack and heap storage to contain dynamic variables.
During execution, the programs obtain and release stack and heap storage when required. The compiler
generates code that manages this storage. This code does not request storage separately for each
| variable. Instead, it requests storage in amounts that are a multiple of 64KB for stack storage and 256KB
| for heap storage.
Note: This is true for programs running under ALCS. In other environments the amounts can be
multiples of a different constant.
| Typically a program can store many variables within 256KB, but it is possible that a single variable (for
| example a large array) can require more than 256KB.
56
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Storage units
| When the program requires stack or heap storage, it requests the required amount (in multiples of 64KB
| or 256KB respectively) from ALCS. ALCS does not distinguish between stack and heap. The only
difference between the two is the way that the high-level language program uses the storage.
Whenever an ALCS ENTER-type service transfers control to an HLL program, the entry needs at least
one HLL storage unit (to hold the ISA) additional to any storage units it is already using. The HLL storage
unit size must be at least large enough to hold the ISA – any remaining space in the first HLL storage unit
is available for use as stack or heap storage.
If the program requires more stack or heap storage than fits in the first HLL storage unit, ALCS can
allocate additional HLL storage units.
You need to be aware that the largest contiguous amount of stack or heap storage that an application can
use is a whole HLL storage unit. You must choose the size for HLL storage units so that they are large
enough to hold the largest variable (which can be an array or structure) that your application uses.
4.4 Storage units
The ALCS online monitor satisfies all requests for entry storage from areas of storage called storage
units. Each entry needs at least one storage unit. This is called the prime storage unit. Both the ECB
and the ECB prefix are in the prime storage unit. The ALCS online monitor uses the ECB prefix to hold
information about the entry (for example, the entry macro trace details). Application programs must not
alter any part of the ECB prefix. The ALCS online monitor keeps critical details of the entry in the ECB
descriptor for the prime storage unit. Application programs cannot modify these details because the ECB
descriptors are in protected storage.
The remainder of the prime storage unit is available to satisfy storage block requests. If the ALCS online
monitor cannot service a storage block request from the prime storage unit, it allocates an overflow
storage unit to the entry. The ALCS online monitor then allocates storage requests from the overflow
storage unit. The entry can overflow into further overflow storage units until its total storage allocation
exceeds its entry storage limit. Overflow storage units do not contain an ECB prefix or an ECB.
|
|
|
|
|
|
|
The first time the ALCS online monitor receives a request to create a DECB for the entry, it allocates a
new overflow storage unit for the entry and reserves the first section for use as part of a DECB frame. The
remainder of this overflow storage unit is available to satisfy storage block requests. The ALCS online
monitor keeps critical DECB data in another part of the DECB frame, referred to as the DECB descriptor,
which is in protected storage. A DECB frame contains multiple DECBs. If the ALCS monitor cannot service
a create DECB request from this DECB frame it will allocate a new overflow storage unit to contain a new
DECB frame.
ALCS uses a different type of storage unit for allocating heap and stack storage in C language application
programs. Figure 48 on page 58 shows entry storage using a prime and overflow storage units, and an
HLL storage unit.
Chapter 4. Storage management
57
Storage units
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Prime storage unit
┌───────────────────┐
│ Storage control │
│ area
│
├───────────────────┤
│
ECB Prefix
│
│
│
├───────────────────┤
│
│
│
│
│
ECB
│
│
│
├───────────────────┤
│ Data collection │
│ area
│
├───────────────────┤
│
│
│ ALCS allocates
│
│ storage blocks
│
│ from this area
│
│
│
│
│
│
│
└───────────────────┘
Overflow storage unit
┌───────────────────┐
│
│
│
│
│
│
│
│
│
│
│ ALCS allocates
│
│
│
│ storage blocks
│
│
│
│ from this area
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
└───────────────────┘
Overflow storage unit
┌───────────────────┐
│
│
│
│
│
DECB frame
│
│
│
│
│
│
│
├───────────────────┤
│
│
│ ALCS allocates
│
│
│
│ storage blocks
│
│
│
│ from this area
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
└───────────────────┘
HLL storage Unit
┌───────────────────┐
│
│
│
│
│
│
│
ISA
│
│
│
│
│
│
│
│
│
├───────────────────┤
│
│
│ ALCS allocates
│
│
│
│ HLL heap and
│
│
│
│ stack storage
│
│
│
│ from this area
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
└───────────────────┘
Figure 48. Entry storage: Prime and overflow storage units
Use the NBRSU= and SUSIZE= parameters of the SCTGEN macro (in the ALCS generation) to specify the
number of storage units and the storage unit size. The storage unit size must be larger than the largest
storage block size. When specifying the storage unit size, consider the following:
5 Too large a storage unit size is economical on time but extravagant on storage. That is, although few
entries need an overflow storage unit, a lot of storage is unused.
5 Too small a storage unit size is economical on storage but extravagant on time. That is, although little
storage is unused, most entries need an overflow storage unit.
5 The maximum amount of heap or stack increment that ALCS can allocate for an HLL program is one
HLL storage unit. Therefore the HLL storage unit must be large enough to contain the largest array
used in an HLL application program or the largest single area requested by malloc or a similar C
language function.
| Specify the storage unit size so that the frequently occurring types of entry need only one storage unit (or
| two if using DECBs).
Note: High-level language application programs need at least one HLL storage unit as well as the prime
storage unit.
Use the ENTSTOR parameter of the SCTGEN macro to set the initial entry storage limit and the maximum
entry storage limit. The entry storage limit for each entry is this initial value, unless the entry requests a
SLIMC monitor service to alter it. SLIMC can decrease the limit, or increase it up to the maximum entry
storage limit. The ALCS online monitor terminates the entry with a dump when the total size of the
storage units required by the entry exceeds the storage limit. Due to fragmentation of storage within the
storage units, the total amount of storage actually in use by the entry can be less than the entry storage
limit when the entry is terminated. Be sure to consider this fragmentation when setting the initial and
maximum entry storage limits.
When ALCS initialization allocates storage for the storage units, it allocates a page as a trap between
each storage unit. The monitor sets the key of these trap pages to 7; it sets the storage unit key to 8.
This provides some protection from corruption of storage due to application program errors.
58
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Storage units
| ALCS uses these trap pages to contain control information, (for example the ECB descriptors and DECB
| descriptors).
Chapter 4. Storage management
59
ALCS services
Chapter 5. ALCS services
This section describes the services that ALCS provides for application programmers.
5.1 ALCS services for communication
Application programs use monitor-request macros to request communication operations. ALCS
Application Programming Reference – Assembler describes the communication monitor-request macros.
They are:
AUTHC
Check whether an entry has authority to access data, ALCS, or application facilities.
COMCC
Updates an entry in the communication table. An application does not have access to the
communication tables and this is the only way to alter an entry in the communication table.
Application programs can alter only selected fields.
COMIC
Obtains information about a communication resource. An application does not have access to
the communication tables and this is the only way to obtain information about a resource. The
CRI does not contain information about the resource.
CRASC
Sends a message to the CRAS printer terminal, or to the CRAS printer terminal associated with
a CRAS display terminal.
DISPC
Builds a multiline output message and optionally sends it to a terminal or printer. DISPC can
invoke the ALCS scrolling package.
ROUTC
Sends a message to a terminal, to another application, or across an ALCS link. The
destination terminal or application can be owned (hosted) by the same ALCS system as the
originating application, or by another system in the same or in a different processor.
SENDC
Sends a message. A macro parameter, the type code, allows a variety of message types to be
transmitted.
SLMTC
Sends a special message to a printer. This monitor-request macro enables the application to
control the printer. The application is notified when the message has been printed
successfully. It is the application's responsibility to handle error conditions that occur on the
printer.
WTOPC
Builds and optionally sends an output message. The message can include a header and
variable text. WTOPC can suppress blanks (space characters) so that two or more blanks are
replaced with a single blank.
The following monitor-request macros are for WTTY communication only. Other application programs
should not use them.
REQSC
Request to send. This monitor-request macro waits for any incoming data on a half-duplex
WTTY line to complete, so that output data can be transmitted.
SCDCC
Checks the status of a WTTY line (before transmitting output data).
STXTC
Sends a block (segment) of a multi-block WTTY message. Use STXTC to send all blocks except
the last. Use SEOMC to send the last block.
SEOMC
Sends the last or only block of a WTTY message.
POLLC
Start input on a WTTY line. Signals that transmission of output data on a half-duplex WTTY
line is complete, and that input data can be accepted.
General-Use Programming Interface
60
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS services
The equivalent C language functions which are implemented in this release of ALCS are:
comic
routc
These are described in ALCS Application Programming Reference – C Language.
5.2 ALCS services for DASD processing
ALCS application programs use ALCS monitor services to request DASD I/O. For a more detailed
description of the ALCS monitor services that initiate DASD I/O to or from:
5 Fixed-file records
5 Pool-file records
5 General file records
refer to:
5 ALCS Application Programming Reference – Assembler
5 ALCS Application Programming Reference – C Language
This following list shows the assembler macros; see the ALCS Application Programming Reference – C
Language for descriptions of the equivalent C language functions.
FILEC
FILNC
FILUC
FINDC
FINHC
FINWC
FIWHC
Files (writes) a DASD record.
Files (writes) a DASD record without detaching the storage block.
Files (writes) a held DASD record and unholds the record.
Finds (reads) a DASD record.
Finds (reads) a DASD record and hold for update.
Finds (reads) a DASD record. The requesting entry loses control until the read completes.
Finds (reads) a DASD record and hold for update. The requesting entry loses control until the
read completes.
The following monitor-request macros allocate and release pool file addresses:
GETFC
RELFC
Gets (dispenses) a pool-file record address, and optionally attaches a storage block.
Releases a pool file address, and optionally detaches the storage block.
The following monitor-request macros request functions related to file addresses:
|
|
|
|
FACEC (application program codes ENTRC FACE)
Calculates a fixed-file address from the fixed-record type number and record ordinal.
FAC8C
Calculates an 8-byte fixed-file address in 4x4 format from the fixed-file record type name or
number and record ordinal.
FA4X4C
Converts a 4-byte file address to an 8-byte file address in 4x4 format, or an 8-byte file address
in 4x4 format to a 4-byte file address.
GDSNC
Opens or closes general data set.
GDSRC
Gets a general data set file address.
HLDTC
Check if a file address at a data level is held by a specified ECB.
RAISA
Calculates a general file address for the first record of a general file; or increments the general
file address by record ordinal increment.
RIDIC
Extracts information about a record ID.
RONIC
UNFRC
Note: Although ALCS provides the RIDIC macro, there is no equivalent C language function.
Extracts information about a fixed, pool or general file address; or calculates the file address
from the record type symbol and record ordinal.
Unhold a held DASD record.
Chapter 5. ALCS services
61
ALCS services
5.3 ALCS services for sequential file processing
Application programs use monitor-request macros to request sequential file operations.
ALCS Application Programming Reference – Assembler describes the sequential file monitor-request
macros.
There are different monitor-request macros for general sequential files and for real-time sequential files.
The following monitor-request macros control ownership of a general sequential file:
TASNC
TCLSC
TOPNC
TRSVC
Assigns a general sequential file to the entry. The general sequential file data set must be
allocated and open. If the general sequential file is assigned to another entry, TASNC waits until
the other entry unassigns it (TRSVC); TASNC then assigns it to the entry. If the general sequential
file is unassigned (reserved), then TASNC immediately assigns it to the entry.
Closes and deallocates a general sequential file data set and unassigns the general sequential
file from the entry.
Allocates and opens a general sequential file data set, then assigns the general sequential file
to the entry.
Unassigns (reserves) a general sequential file from the entry, but does not close or deallocate
the general sequential file data set. This allows another entry to assign the general sequential
file using TASNC.
The following monitor-request macros read and write general sequential file records:
TPRDC
TWRTC
TDTAC
Reads a standard size (L1, L2, ...) record from a general sequential file.
Writes a standard size (L1, L2, ...) record to a general sequential file.
Reads or writes any size record from or to a general sequential file.
The following monitor-request macros write real-time sequential file records:
TOURC
TOUTC
Writes a standard size (L1, L2, ...) record to a real-time sequential file.
Writes any size record to a real-time sequential file.
Another sequential file monitor-request macro is:
TDSPC
Extracts information about real-time, general, and system sequential files.
5.3.1 ALCS C language functions for sequential file processing
The assembler macros in 5.3, “ALCS services for sequential file processing” are all available in ALCS as
equivalent C language functions which can be used for sequential file processing.
ALCS also provides these C language functions, for compatibility with TPF:
tape_open
tape_close
tape_read
tape_write
Open a general sequential file.
Close a general sequential file.
Read a record.
Write a record.
All these C language functions are fully described in ALCS Application Programming Reference – C
Language.
62
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry management: ALCS services
5.4 ALCS entry management services
The following entry-related monitor services are available for application programmers and are described
in ALCS Application Programming Reference – Assembler.
CORHC
CORUC
CREDC
CREEC
CREMC
CRETC
CREXC
DEFRC
DEQC
DLAYC
ENQC
EVNTC
EVNWC
LODIC
POSTC
SAVEC
SYNCC
TASTC
WAITC
Define and hold a resource.
Unhold a resource.
Create a new entry and put it into the defer list.
Create a new entry with attached storage block.
Create a new entry and put it into the ready list.
Create a new entry for scheduling after a time delay.
Has identical function to CREDC.
Defer processing of this entry to allow other entries to proceed. Entries request DEFRC monitor
service to avoid monopolizing resources.
Dequeue (unhold) a resource.
Has identical function to DEFRC.
Define and enqueue (hold) a resource.
Define an event for EVNWC and POSTC.
Wait until an event completes.
Calculates the number of additional entries you can create without performance degradation.
Signal that an event is complete. Some events can require more than one POSTC to complete
them.
Save and restore the contents of requested information (for example registers, ECB work
areas) in a local save stack.
Synchronize access to application global area.
Start TAS (see “Time available supervisor” on page 43).
TASBC stops TAS.
Wait for I/O to complete (see 3.4, “Input/output counter and wait service” on page 47). Some
other monitor services include a request for the wait service; for example, FINWC requests a
DASD record read, followed by a wait.
TPF compatibility
Do not use the SAVEC service in programs that must be compatible with TPF.
Chapter 5. ALCS services
63
Storage management services
5.4.1 C language functions for entry management
Application programs written in the C language can use these entry-related functions provided with ALCS.
They are described in ALCS Application Programming Reference – C Language.
corhc
coruc
credc
creec
cremc
cretc
crexc
defrc
dlayc
lodic
waitc
Define and hold a resource.
Unhold a resource.
Create a new entry and put it into the defer list.
Create a new entry and pass storage block contents to the new entry.
Create a new entry and put it into the ready list.
Create a new entry after a time delay.
Has identical function to credc.
Suspend processing of this entry to allow other entries to proceed. Entries request defrc
monitor service to avoid monopolizing resources.
Has function identical to defrc.
Calculates the number of additional entries you can create without performance degradation
Wait for I/O to complete. Some other functions include a request for the wait service; for
example, finwc requests a DASD record read, followed by a wait (see 3.4, “Input/output
counter and wait service” on page 47).
5.5 ALCS storage management services
Application programs use monitor services to request services related to storage management.
ALCS Application Programming Reference – Assembler describes the storage related monitor services.
They are:
ALASC
ATTAC
| DECBC
|
DETAC
| FLIPC
|
GETCC
RELCC
CRUSA
SAVEC
Get (obtain and attach) a storage block of specified size as the automatic storage block.
Re-attach a storage block after a DETAC.
Create, locate, validate or release a DECB, or swap the storage level in a DECB with a storage
level in the ECB.
Detach the storage block at a specified level and save the block address.
Flip (exchange) the contents of two ECB storage levels. FLIPC also exchanges the contents of
ECB data levels and detail error indicators.
Get (obtain and attach) a storage block of a specified size at a specified level.
Release (detach and free) a storage block attached at a specified level.
Conditionally release (detach and free) storage blocks attached at specified levels.
Save and restore the contents of requested information (for example registers, ECB work
areas) in a local save stack.
TPF compatibility
|
Do not use the SAVEC service in programs that must be compatible with TPF
and the following macro that generates inline code:
LEVTA
Test if a storage block is attached at a specified level.
Note: In additon to the above, many ALCS monitor services either obtain and attach or detach and free a
storage block as part of the requested function. For example, the FINDC (read a DASD record) monitor
service automatically obtains and attaches a storage block.
64
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Application programs written in the C language can use functions provided with ALCS for storage
| management. ALCS Application Programming Reference – C Language describes these functions. They
are:
attac
detac
| flipc
|
getcc
relcc
crusa
| tpf_decb_create
| tpf_decb_locate
| tpf_decb_release
| tpf_decb_swapblk
| tpf_decb_validate
Re-attach a storage block after a detac.
Detach the storage block at specified level and save the block address.
Flip (exchange) the contents of two ECB storage levels. flipc also exchanges
the contents of ECB data levels and detail error indicators.
Get (obtain and attach) a storage block of specified size at a specified level.
Release (detach and free) a storage block attached at a specified level.
Conditionally release (detach and free) storage blocks attached at specified levels.
Create a DECB.
Locate a DECB.
Release a DECB.
Swap the contents of an ECB storage level and a DECB storage level.
Validate a DECB.
There are also functions for generating inline code:
levtest
malloc
calloc
free
Tests if a storage block is attached to a specified storage level
Standard function to get heap storage
Standard function to get heap storage
Standard function to release heap storage.
Note: Any C variables may use stack space.
5.6 ALCS services for global area processing
ALCS supports macros that provide services related to the application global area.
ALCS Application Programming Reference – Assembler describes the following global-related
monitor-request macros.
FILKW
GLOUC
KEYUC
SYNCC
Reverses the effect of GLMOD and keypoints a global record.
Writes keypointable records from the application global area to the database.
Writes keypointable records from the application global area to the database.
Synchronizes access to the application global area.
and the following macro that is not a monitor-request macro:
GLOBZ
Get the address of a directory.
TPF compatibility
When ALCS global area protection is specified, ALCS also supports:
KEYCC and GLMOD To change the PSW protect key to allow storing into global areas 1 or 3
KEYRC and FILKW (option R) To restore the PSW protect key after storing into global areas 1 or 3
If global area protection is not specified, KEYCC, GLMOD, KEYRC, FILKW (option R) have no effect, but show
up in a macro trace.
Chapter 5. ALCS services
65
5.6.1 C language functions for global area processing
The following C language functions are provided with ALCS for global area processing:
glob
global
Addresses an application global field or record.
Addresses, updates, synchronizes or keypoints a global field.
These functions are fully described in ALCS Application Programming Reference – C Language.
5.7 ALCS services for program linkage
Application programs use monitor-request macros to transfer control to other application programs. They
are called program linkage or ENTER/BACK macros.
See ALCS Application Programming Reference – Assembler for descriptions of the program linkage
monitor-request macros listed below:
BACKC
ENTDC
ENTNC
ENTRC
FINPC
FIPWC
Returns control to the calling application program; that is, to the instruction following a previous
ENTRC macro.
Transfers control to an application program or transfer vector, and clears (drops) any return
addresses that previous ENTRC macros (if any) saved. Use this macro when control does not
return to this program.
Transfers control to an application program or transfer vector but does not save a return
address. Use this macro when control does not return to this program. If this program was
entered using ENTRC, then a return address was saved; if a BACKC macro is subsequently
issued, then control returns to that address (the instruction following the ENTRC).
Transfers control to an application program or transfer vector, and saves the return address.
ENTRC saves this return address information in the ECB prefix; Use this macro when control will
return to this program (see BACKC).
Gets the address of an application program.
Finds an application program, moves it into a storage block, and attaches the storage block to
the ECB.
5.7.1 C language functions for program linkage
See ALCS Application Programming Reference – C Language for full descriptions of the corresponding C
language functions:
entdc
entrc
66
Transfers control to an application program without return.
Transfers control to an application program with an expected return.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Overview of ALCS
Chapter 6. Overview of ALCS
This chapter presents an overview of the main features of ALCS.
6.1 What ALCS provides
ALCS is a software interface between customer-written application programs and the MVS operating
system. It provides a number of services that application programs can use. To request these services in
assembler programs you use the ALCS assembler macros described in ALCS Application Programming
Reference – Assembler. In C programs you use the C functions described in ALCS Application
Programming Reference – C Language.
ALCS runs as a job or started task under MVS. It provides real-time transaction processing for airlines
and other industries needing high-volume transaction rates and high system availability. It is typically used
for passenger reservation and ticketing systems.
A typical ALCS operating environment is shown in outline in Figure 49.
Figure 49. ALCS operating environment
Chapter 6. Overview of ALCS
67
Overview of ALCS
6.2 Agent sets
There can be several thousand terminals linked to the same ALCS system. These terminals are called
agent sets. If your installation uses NetView*, you can also use NetView operator identifiers (operator
IDs) as agent sets.
An ALCS agent set intended for operators, programmers, and data administrators is called a computer
room agent set (CRAS).
Some CRAS terminals have specific uses:
Prime CRAS
This is the primary terminal that the operator uses to control ALCS. The Prime CRAS accepts all
operator commands.
Receive Only CRAS (RO CRAS)
This is a printer designated to receive messages sent by ALCS.
Alternate CRAS terminals
These terminals accept some, but not all of the operator commands. ALCS is usually set up so that if
the current Prime CRAS fails, it automatically switches to an alternate CRAS terminal, which then
becomes the Prime CRAS.
Alternate CRAS printers
There can be a number of alternate CRAS printers. ALCS is usually set up to switch to one of these if
the RO CRAS fails.
6.3 Functions performed by ALCS
ALCS (working with other system software, such as MVS and VTAM) performs the following functions:
Controls incoming and outgoing messages
ALCS controls the transmission of all messages between end-user terminals and application
programs.
Manages processor storage and file storage
ALCS controls the allocation and release of processor storage and DASD storage.
Queues work to be done on messages
ALCS maintains lists of work to be done on all messages currently being processed.
Controls input and output to DASD
ALCS controls all input and output operations to DASD, usually on request of the application
programs.
Checks errors and recovers where possible
ALCS identifies, logs, and resolves (where possible) all permanent and transient errors.
Communicates with the operator
ALCS allows the operator to issue commands to request information, or to change operating
parameters. It also provides information to the operator when this becomes necessary.
Allows switch-over to standby system
ALCS is designed so that, if necessary, the operator can switch over to a standby version of ALCS
with very little disruption.
68
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Overview of ALCS
Provides online maintenance and customization
Many installations require the ALCS system to be available 24 hours a day, 7 days a week. All ALCS
maintenance facilities can be run at the same time as other work, without disrupting applications.
6.4 Processing a message
The following series of figures shows how ALCS uses an application program to process a simple enquiry,
for example, an agent asking if there are any vacancies on a flight, or a bank officer querying a customer
balance in a bank account.
Most units of work are initiated by messages received from terminals (Figure 50). These units of work
are called entries. (On many terminals the agent presses the ENTER key to send the message.)
Figure 50. Agent presses the ENTER key to send a message
6.4.1 Entry control block
When ALCS receives a message, it assigns a storage area called an entry control block (ECB) to that
message (Figure 51 on page 70). The ECB contains a pointer to the message.
Chapter 6. Overview of ALCS
69
Overview of ALCS
Figure 51. ALCS creates an ECB for the message
The ECB is an interface between ALCS and application programs. ALCS uses part of the ECB for saving
information. Other parts are available for use by application programs as small work areas. Another part
is used for holding the addresses of areas of storage used by the program.
6.4.2 Selecting a program
ALCS examines the originating terminal address of the message, and message contents, and selects the
appropriate application program to process the message (Figure 52).
Figure 52. ALCS selects a program for the ECB
6.4.3 Program flow
The program starts processing the message. At some stage it needs to read data from DASD. It does
not read DASD directly but requests an ALCS service to perform the read, for example, FINDC (findc).
When it has done this, the application program usually suspends itself, for example by requesting an
ALCS wait service, and control returns to ALCS (Figure 53 on page 71).
70
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Overview of ALCS
Figure 53. Program requests data from a DASD record
When this happens, ALCS stores in the ECB the contents of the current program registers and information
such as the address of the next program instruction.
Data is held on DASD in the form of records. Records are explained in 6.7, “Direct access files” on
page 75.
After ALCS has initiated a read of the DASD record, it checks for other entries to start or continue
processing.
Chapter 6. Overview of ALCS
71
Overview of ALCS
6.4.4 ALCS reactivates the program
When ALCS detects that the read of the DASD record has completed, it restarts the program from the
point stored in the ECB. The program can then continue as if there had been no interruption. ALCS puts
a pointer in the ECB to the data it has read (Figure 54).
Figure 54. Program receives data from a DASD record
An ECB can have up to 16 pointers to data read from DASD. The 16 fields containing these pointers are
called data levels.
6.4.5 Transferring control to another program
An application program need not carry out all the processing itself, but can transfer control to another
program to perform a specific action or task (Figure 55). The called program can return back to the first
program or can in turn call other programs.
Figure 55. Program transfers control to another program
72
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Overview of ALCS
Application programs transfer control by requesting ALCS transfer services (see -- Heading 'TRANSF'
unknown --). In addition, high-level language programs can call functions defined in other application
programs without losing control.
6.4.6 Sending a message
The application program, after processing data read from DASD, creates an output message. ALCS
displays this message on the terminal where the input originated (Figure 56).
Figure 56. ALCS sends a message to the terminal
After it passes the message to ALCS, the application program normally exits the entry. ALCS releases
the ECB, and any associated storage used by the entry, as part of the exit processing.
6.5 Using information from previous messages
One ECB is associated with each message. Some transactions might require the application program to
use information from several messages received from the same terminal. (Messages contain the
originating terminal address.)
In these cases, the application must retain information from a series of messages received from a single
terminal. It can do this by storing information in DASD records.
The IPARS reservation application (see 6.10.1, “IPARS applications” on page 81) holds data relating to a
particular terminal in a record called the agent assembly area (AAA) record. The IPARS application
reads this record, updates the record and then writes it back to DASD (by requesting an ALCS write
service, for example FILEC (filec)).
Chapter 6. Overview of ALCS
73
Overview of ALCS
6.6 Application programs in ALCS
ALCS might have to restart the same application program many times, from different points in the
program. Application programs must be written in such a way that ALCS can do this, and can also use
the same program concurrently for many entries.
Such programs must be reentrant. A reentrant program must not modify any storage located within the
program itself. Instead, it must reference switches, indicators, or counters in an application work area in
the ECB, or other storage owned exclusively by the entry. In this case, ALCS can suspend, abend,
initiate, or resume processing of any number of entries at any point in their processing.
Because ALCS uses the ECB to control reentrant application programs, these programs are also called
ECB-controlled programs.
6.6.1 Obtaining working storage
Most programs need work areas; for example, to hold working data or intermediate results of calculations.
In high-level language programs, you obtain working storage automatically, see 8.15,
“Automatically-allocated storage” on page 132.
Assembler programs do not have this facility, so ALCS provides macros that programs can use to get
blocks of storage. You might also use these in C programs when you are creating DASD records.
When ALCS allocates a block of storage, it sets a pointer to it in the ECB in the same way as to the
message area. The block of storage is “owned” by the entry (Figure 57).
Figure 57. Working storage
ALCS allocates storage in fixed-size pieces called blocks. There are up to 9 different block sizes allowed
by ALCS (see note 1 on page 75). These are shown in Figure 58.
Figure 58 (Page 1 of 2). Block sizes
Block
size
Number of bytes of application data
Size recommended for compatibility with
TPF
L0
Up to 32K, 127 minimum
127 bytes
74
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Overview of ALCS
Figure 58 (Page 2 of 2). Block sizes
Block
size
Number of bytes of application data
Size recommended for compatibility with
TPF
L1
Up to 32K, 381 minimum
381 bytes
L2
Up to 32K, 1055 minimum
1055 bytes
L3
Up to 32K, 4000 minimum
L4
Up to 32K
L5
Up to 32K
L6
Up to 32K
L7
Up to 32K
L8
Up to 32K
4095 bytes (required for TPFDF)
TPF compatibility
To be compatible with TPF, all installations should use block sizes L0, L1, L2, and L4 with the
recommended values shown in Figure 58 on page 74.
An ECB can have up to 16 pointers to blocks of working storage. (This does not include storage that has
been allocated automatically.) These pointers are called storage levels. ALCS clears the pointers when
it releases the storage blocks (for example, when an application exits an entry).
| In addition to the 16 storage levels an ECB can also dynamically create one or more DECBs each of
| which will contain a storage level. For more information see 8.18, “Data event control blocks (DECBs)” on
| page 136.
6.7 Direct access files
Data is held on DASD in fixed-size records. ALCS supports 8 different record sizes. These are the same
as block sizes L1 through L8 shown in Figure 58 on page 74. (There are no DASD records of size L0.)
Notes:
1. The system programmer defines storage block and DASD record sizes during system generation.
Your installation might use only some of the different block and record sizes, for example, L1, L2, L3,
and L4.
2. Storage blocks and DASD records are physically larger than the sizes shown in the tables. Records
contain additional information that ALCS uses for control purposes.
DASD records are classified into three main classes: fixed-file records, pool-file records, and general
file records.
6.7.1 Fixed-file records
The system programmer in your installation allocates some of the records on DASD as fixed-file records.
Fixed-file records can be used by application programs when the number and size of records needed can
be calculated in advance.
Chapter 6. Overview of ALCS
75
Overview of ALCS
Fixed-file record type
The system programmer can allocate records to belong to a particular fixed-file record type. A fixed-file
record type is identified by a symbol and a number. By convention, the symbol starts with a hash sign (#)1
followed by from five to seven characters, for example #CONV1, #WORK2. The number can be any
number from 1 to 65 535. (ALCS requires a very minor modification to support more than 4094 record
types, see your IBM program support representative).
Within a fixed-file record type, the application program can identify a particular record by its ordinal
number (Figure 59).
┌──────┐
│
│
│
│
│
│
└──────┘
┌──────┐
│
│
│
│
│
│
└──────┘
┌──────┐
│
│
│
│
│
│
└──────┘
┌──────┐
│
│
│
│
│
│
└──────┘
┌──────┐
│
│
│
│
│
│
└──────┘
. . . . .
1
2
3
4
. . . . .
Figure 59. Fixed file ordinals
File addresses
|
|
|
|
ALCS locates records on DASD by means of a 4-byte file address. ALCS provides application programs
with services that calculate the file address of a fixed file record and return it as a 4-byte file address (or
an 8-byte file address in 4x4 format for use with a DECB). The application supplies the record type and
the ordinal number. For more details see 7.1, “Using direct access files” on page 82 and 8.18, “Data
event control blocks (DECBs)” on page 136.
Miscellaneous file records
To allow programs to use small numbers of fixed-file records, many installations define some
miscellaneous fixed-file record types. These are identified by names such as #MISC1, #MISC2, and so
on, where the numbers, 1, 2, ..., identify the record size (L1, L2, and so on). Some installations use
#MISCS and #MISCL for sizes L1 and L2.
The system programmer can allow individual application programs to use a range of ordinals from one or
more of the miscellaneous file records. This saves having fixed-file records allocated specifically for an
application.
6.7.2 Pool-file records
The system programmer also creates pools of records. Each pool contains records of one particular size
(L1, L2, and so on). Records in these pools are called pool-file records.
The records in a pool file can be either short-term pool-file records or long-term pool-file records, as
follows:
1
This character might appear differently on your equipment. It is the character represented by hexadecimal 7B.
76
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Overview of ALCS
Short-term pool-file records
These are pool-file records (of various sizes) that ALCS makes available (“dispenses”) to applications for a
short period of time (usually seconds or minutes, typically the life of an entry).
Because an installation only has a limited number of short-term pool records defined, short-term pool-file
records are only used to hold data temporarily. When all the short-term records of a particular size
become used up, ALCS reuses the oldest ones and the data in these records is overwritten.
Short-term pool-file records are used by applications where the integrity of the data is not critical. For
example, an application could use them to build up an output message before sending it to a terminal.
Long-term pool-file records
These are pool-file records (of various sizes) that any application can use when the integrity of the data is
critical. Once ALCS has dispensed a long-term pool-file record to an application, it will not dispense the
record again unless a number of conditions are met. See “When ALCS redispenses a long-term pool-file
record” on page 79.
Long-term pool-file records are suitable for holding long-term data where the amount of data is not known
in advance, but where a loss of data would cause a serious problem. For example, the IPARS reservation
application uses long-term pool-file records for passenger data in the passenger name record (PNR).
Applications should release a long-term pool-file record when the data is no longer needed; ALCS can
then dispense the pool-file record to another application. (But see 6.7.4, “Recovering long-term pool-file
records” on page 78.)
6.7.3 Chains of pool-file records
An application identifies an individual pool-file record by its file address. ALCS supplies this 4-byte file
address when it dispenses a pool-file record to an application.
ALCS keeps track of which pool-file records it has dispensed, but applications share this responsibility.
Applications need to record details of each pool-file record that they have used. They normally do this by
putting the file address of the pool-file record in another record, thus creating a chain of two or more
records. The application can put the file address in either:
1. A fixed-file record (Figure 60).
┌──────┐
┌──────┐
│
│
│
│
│
│────────────;│
│
│
│
│
│
└──────┘
└──────┘
Fixed-file
Pool-file
record
record
Figure 60. Fixed-file record containing a file address of a single pool-file record
Chapter 6. Overview of ALCS
77
Overview of ALCS
2. A pool-file record that is addressed by another pool file record, or by a fixed-file record (Figure 61).
┌──────┐
┌──────┐
┌──────┐
│
│
│
│
│
│
│
│────────────;│
│─── . . . ────────;│
│
│
│
│
│
│
│
└──────┘
└──────┘
└──────┘
Fixed-file
Pool-file
Pool-file
record
record
record
Figure 61. Fixed-file record addressing a chain of pool-file records
A record can contain one or many addresses of other records. This can create very complex structures
(see ALCS Concepts and Facilities). All such structures must start from a fixed-file record at the top
(base) of the structure.
6.7.4 Recovering long-term pool-file records
At regular intervals (every few days, or every week), an installation must recover long-term pool-file
records that have been used by applications but which the applications have since released.
ALCS provides a utility program, called Recoup, to do this. In addition to checking that the pool-file
record has been released, ALCS checks that the record is not part of a chain. This is called chain
chasing.
Chain chasing
Recoup examines each fixed-file record to see if it contains an address of a long-term pool-file record; if
so, it notes that this addressed pool file record is still in use. If the pool-file record contains an address of
another pool-file record, it notes that this other pool-file record is also in use, and so on.
It follows chains of pool-file records (see Figure 61) until it comes to a pool-file record that does not
contain an address of another pool-file record.
When it has examined all the records, Recoup creates a new, up-to-date, table of long-term pool-file
records that are available for ALCS to dispense to application programs.
Notes:
1. The system programmer must define where the file address fields are in each type of fixed-file record
and in each pool-file record where these are part of a chain. When you use long-term pool-file
records you must give the system programmer sufficient information to do this.
2. Recoup can be run while ALCS is operating normally.
Alternative method of recovering long-term pool records
Occasionally, ALCS installations can not or do not run Recoup in time to prevent long-term pool depletion.
This can happen if the operations staff simply fail to run Recoup. But it is more likely to happen because
unexpectedly high load, or application error, causes pool depletion to occur much sooner than expected.
ALCS already includes facilities to reduce the possibility of unexpected pool depletion. In particular:
5 ALCS monitors the long-term pool dispense rate and warns if the current rate will deplete pool in less
than 24 hours.
5 ALCS controls the maximum number of dispenses that a single entry can perform.
78
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Overview of ALCS
However ALCS installations sometimes require an “emergency” method to recover long-term pool. If an
ALCS system does run out of long-term pool, the application will not work.
An ALCS system that has completely run out of long-term pool can continue functioning by redispensing
long-term pool records that have been released since the last Recoup.
To do this, ALCS maintains a list of released file addresses, in release order. If a pool is depleted, ALCS
will start to redispense file addresses from this list. See ALCS Installation and Customization for an
explanation of how to implement this facility using the pdulogstream parameter of the SCTGEN macro.
When ALCS redispenses a long-term pool-file record
Before ALCS redispenses a long-term pool-file record, all the following conditions must be met:
5 An application has released the record.
5 The record is not referenced by another record (the record is not in a chain).
5 Recoup has been run and has identified the record as fulfilling the two conditions mentioned above.
ALCS dispenses long-term pool-file records on a cyclical basis, so there will be an additional delay before
it redispenses a particular long-term pool-file record. These conditions make it almost impossible for
ALCS to dispense a long-term pool-file record that is currently in use.
6.7.5 Application global area
Some existing applications written for use with ALCS, TPF, or predecessor systems, keep data in an area
of processor storage called the application global area. You are recommended not to develop new
applications that keep data in the application global area. However, if you are updating existing programs
or you are writing new applications that coexist with existing programs, you might need to access data in
the application global area. 7.5, “Global records and fields” on page 101 describes how to do this.
6.7.6 General files and general data sets
General files and general data sets (GDSs) contain DASD records that application programs can read and
write. In addition, batch programs can read records from and write records to these files. You can use
general files and GDSs when application programs need to pass information to or receive information
from, offline programs.
In some predecessor systems general files and GDSs are different, and application programs must use
different methods to access them. In ALCS they are physically identical, but ALCS supports the two
methods to access them. The application program must access a file as either a general file or a GDS
(and not mix the two access methods).
Note: In new applications you might prefer to use APPC, SQL, or MQI instead of general files. See -Heading 'APPC' unknown --, 7.7, “Using Structured Query Language (SQL)” on page 109, and -- Heading
'MQI' unknown --.
General files
Application programs identify a general file by the general file number – a decimal number in the range 1
through 255. (One general file, number 0, is reserved for use by ALCS itself.)
ALCS provides application programs with a service that calculates the 4-byte file address of a general file
record. (The application program provides the general file number and the ordinal number of the record.)
Chapter 6. Overview of ALCS
79
Overview of ALCS
General data sets
Application programs identify a general data set by the data set name.
ALCS provides application programs with a service that calculates the 4-byte file address of a general
data set record. (The application program provides the data set name and the ordinal number of the
record.) ALCS also provides services to open and close general data sets.
6.7.7 Virtual file access
ALCS retains records in processor storage after they have been read from DASD or written to DASD (or
both). ALCS retains the records in buffers called virtual file access (VFA) buffers. (See ALCS
Concepts and Facilities for more information about VFA.) The system programmer specifies the number
of VFA buffers that ALCS allocates.
Normally, there are many more records on DASD than there are VFA buffers. ALCS manages the VFA
buffers so that the most recently referenced records remain in buffers. When an application program
reads a record, ALCS provides a copy from the VFA buffer (if the record is in a buffer) or reads the record
from DASD (if the record is not in a buffer).
The use of VFA buffers is transparent to the application program. The program does not know (and
cannot find out) if a particular record is in a VFA buffer.
6.8 Sequential files
Sequential files contain records that are written (and subsequently read) in sequence, not randomly. In
this way they are equivalent to magnetic tapes. ALCS sequential files are identified by 3-character names.
There are two types of sequential file that application programs can use:
Real-time sequential files
These files are opened automatically when ALCS is started. Any application program can write
records to real-time sequential files, but cannot read records from them. Such files are useful for
logging.
General sequential files
An application must open a general sequential file and must specify whether it is opening the file for
input (to read records) or output (to write records). Several applications can share the use of the
same general sequential file, but they must do this in a controlled way. See 7.4, “Using sequential
files” on page 98.
6.9 Communication with users, other systems, and other applications
An ALCS system does not exist in isolation. There are several areas where ALCS interacts with areas
outside the main computer installation:
5 Terminals in remote locations, connected over a VTAM* network
5 Connections to other installations using a Synchronous Link Control (SLC) link, particularly those to a
SITA** or ARINC** network
5 Connections to other installations using an LU 6.1 link
5 Connections to other installations or devices using Transmission Control Protocol/Internet Protocol
(TCP/IP)
80
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Overview of ALCS
5 NetView operator identifiers
5 Advanced program-to-program communications (APPC), Message Queue Interface (MQI), and so on.
Terminals on a VTAM network are controlled by NetView or VTAM commands. Terminals connected
using SLC are controlled by ALCS operator commands.
Each communication resource is identified by a communication resource identifier (CRI) and
communication resource name (CRN).
6.10 ALCS applications
An ALCS application performs some useful user-related task. For example, in an airline environment
typical applications are reservations, message switching, departure control, and so on. Each application
usually arranges for processing to be carried out by a number of application programs which transfer
control between themselves, as shown in Figure 62.
Application
───────────
┌──────┐
┌──────┐
┌───;│ D123 │───;│ D124 │──; ... ──┐
(Common programs)
│
└──────┘
└──────┘
│ (Common program)
Reservations ──────┐
├───; .......
│
│
┌──────┐
┌──────┐
│
┌──────┐
┌──────┐
│
┌──────┐
Departure control ─┼──;│ UII1 │─ ─;│ UII2 │───┼───;│ G113 │───;│ G114 │──; ... ──┼──;│ UIO1 │
│
└──────┘
└──────┘
│
└──────┘
└──────┘
│
└──────┘
Ticketing ─────────┘
input
routing
├───; .......
│
output
edit
program
│
┌──────┐
┌──────┐
│
edit
program
└───;│ H223 │───;│ H224 │──; ... ──┘
program
└──────┘
└──────┘
Message switching ───; (other application programs)
Figure 62. Example ALCS applications and their constituent programs
ALCS applications written in assembler often make use of common programs for input and output editing
of messages, as shown in Figure 62.
6.10.1 IPARS applications
Two sample applications are supplied with ALCS. Together they constitute the International Programmed
Airlines Reservation System (IPARS). They are:
5 IPARS reservations application
5 IPARS message switching application.
Installations can use one or both of these applications to test that ALCS is working correctly. You can use
them as supplied, or as a basis for more comprehensive applications of your own.
Chapter 6. Overview of ALCS
81
Data
Chapter 7. Data in ALCS
This chapter describes data that is available to ALCS application programs, including:
5 The real-time database
5 Sequential files
5 Data held on other systems (for example, relational databases).
It also describes how your application program can access and update such data.
7.1 Using direct access files
The ALCS real-time database consists of records on direct access storage devices (DASD). The three
types of record are:
5 Fixed-file records
5 Pool-file records
5 General file records and general data set records.
This section provides an overview of ALCS DASD support. It describes file addresses within ALCS (fixed
file, pool file, and general file) and explains the record hold facility.
7.1.1 File addresses
Each record on DASD is identified by a 4-byte file address.
|
|
|
|
|
|
|
TPF compatibility
Applications that require compatibility with TPF can use an 8-byte file address, by using a DECB data
level. ALCS applications that use a DECB data level must use an 8-byte file address in 4x4 format.
You can obtain an 8-byte file address by specifying a DECB address when you request a service to
get a file address (see below), or by requesting the FA4X4C (tpf_fa4x4c) service to convert an existing
4-byte file address to an 8-byte file address in 4x4 format. For more information about the 8-byte file
address in a DECB see 8.18.5, “8-byte file address support” on page 139.
When an application program requests a DASD I/O operation, it must tell ALCS the file address of the
| record it wants to read or write. Application programs can get a file address in one of the following ways:
|
|
5 For fixed-file records, request the FACE (face) or FACS (facs) service to obtain a 4-byte file address.
Request the FAC8C (tpf_fac8c) service to obtain an 8-byte file address in 4x4 format. You provide the
fixed file record type and ordinal number of the record you want.
|
|
|
5 When writing a pool-file record, request the GETFC (getfc) service specifying an ECB level to get the
4-byte file address of an unused pool file record. Request the GETFC (getfc) service specifying a
DECB address to get the 8-byte file address in 4x4 format of an unused pool file record. When
reading a pool-file record that is chained from another record, get the file address from the “refer-from”
record (see 6.7.3, “Chains of pool-file records” on page 77).
|
5 For general files, request the RAISA (raisa) service to calculate the 4-byte file address.
|
|
|
5 For general data sets, request the GDSNC (gdsnc) and GDSRC (gdsrc) services specifying an ECB data
level to calculate the 4-byte file address. Request the GDSNC (gdsnc) and GDSRC (gdsrc) services
specifying a DECB address to calculate the 8-byte file address in 4x4 format.
82
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
7.1.2 Standard record header
ALCS has a standard format for the first 16 bytes of all records on fixed files, pool files, and general files.
This is shown in Figure 63 on page 83.
Record ID
│
Record code check
│
│ Control byte
│
│
│
Forward chain
Backward chain
│
│
│ Program stamp
│
│
│
│
│
│
│
│
D
D
D
D
D
D
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ I
D │ X │ C │ X
X
X
X │ F
F
F
F │ B
B
B
B │
├───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┤
│
│
│
Area for user data
│
:
:
:
:
│
│
└───────────────────────────────────────────────────────────────┘
Figure 63. Standard record header
The standard header contains the following fields:
Record ID
This 2-byte field contains the record identifier (record ID). Conventionally, the record ID indicates the
kind of data in the record. For example, airlines reservations applications keep passenger name
records in long-term pool-file records with an ID of 'PR'.
When application programs read records, ALCS optionally checks that the ID is the same as that
which the application program expects. See 7.2, “Reading and writing DASD records” on page 84.
When ALCS dispenses a pool-file record to an application program, it uses the record ID to select the
appropriate type of record – that is, a long-term or short-term pool-file record of a particular size (L1,
L2, and so on).
Some systems implement logging (using an installation-wide exit) on the basis of the record ID. See
ALCS Installation and Customization for details of installation-wide exits.
Note: Up to 10 record types can share the same record ID. To distinguish between them, ALCS
allows a record ID qualifier: a number between 0 and 9.
Record code check
This 1-byte field contains the record code check (RCC). The RCC is intended as an aid in detecting
incorrect chaining of records with the same record ID (particularly passenger name records, which can
number millions).
A mismatch shows that the chain is broken, probably as a result of an application program releasing a
record too soon. A false match cannot be excluded, but the RCC should give early indication of a
chaining problem.
Control byte
ALCS ignores this 1-byte field. (There was a standard use for this field in IPARS, but this standard is
now obsolete.)
Program stamp
ALCS stores in this 4-byte field the name of the application program that writes the record.
Forward chain
If the file uses standard forward chaining (see 6.7.3, “Chains of pool-file records” on page 77), this
4-byte field contains the file address of the next record in the chain. In the last (or only) record in a
chain this field contains binary zeros.
Chapter 7. Data in ALCS
83
Data
Backward chain
If the file uses standard backward chaining (see 6.7.3, “Chains of pool-file records” on page 77) this
4-byte field contains the file address of the previous record in the chain. In the first (or only) record in
a chain this field contains the file address of the last record in the chain.
In assembler programs, use the STDHD DSECT to reference the standard record header. See the ALCS
Application Programming Reference – Assembler for details.
In C programs, use the header file <c$stdhd.h> to reference the standard record header. See the ALCS
Application Programming Reference – C Language for details.
The following sample structure shows the standard record header as it could be defined in a C language
program. See ALCS Application Programming Reference – C Language for more details.
struct sample_record_header
{
/V
VV
Example of a standard header area
V/
char
record_ID[2];
/V
unsigned char
rcc;
/V
unsigned char
control_byte;
/V
char
program_stamp[4]; /V
long int
forward_chain;
/V
long int
backward_chain;
/V
};
Record ID
Record code check
Control byte
Program stamp
Forward chain file address
Backward chain file address
V/
V/
V/
V/
V/
V/
Note: Records used with the IBM database facility (TPFDF) program product use an extended record
header.
7.2 Reading and writing DASD records
An ECB contains 16 data levels and 16 corresponding storage levels. Each level is identified by a
defined symbol: D0 for level 0, D1 for level 1, through to DF for level 15.
| An ECB may also dynamically create one or more DECBs, each of which contains a data level and
| corresponding storage level.
An application uses a data level and a corresponding storage level whenever it reads or writes a DASD
record. 8.4, “ECB data levels and storage levels” on page 127 describes the data and storage level fields
in more detail but their use is described here.
Each data level contains the following information about a DASD record:
|
5 2-byte record ID
5 1-byte record code check (RCC) character
5 4-byte file address (ECB level) or 8-byte file address in 4x4 format (DECB level).
When an application has read a DASD record, or when it is preparing a record for writing to DASD, it
| holds the record image in a storage block which is attached to the ECB or a DECB (see 8.16, “Storage
blocks” on page 133).
84
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
| Information about an attached storage block is held in a storage level, which can contain the following
information:
5 4-byte storage block address
5 2-byte storage block size field (length in bytes of the user area of the block)
5 2-byte storage block size indicator (L1, L2, ..., L8).
7.2.1 Reading DASD records
When an application program requests an ALCS service to read a DASD record, it specifies the file
| address of the record it wants to read in any data level which is free (either from the 16 in the ECB (D0
| through DF) or from a DECB). (An application can get a DASD file address in various ways, see 7.1.1,
“File addresses” on page 82.)
The application can optionally also specify the record ID, or the record ID and the RCC value of the DASD
record. If the application does not require ALCS to check these fields, it sets them to binary zeros. See
Figure 64.
Data level n
┌
│
│
│
│
│
└
ECB
┌──────────────────┐
:
:
│
│
├──────────────────┤
│ Record ID
│
├──────────────────┤
│ RCC
│
├──────────────────┤
│ File address
│
├──────────────────┤
│
│
:
:
└──────────────────┘
(Optional)
(Optional)
| Figure 64. Contents of an ECB data level before a DASD read request
Note: There is a reserved 1-byte field (not shown in the figure) between the RCC and file address fields.
When an application program requests a read service, for example, FINDC (findc), it specifies the data
| level (D0 through DF or the DECB address) that contains the information.
ALCS attempts to read the specified record. If successful, it gets a storage block of the appropriate size
| (L1, L2, ..., L8) and reads the DASD record into this block. It attaches this storage block to the ECB or
| DECB and loads the address of the attached storage block, the storage block size, and the storage block
size indicator (L1, L2, ..., L8) into the corresponding storage level fields. See Figure 65 on page 86.
Chapter 7. Data in ALCS
85
Data
Data level n
┌
│
│
│
│
│
└
┌
Storage level n │
│
│
│
│
└
ECB
┌───────────────────┐
:
:
│
│
├───────────────────┤
│ Record ID
│
├───────────────────┤
│ RCC
│
├───────────────────┤
│ File address
│
├───────────────────┤
│
│
│
│
├───────────────────┤
┌────────────────────┐
│ SB address
│ ── ── ── ── ── ── ; │
│
├───────────────────┤
│
│
│ SB size
│
│
│
├───────────────────┤
│
│
│ SB size indicator │
│
│
├───────────────────┤
└────────────────────┘
:
:
Storage block containing
│
│
the DASD record image
└───────────────────┘
Figure 65. Data level and storage level after a successful DASD read
If ALCS cannot read the required DASD record, or if either of the optional fields (record ID and RCC) do
not match those in the DASD record, ALCS reports an error. See 9.3.1, “Error indicators in the ECB and
DECB” on page 152 for a description of how an application tests for these errors.
7.2.2 Writing DASD records
Before an application requests an ALCS service to write a DASD record, it must store the record image in
| a storage block attached to the ECB or a DECB. (It can get an empty storage block, and attach it at a
specified level using a GETCC (getcc) service, as described in 8.16, “Storage blocks” on page 133.)
The GETCC (getcc) service puts the address of the storage block, the storage block size, and the storage
block size indicator in the storage level fields (see Figure 66). The application must also specify the file
address and the record ID in the corresponding data level. It can optionally specify the RCC.
Data level n
┌
│
│
│
│
│
└
┌
Storage level n │
│
│
│
│
└
ECB
┌───────────────────┐
:
:
│
│
├───────────────────┤
│ Record ID
│
├───────────────────┤
│ RCC
│ (optional)
├───────────────────┤
│ File address
│
├───────────────────┤
│
│
│
│
├───────────────────┤
┌────────────────────┐
│ SB address
│ ── ── ── ── ── ── ; │
│
├───────────────────┤
│
│
│ SB size
│
│
│
├───────────────────┤
│
│
│ SB size indicator │
│
│
├───────────────────┤
└────────────────────┘
:
:
Storage block containing
│
│
the DASD record image
└───────────────────┘
Figure 66. Data level and storage level before a DASD write request
When an application program requests a write service, for example, FILEC (filec), it specifies the storage
| level and data level (D0 through DF or the DECB address) that contains the information.
86
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
If the file address is not valid, or if the Record ID or (optional) RCC field does not match the corresponding
fields in the DASD image in the storage block, this is an error. With most write services, ALCS does not
return to the entry, so the application cannot test this. However one write service, FILNC (filnc) returns
error information which the application can test, see 9.3.1, “Error indicators in the ECB and DECB” on
page 152.
7.2.3 Sequential files
Some sequential file services also use a data level. The TOUTC (toutc) service requires the application to
store in the data level the storage address and data length for the write. Also, TDSPC (tdspc) can return
status information in a data level. See 9.2, “The ALCS wait mechanism and error processing” on
page 148.
7.3 Serialization
ALCS is a multiprogramming and multiprocessing transaction processing system. (Systems like this are
also called parallel processing or multi-user systems.) This means that there can be many entries
accessing the data base at the same time. This requires a serialization process to ensure consistent
database updates.
Use of locks
Consider, as an example, two entries which each need to update the same DASD record. Because the
two entries can be processing at the same time, one of the updates can be lost, see Figure 67.
Entry 1
───────
┌──────────────────┐
│ Read DASD record │
│ without hold
│
└──────────────────┘
│
D
┌────────────────────┐
│ Update DASD record │
└────────────────────┘
│
D
┌───────────────┐
│ Write updated │
│ DASD record
│
└───────────────┘
Entry 2
───────
┌──────────────────┐
│ Read DASD record │
│ without hold
│
└──────────────────┘
│
D
┌────────────────────┐
│ Update DASD record │
└────────────────────┘
│
D
┌───────────────┐
│ Write updated │
│ DASD record
│
└───────────────┘
Figure 67. Reading DASD records without holding the file address - updates performed by either entry can be lost.
After such a sequence, the update of entry 1 would be lost.
To prevent this, the program must serialize the updates using a lock, The previous sequence becomes
that shown in Figure 68 on page 88.
Chapter 7. Data in ALCS
87
Data
Entry 1
───────
┌──────────────────┐
│ Read DASD record │
│ with hold
│
└──────────────────┘
│
D
┌────────────────────┐
│ update DASD record │
└────────────────────┘
│
D
┌──────────────────┐
│ Write and unhold │
│ the DASD record │
└──────────────────┘
. . . . . . . . . . . . . . .
Entry 2
───────
┌──────────────────┐
│ Read DASD record │
│ with hold
│
└──────────────────┘
│
(ALCS does not provide
│
the held DASD record
until it is unheld)
│
│
. . . . . . . . . . . . . .
D
┌────────────────────┐
│ ALCS provides the │
│ DASD record (held) │
└────────────────────┘
D
┌────────────────────┐
│ update DASD record │
└────────────────────┘
D
┌──────────────────┐
│ Write and unhold │
│ the DASD record │
└──────────────────┘
Figure 68. Reading DASD records and holding the file address – updates performed by either entry are recorded.
ALCS suspends entry 2 and does not allow it to read the record and hold the file address until entry 1 has
unheld the file address.
To lock a file address, the application program reads the record by requesting a service that has a built-in
“hold” option, for example, the FINHC (finhc) or FIWHC (fiwhc) service. When either of these requests
completes, the entry is holding the file address. The entry continues to hold the file address until it
unholds it with a FILUC (filuc) or UNFRC (unfrc) request.
Serialization is often more complex than this simple example. A single entry often needs to update
several records – perhaps deleting information from one record and storing it in another. For example, an
airline transaction to cancel a flight might need to transfer the passengers with reservations on that flight
to one or more other flights.
Consistent use of locks
In the example just discussed, two entries 1 and 2 ensure that they update an index correctly by using a
lock. But for locks to work, it is essential that:
5 All programs that update a record must request the lock.
In our example, it is not enough for entry 1 to request the lock. If entry 2 does not request the lock
then it is still possible for entry 1's update to be lost.
In our simple example this mistake is unlikely, but in a real application there may be hundreds of
programs that update a particular type of record – if even one program fails to request the lock then
updates can be lost.
5 All programs that update a record must request the same lock.
In our example, if entry 1 requests lock “A” and entry 2 requests lock “B” then there is no serialization
and updates can be lost.
88
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
Again, this mistake is unlikely in our simple example. But real applications are more complex. For
example, in an airline reservation system, one program might request a lock for a particular flight
number when adding a passenger, but another program might request a lock for the flight number and
date.
Lock contention and granularity
When two entries request the same lock, the first one gets the lock and the second must wait. The
second entry cannot resume until the first entry releases the lock. If a third entry requests the same lock
then it must wait for both the first entry and the second entry.
Multiple requests for the same lock is called lock contention. Lock contention slows transaction
responses by forcing entries to wait. To get the best performance from your application, you must design
your application and your database to minimize lock contention.
There are two main factors that affect lock contention:
5 The amount of time that your application holds a lock.
The longer your program holds a lock, the more likely it is that another entry will request the lock while
your program is holding it.
5 The amount of the database that the lock controls.
This is called lock granularity. Coarse granularity uses a small number of locks, each controls a
large proportion of the database. Fine granularity uses a large number of locks, each controls a small
proportion of the database.
The coarser your lock granularity, the more likely it is that updates to different records will require
holding the same lock and therefore the more likely it is that two entries will request the lock at the
same time.
7.3.1 Serialization – forcing exclusive access to resources
Each ALCS entry has its own ECB and its own attached and detached storage blocks, which all belong
exclusively to that entry. Assembler application programs can therefore use the storage without
interference from other entries.
However, all ALCS entries can share other resources, in particular:
5 Database records
5 The application global area
5 Sequential files.
In order to allow application programs to share these resources without corrupting their contents, ALCS
allows programs to force exclusive access to a resource while they are using it, as follows:
5 Force exclusive access to the resource
5 Perform instructions that use the resource
5 Release the resource so that other entries can use it.
While one entry has exclusive access to a resource, ALCS queues any other entries that require access to
it until the first entry releases it.
Application programmers should therefore keep exclusive access to a resource for the shortest possible
time. Otherwise, entries will be kept waiting unnecessarily, which directly affects transaction response
times.
Chapter 7. Data in ALCS
89
Data
For details of how application programs get and release exclusive access of resources, see 7.3.2,
“Serializing access to the application global area” on page 90.
7.3.2 Serializing access to the application global area
ALCS supports an area of storage that entries can share. This is called the application global area2.
This area is not protected; any entry can store information in the global area.
It is complex to use the application global area in a multiprocessor environment for anything except
constants. It is much simpler to store variable data in DASD records (appropriate use of virtual file access
(VFA) makes physical I/O unnecessary).
However, if you cannot avoid using the application global area, this section describes how assembler
application programs can update the application global area in a multiprogramming and multiprocessing
environment.
C language application programs
Application programs written in the C language use their own global functions. These are described in
7.3.3, “SYNCC monitor-request macro and global C function” on page 95.
To avoid potential errors, application programs can update the application global area by using the
following:
5
5
5
5
5
Block-concurrent references
COMPARE AND SWAP (CS and CDS) instructions
ALCS resource hold
ALCS BEGIN macro SHR and XCL parameters
SYNCC monitor-request macro. See 7.3.3, “SYNCC monitor-request macro and global C function” on
page 95.
TPF compatibility
IBM advises that you use only the SYNCC macro for global serialization in order to minimize changes
required to migrate from or to a loosely coupled environment.
When two entries try to update the same global area field at the same time, then the result can be
unpredictable. For example, an application program may contain a sequence of instructions such as:
L
LA
ST
r1,global_field
r1,1(,r1)
r1,global_field
On a multiprocessor, two entries can execute the same sequence of instructions on two different
processors. The result, however, is unpredictable:
5 If the instructions are executed at exactly the same moment, both entries load the same value into r1,
increase the value by 1, and store it in global_field. The result is that the value in global_field
increases by 1.
5 If the instructions are executed at different times, one entry loads the original value and updates it.
Then the other entry loads the updated value and updates it again. The result is that the value in
global_field increases by 2.
2
Actually the ALCS application global area is three areas of storage.
90
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
Although the first case is extremely rare, you must write your programs to take account of this possibility.
In general, any sequence of instructions similar to:
1. Load global area field
2. Compute new value
3. Store back new value
can produce unpredictable results. Some single instructions, for example OR (OC and OI), can produce
unpredictable results in the same way.
A comparable error can happen if one entry updates a global area field (store accesses) and another entry
reads (fetch accesses) the field at exactly the same time. For example, one entry can move data to a
global area field. The data replaces the previous field contents. Another entry can move data from the
same field (for example, into the ECB work area). The two moves can overlap so that the second entry
moves a mixture of the original field contents and the new contents.
Note that both types of error can occur on uniprocessors. If an entry loses control during the update, then
another entry can refer to or update the same field. Consider this example:
L
r1,global_field
DEFRC ,
LA
r1,1(,r1)
ST
r1,global_field
When one entry issues the DEFRC, another entry can update the value in global_field. In the same way, an
entry that issues DEFRC between two related updates to the global area allows other entries to “see”
inconsistent data.
Treat individual fields that are independent of other fields according to their size:
For appropriately aligned fields up to 8 bytes, use either of:
5 Block-concurrent instructions (page 91)
5 COMPARE AND SWAP and COMPARE DOUBLE AND SWAP (page 92).
For other fields, use either
5 The SHR and XCL parameters (page 93). The global area field name can be a suitable token, or
5 The resource hold facility (page 93).
S/390 block-concurrent references
Application programs can safely share information in the application global area by means of
block-concurrent instructions, provided that:
5 For update, the new value does not depend on the old value (the program does not use the old
contents of the field to calculate the new contents), and
5 The field does not need to be consistent with other fields.
In these circumstances, block-concurrent instructions can be the most efficient way to share access, as
they do not require any extra instructions to serialize accesses.
Some assembler instructions make block-concurrent storage references. The ESA/390 Principles of
Operation describes block-concurrent references and lists the instructions that make this type of reference.
Many instructions that refer to an operand access the operand in a way that is block-concurrent. For
example:
5 Byte
Chapter 7. Data in ALCS
91
Data
5 Halfword, aligned
5 Fullword, aligned
5 Doubleword, aligned.
That is, the access (fetch or store) does not overlap with other accesses to the same field. For example,
some programs STORE (ST) into a fullword and other programs LOAD (L) from the fullword.
5 STORE does not overlap with STORE. For example, an aligned fullword field contains hexadecimal
00000000 and there are two STOREs into the field. One stores hexadecimal 11111111 and the other
stores hexadecimal 22222222. The field can contain hexadecimal 00000000, 11111111, or 22222222.
It cannot contain, for example, 11112222. (If the field is not fullword aligned, the STOREs can
overlap, and the result can be 11112222.)
5 STORE does not overlap with LOAD. For example, an aligned fullword field contains hexadecimal
00000000 and there is a STORE into the field; it stores hexadecimal 11111111. LOAD can load
hexadecimal 00000000 or 11111111. It cannot load, for example, 11111100. (If the field is not
fullword aligned, the STORE can overlap, and LOAD can load 11111100.)
Use of block-concurrent instructions
An aligned fullword contains a currency exchange rate. The program that updates the field gets the new
exchange rate from an external source – an input message. The program uses STORE (ST) to update
the field. All programs that use the field use LOAD to load it. In this case there is no need to serialize the
accesses.
There can be several fullwords that contain exchange rates. If so, then block concurrent accesses cannot
ensure that all the exchange rates are consistent. Instead, a program that updates the exchange rates
must have exclusive control of all the exchange rates while it makes the updates. Programs that use
more than one exchange rate must have shared control of the exchange rates. But even in this case, a
program that uses only one exchange rate can LOAD it while another program is updating exchange
rates.
S/390 compare and swap instructions
If block-concurrent access is not suitable, then COMPARE AND SWAP (CS) or COMPARE DOUBLE AND
SWAP (CDS) can be the most efficient way to share access to information in the application global area.
It does require extra instructions (CS or CSD) to serialize accesses but it does not prevent parallel
execution. Two entries can run at the same time on two different processors, even though they both
update the same global area field. COMPARE AND SWAP is not suitable for information where several
fields must contain consistent information.
The ESA/390 Principles of Operation describes the CS and CDS instructions and gives examples of how
to use them.
In general, use CS to update a global area field as follows:
1.
2.
3.
4.
Load global area field into general register r1
Use r1 to compute the new value in general register r2
Use COMPARE AND SWAP to store back the new value
If condition code 4, then repeat from step 2.
For example, to add 1 to the contents of global_field:
92
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
RETRY
L
EQU
LA
CS
BNE
r1,global_field
V
r2,1(,r1)
r1,r2,global_field
RETRY
Note: A field can contain subfields that application programs access independently. For example, an
application program can use TEST UNDER MASK (TM) several times to test different bits in the same
fullword. To ensure that these tests give consistent results, the program must use block-concurrent
accesses to copy the whole fullword (for example, into the ECB work area). The application program can
then test its own copy; no other program can change it between tests.
ALCS resource hold
If block-concurrent access and COMPARE AND SWAP are not suitable, then ALCS application programs
can use resource hold to serialize access to information in the application global area.
To use resource hold in this way, define a value (for example, a storage address) that uniquely identifies a
field or a group of fields in the application global area. Every application program that uses the field or
fields must ensure exclusive control. To do this, application programs can use the resource hold
monitor-request macros. These are:
5 SYNCC LOCK and SYNCC UNLOCK (recommended)
5 CORHC and CORUC
5 ENQC and DEQC.
The ALCS Application Programming Reference – Assembler describes these monitor-request macros.
Note that the resource hold monitor-request macros allow an entry to keep exclusive access to global area
information, even if the entry loses control, for example, when the entry waits for DASD I/O completion.
ALCS BEGIN macro SHR and XCL parameters
TPF compatibility
This facility is not available in TPF.
If block-concurrent access and COMPARE AND SWAP are not suitable, ALCS application programs can
use the BEGIN macro parameters SHR and XCL to serialize access to information in the application global
area. Shared access (SHR) is equivalent to read-only access; exclusive access (XCL) is equivalent to read
and write access. The format of these parameters is:
SHR=(token,...)
XCL=(token,...)
where token is a user-defined character string that identifies a field or a group of fields in the application
global area. In this way the application program indicates that it requires shared or exclusive access to
one or more groups of fields.
The token ALL means all fields in the application global area, NONE means no fields. (The next sections
describe how your system programmer can set up your tokens.)
The defaults are SHR=ALL,XCL=ALL. The program gets exclusive control of all global area fields. On a
multiprocessor, this default means that the program can only run parallel with programs that specify
Chapter 7. Data in ALCS
93
Data
SHR=NONE,XCL=NONE. Many programs do not need exclusive control of all fields in the global area. For
these programs, use the SHR and XCL parameters to reset the defaults.
For optimum performance, even on a uniprocessor, you should specify SHR=NONE,XCL=NONE. Do this when
the application program:
5 Does not refer to any global area fields
5 Only refers to global area fields that are constants
5 Can share access to all the global area fields that it references (for example, because it uses
block-concurrent accesses, or because application programs use COMPARE AND SWAP to update
the fields)
5 Uses resource hold to control all accesses to the global area.
If the application program requires shared access to some global area fields, but it does not require
exclusive access, then specify XCL=NONE. (If possible, also avoid SHR=ALL, see below.) Do this if the
application program:
5 Does not modify any global area fields
5 Can share access to all the global area fields that it modifies (for example, because it uses
block-concurrent stores or COMPARE AND SWAP)
5 Uses resource hold to control accesses to the global area fields that it modifies.
If the application program requires shared or exclusive access to some but not all of the global area, then
do not specify or default to SHR=ALL or XCL=ALL. Instead, specify tokens that identify only those fields the
application program references. The following sections describe how you can set up your own tokens.
Note: The BEGIN macro parameters do not allow an entry to keep exclusive or shared control of global
area information if the entry loses control. For example, if the entry waits for DASD I/O completion, it
loses shared (or exclusive) control while it is waiting. It gets shared (or exclusive) control again when the
wait completes. To keep control (when the entry would otherwise lose control) use the resource hold
facility. See “ALCS resource hold” on page 93.
How to allocate BEGIN macro SHR and XCL parameters
The BEGIN macro's SHR and XCL parameters use tokens that are user-defined character strings. Each
token identifies a field or a group of fields in the application global area. If required:
5 A token can identify a single field.
5 More than one token can identify the same group of fields.
5 The group of fields that one token identifies can overlap with the group that another token identifies.
5 A token can identify some or all of the fields that another token identifies.
You can allocate tokens in the following ways:
5 Identify major subsets of the application programs. Each subset is the only (or main) user of a
particular subset of global area fields. Allocate a token to each subset of global area fields.
This can make it easy to modify existing application programs (add SHR and XCL parameters to the
BEGIN statement) so that they can exploit multiprocessors.
For example, an airline application might include the following subsets:
Passenger seat reservations
Fare quotation
Check-in.
94
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
You could allocate a token RES to identify fields in the global area that passenger seat reservations
programs use. To identify fields used by fare quotation programs you could allocate a token
FQUOTE.
5 Identify groups of logically related global area fields. The fields are related because they must contain
consistent information. Often a single application program is reponsible for updating all the fields in a
group. Allocate a token to each group of logically related fields.
For example, the global area might contain a number of fields that contain date and time information.
The token TIME can identify this group of fields. One application program can be responsible for
updating all of these fields (for example, every minute). That program requires exclusive access to the
group. Other programs that access some or all of the fields in the group need shared access to the
group.
How to define BEGIN macro SHR and XCL parameters
To define tokens for the BEGIN macro's SHR and XCL parameters, modify the ALCS global access
serialization macro, DXCSER. The DXCSER macro is described in the ALCS Installation and Customization.
DXCSER associates each token with one or more resources. ALCS implements this with two fullwords. One
fullword indicates shared control requirements. When a bit is on, the application program requires shared
control of the corresponding resource. Similarly, the other fullword indicates exclusive control
requirements.
In this way, an application program can specify exclusive control, shared control, or no control of each
resource independently.
There can be up to 32 resources. But there can be many more tokens. Allocate resources to tokens as
follows:
5 If a token represents a group of fields that must contain consistent information, allocate one resource
to it.
5 If a token represents a major subset of the global area, allocate several resources to it. This allows
other tokens to refer to groups of fields within the major subset.
5 If more than one token refers to the same group of fields, allocate the same resource to all the tokens.
It can be necessary to “lump” groups of fields (that is, allocate a single resource to more than one group
of fields).
7.3.3 SYNCC monitor-request macro and global C function
To be compatible with loosely coupled systems, ALCS application programs can use the SYNCC
monitor-request macro to serialize access to the application global area. C application programs can only
use the global C function – which provides essentially the same services as SYNCC.
In a loosely coupled configuration (or in a TPF tightly-coupled configuration) there are multiple copies of
the application global area. SYNCC and global provide services to ensure that updates are correctly and
consistently applied to all copies. These services also serialize global area updates in tightly-coupled and
uniprocessor configurations. They are:
LOCK
This service gives the requesting entry exclusive control of the specified global field. Entries
that request this service are forced to run serially even if they execute in different CECs of a
loosely coupled configuration.
Chapter 7. Data in ALCS
95
Data
(In a TPF loosely coupled configuration, this service also ensures that any updates to the field
– including updates done on other CECs in the complex – complete before returning to the
requesting entry.)
After requesting the LOCK service, the entry can update the locked field.
SYNC
After updating the global area field, the entry must request this service to:
1. Inform ALCS that the field has changed. If the record containing the field is keypointable
then ALCS updates the file copy of the record.
(In a TPF loosely coupled configuration, this service starts the process of updating the field
in other CECs of the complex.)
2. Unlock the global field. This allows the next entry (if any) that is waiting to access the field
to proceed.
An entry can use the LOCK service of SYNCC or global even when the entry does not update the global
area field. For example, an entry can use the LOCK service to prevent any other entry from updating a
field during some process. An entry may also use the LOCK service to be sure that it accesses absolutely
up to date field contents even in a loosely coupled configuration.
If an entry uses the LOCK service without updating the global field, it can not use the SYNC service to
unlock the field. Therefore, SYNCC and global provide the following additional service:
UNLOCK This service unlocks the global field. This allows the next entry (if any) that is waiting to
access the field to proceed.
7.3.4 ALCS services for accessing DASD records
Application programs can use the following assembler macros and C functions to access DASD records.
Type of
DASD
record
Assembler function
macro
Used to
Fixed file
FACE
(note 1)
face
Calculate a fixed file address from fixed-file record type
number and record ordinal
|
|
FACS
(note 1)
facs
Calculate a fixed file address from fixed-file record type name
and record ordinal
|
|
FAC8C
tpf_fac8c
Calculate an 8-byte fixed file address in 4x4 format from
fixed-file record type name or number and record ordinal
GETFC
(note 2)
getfc
getfc_alt
Get a pool file address (dispensed by ALCS) and optionally
get and attach a storage block
|
|
RCRFC
tpf_rcrfc
Release a pool file address and detach and release the
storage block
|
|
RELFC
relfc
Release a pool file address, and optionally detach and
release the storage block
|
RLCHA
rlcha
Release a chain of pool-file record addresses
General
file
RAISA
raisa
Calculate the file address of the first record in a general file
or increment the relative record number of the current record
in a general file and calculate its file address
General
data set
GDSNC
gdsnc
Open or close a general data set (GDSNC OPEN also calculates
the file address of a general data set record)
GDSRC
gdsrc
Calculate the file address of a general data set record
|
|
Pool file
|
|
|
|
96
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
Type of
DASD
record
Assembler function
macro
Used to
All
FILEC
filec
filec_ext
File (write) a DASD record
|
|
FILNC
filnc
filnc_ext
File (write) a DASD record without detaching the storage
block
|
|
FILUC
filuc
filuc_ext
File (write) a held DASD record and unhold the file address
|
|
FINDC
findc
findc_ext
Find (read) a DASD record
|
|
FINHC
finhc
finhc_ext
Find (read) a DASD record and hold the file address
|
|
FINWC
finwc
finwc_ext
Find (read) a DASD record
|
|
FIWHC
fiwhc
fiwhc_ext
Find (read) a DASD record and hold the file address
|
|
RCUNC
rcunc
Unhold a held DASD record and detach and release the
storage block
|
|
Extract information about a record ID
RIDIC
RONIC
ronic
Extract information about a record
UNFRC
unfrc
unfrc_ext
Unhold a held DASD record
SONIC
sonic
Extract information about a record
|
|
file_record
file_record_ext
File a DASD record
|
|
find_record
find_record_ext
Find a DASD record
tpf_fa4x4c
Convert a 4-byte file address to an 8-byte file address in 4x4
format, or convert an 8-byte file address in 4x4 format to a
4-byte file address
|
|
|
|
|
FA4X4C
Notes:
|
1. FACE and FACS are not assembler macros but programs that application programs can ENTER.
2. ALCS also provides GETLC, GETSC, GCFLC, and GCFSC macros for compatibility with TPF. IBM
recommends that you use GETFC instead of any of these macros.
TPF compatibility
Do not request the RIDIC or RONIC (ronic) services in programs that must be compatible with TPF.
7.3.5 Summary of ALCS services for DASD processing
Figure 69 on page 98 summarizes the assembler macros (in upper case) and functions (lower case) you
can use with records on DASD.
Chapter 7. Data in ALCS
97
Data
Records on DASD
│
┌───────────────────────┬──────────┴─────────┬────────────────────────┐
│
│
│
│
Fixed-file records
Pool-file records
General file records
General data set records
RIDIC
RONIC
SONIC
ronic
sonic
|
|
|
|
|
|
FACE
FACS
FAC8C
FA4X4C
face
facs
tpf_fac8c
tpf_fa4x4c
FA4X4C tpf_fa4x4c
GETFC getfc
getfc_alt
RCRFC tpf_rcrfc
RELFC relfc
RLCHA rlcha
FA4X4C tpf_fa4x4c
RAISA raisa
FA4X4C tpf_fa4x4c
GDSNC gdsnc
GDSRC gdsrc
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FILEC
filec
filec_ext
filnc
filnc_ext
filuc
filuc_ext
findc
findc_ext
finhc
finhc_ext
finwc
finwc_ext
fiwhc
fiwhc_ext
rcunc
unfrc
unfrc_ext
FILEC
FILEC
FILEC
FILNC
FILUC
FINDC
FINHC
FINWC
FIWHC
RCUNC
UNFRC
|
|
|
|
file_record
file_record_ext
find_record
find_record_ext
RIDIC
RONIC
SONIC
FILNC
FILUC
FINDC
FINHC
FINWC
FIWHC
RCUNC
UNFRC
ronic
sonic
filec
filec_ext
filnc
filnc_ext
filuc
filuc_ext
findc
findc_ext
finhc
finhc_ext
finwc
finwc_ext
fiwhc
fiwhc_ext
rcunc
unfrc
unfrc_ext
RIDIC
RONIC
SONIC
FILNC
FILUC
FINDC
FINHC
FINWC
FIWHC
RCUNC
UNFRC
file_record
file_record_ext
find_record
find_record_ext
ronic
sonic
filec
filec_ext
filnc
filnc_ext
filuc
filuc_ext
findc
findc_ext
finhc
finhc_ext
finwc
finwc_ext
fiwhc
fiwhc_ext
rcunc
unfrc
unfrc_ext
file_record
file_record_ext
find_record
find_record_ext
RIDIC
RONIC
SONIC
FILNC
FILUC
FINDC
FINHC
FINWC
FIWHC
RCUNC
UNFRC
ronic
sonic
filec
filec_ext
filnc
filnc_ext
filuc
filuc_ext
findc
findc_ext
finhc
finhc_ext
finwc
finwc_ext
fiwhc
fiwhc_ext
rcunc
unfrc
unfrc_ext
file_record
file_record_ext
find_record
find_record_ext
Figure 69. ALCS services for processing DASD records
7.3.6 Offline access to general files and general data sets
Offline programs use standard VSAM facilities to access general files and general data sets. Offline
programs must not access the ALCS real-time database.
7.4 Using sequential files
In ALCS, sequential files consist of records on any medium that MVS sequential access method (SAM)
supports, including DASD. Sequential files are identified by a 3-character name. Records on sequential
files can be standard sizes (L0, L1, L2, ..., L8) or nonstandard sizes. C language programs can read and
write standard-size records only.
There are three types of sequential file: system files, real-time, and general. Application programs cannot
access system sequential files, but can:
5 Write records to real-time sequential files
5 Read records from, or write records to, general sequential files.
You can access partitioned data set (PDS) members as sequential files.
98
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
7.4.1 System sequential files
Application programs cannot read records from, or write records to, system sequential files. (However,
once ALCS has closed a system sequential file, an application could open the same physical file as a
general sequential file and read the records from it.)
7.4.2 Real-time sequential files
When ALCS is started, it opens all the real-time sequential files that are available. Any entry can then
write data to any of these files.
Real-time sequential files are for output only. The real-time sequential file services TOURC (tourc) and
TOUTC (toutc) allow application programs to write to real-time sequential files.
Note: Because any entry can write data to a real-time sequential file at any time, you cannot normally
control the sequence of records on the file. The records that your entry writes may be interspersed with
records that other entries write.
7.4.3 General sequential files
Before an application program can use a general sequential file, the entry must first open the file and
assign it to itself. “Assigned” means that the file is allocated for the use of this entry only.
The TOPNC (topnc) service opens and assigns a general sequential file with one call. When it requests this
service the program must specify whether the sequential file is to be opened for reading (input) or writing
(output).
Following a TOPNC (topnc) request to open the file for input, application programs can request the TPRDC
(tprdc) service to read records from the sequential file. If the file was opened for output, application
programs can request the TWRTC (twrtc) service to write records to the sequential file. Assembler
programs can use the TDTAC service to read and write nonstandard-size records.
When an application has finished using a general sequential file (and before the entry exits), it must
unassign the general sequential file. There are two ways to do this. The TCLSC (tclsc) service unassigns
and closes the general sequential file. The TRSVC (trsvc) service unassigns the general sequential file, but
it does not close it. Requesting the TRSVC (trsvc) service is called reserving the sequential file.
Once a general sequential file is reserved, another entry (or the same entry that requested TRSVC (trsvc)
can assign the file to itself by requesting the TASNC (tasnc) service.
Note: The “higher-level” C functions tape_open, tape_read, and tape_write do not follow these
conventions. Do not use them if more than one entry can access the general sequential file at the same
time.
7.4.4 Several entries using the same general sequential file
The TRSVC (trsvc) and TASNC (tasnc) services allow several entries to use the same general sequential file,
as follows:
1. One entry opens and assigns the file by requesting the TOPNC (topnc) service. It reads or writes
several records and then reserves the file by requesting the TRSVC (trsvc) service.
2. Another entry then assigns the file by requesting the TASNC (tasnc) service, reads or writes several
records, and then reserves the file again.
Chapter 7. Data in ALCS
99
Data
3. When these cooperating entries have all finished using the file, one of them assigns the file and then
closes it by requesting the TCLSC (tclsc) service.
Figure 70 shows this process.
Entry 1
Entry 2
───────
───────
┌────────────────────┐
│ Open the general
│
│ sequential file
│
│ for input
│
│ TOPNC (topnc)
│
└────────────────────┘
D
┌──────────────────┐
│ Read from the
│
│ file
│
│ TPRDC (tprdc)
│
┌────────────────────┐
└──────────────────┘
│ Assign the general │
D
│ sequential file
│
┌──────────────────┐
│ TASNC (tasnc)
│
│ Reserve the file │
└────────────────────┘
│ for further use │
.
│ TRSVC (trsvc)
│
.
└──────────────────┘
.
-------------------------------------------------D
┌──────────────────┐
│ Read from the
│
│ file
│
┌────────────────────┐
│ TPRDC (tprdc)
│
│ Assign the general │
└──────────────────┘
│ sequential file
│
D
│ TASNC (tasnc)
│
┌──────────────────┐
└────────────────────┘
│ Reserve the file │
.
│ for further use │
.
│ TRSVC (trsvc)
│
.
└──────────────────┘
-------------------------------------------------D
┌──────────────────┐
│ Read from the
│
│ file
│
┌────────────────────┐
│ TPRDC (tprdc)
│
│ Assign the general │
└──────────────────┘
│ sequential file
│
D
│ TASNC (tasnc)
│
┌──────────────────┐
└────────────────────┘
│ Reserve the file │
.
│ for further use │
.
│ TRSVC (trsvc)
│
.
└──────────────────┘
.
-------------------------------------------------D
┌──────────────────┐
│ Close the file
│
│ TCLSC (tclsc)
│
└──────────────────┘
Figure 70. Two entries accessing the same general sequential file
The general sequential file must be open when an application program assigns it by requesting TASNC
(tasnc) need not be reserved at the time. If the general sequential file is assigned to another entry, the
TASNC (tasnc) service waits for the other entry to request TRSVC (trsvc). If several entries request TASNC
(tasnc) for a file that is already assigned then they get control in turn; when one entry requests TRSVC
(trsvc), the next entry gets control, and so on.
7.4.5 ALCS services for sequential file processing
The following table shows the assembler macros and C functions you can use with ALCS sequential files.
100
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
Type of sequential
file
Assembler function
macro
Used for
All
TDSPC
tdspc
Extract information about the sequential file
Real-time
TOURC
tourc
Write a standard-size (L0, L1, L2, ...) record
TOUTC
toutc
Write any size record
TASNC
tasnc
Assign a general sequential file to the entry
TCLSC
tclsc
Close and deallocate, then unassign a file
TOPNC
topnc
Open and allocate, then assign a file to an entry
TRSVC
trsvc
Unassign (reserve) a general sequential file
TPRDC
tprdc
Read a standard-size record (L0, L1, L2, ...)
TWRTC
twrtc
Write a standard-size record (L0, L1, L2, ...)
General
Read or write any size record
TDTAC
tape_close Close a general sequential file
tape_open
Open a general sequential file
tape_read
Read a record
tape_write Write a record
7.4.6 Summary of ALCS services for sequential files
Figure 71 summarizes the assembler macros (in upper case) and functions (in lower case) you can use
with the three types of sequential file.
Sequential Files
│
┌────────────────────┴───┬────────────────────────┐
│
│
│
System
Real-time
General
(no I/O allowed)
(write only)
(read and write allowed)
TDSPC
tdspc
TDSPC
tdspc
TDSPC
tdspc
TOURC
TOUTC
tourc
toutc
TASNC
TCLSC
TDTAC
TOPNC
TPRDC
TRSVC
TWRTC
tasnc
tclsc
topnc
tprdc
trsvc
twrtc
tape_close
tape_open
tape_read
tape_write
Figure 71. Macros and functions for processing sequential files
7.5 Global records and fields
ALCS supports the use of application global records and global fields (both referred to as “globals”).
Global records are fixed-file records that ALCS loads into main storage shortly after start up. Global fields
are fields within directly-addressable global records (see “Directly-addressable global records” on
page 102).
Global records can be read and modified by all application programs.
Chapter 7. Data in ALCS
101
Data
You are recommended not to use global records (see 7.5.4, “Using globals – attention” on page 104).
You can get the same benefits in a more controlled way by using VFA. However, some existing
applications use global records, so you might need to know how they operate.
By convention, global records and fields are identified in assembler language programs by a name starting
with an '@', followed by from 1 to 7 alphabetic or numeric characters (for example, @ABC11). In C
language programs the name starts with an underline character (for example, _ABC11). In the following
section we use the assembler convention.
7.5.1 Global directories
ALCS holds global records in main storage in 3 global areas. The first global area holds up to 16 global
directories. Each global directory has an identifier @GLnBA, where n is a hexadecimal number 0
through F. Global directory @GLFBA is reserved for ALCS’s use.
TPF compatibility
If your programs must be compatible with TPF, see 7.6, “Globals — compatibility with TPF” on
page 107.
Each global directory contains up to 256 directory “slots”, each slot contains the storage address of a
global record (4 bytes), or the storage address and file address of a global record (8 bytes). Each
directory slot is identified by a name of up to 8 characters. Figure 72 shows a logical view of a global
directory showing how directory entries enable assembler language application programs to locate global
records by using directory slots.
@ABC1
@ABC2
@ABC3
D
D
D
┌────────┬────────┬────────┬────────────┐ ┐
│
│
│
│ . . .
│ │ Directory slots
├────────┴────────┴────────┴────────────┤ │
│
│
│
└─────────────────────────────────────────────────────────────┐
┌───────────────┘
└─────────────────────────────────────────────────┐
D
│
│
│ ┘
D
┌────────────────┐
│
├───────────────────────────────────────┤ ┐
┌─────────────────┐ │
│
└;@ABD1 ─ ─;│
│ │
│
│ │
│
│
@PQR1─ ─;┌─────┐
│ │
│
│ └────────────────┘
:
│
└─────┘
│ │
│
│
│
├───────────────────────────────────────┤ │
└─────────────────┘
└;@ABD2 ─ ─;│
│ │
│ @STU1─ ─;┌─────┐ @STU2─ ─;┌─────┐
│ │
Indirectly-addressable global records
:
│
└─────┘
└─────┘
│ │
│
├───────────────────────────────────────┤ │
└;@ABD3 ─ ─;│
│ ├─ Directly-addressable
│
@XYZ1─ ─;┌─────┐
│ │ global records and fields
│
└─────┘
│ │ (within 4KB from start of directory)
└───────────────────────────────────────┘ ┘
Figure 72. ALCS global area directory – logical view
Directly-addressable global records
As described in 7.5.1, “Global directories”, global area 1 holds up to 16 global directories. Global area 1
can also hold global records, as shown in Figure 72. In addition to accessing these records through a
directory slot, assembler programs can access fields within these records directly, using the field name (for
example @ABD1, @ABD2, @ABD3), so long as they are within 4KB from the start of the directory.
These records are called directly-addressable global records.
Within directly-addressable global records, application programs can access fields directly using the field
name (for example, @PQR1, @STU1, @STU2, @XYZ1). These fields are called global fields. They are
the only type of “global” that C language programs can update.
102
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
Indirectly-addressable global records
A directory can contain storage addresses of up to 256 global records outside the 4KB area. Programs
can only access these records indirectly through the directory slot, using the identifier (for example,
@ABC1, @ABC2, @ABC3). These global records are called indirectly-addressable global records.
The program must know the structure of the record to access individual fields in it. (An assembler
language program uses a named DSECT, a C language program uses a named struct.)
7.5.2 Keypointing global records
Keypointing is the process of writing a record to the database. The system programmer defines
individual global records as being keypointable or nonkeypointable.
Keypointable
These are global records that are intended to be updated by application programs. After each update,
the application program can issue an assembler macro to write the global record to DASD.
Nonkeypointable
These are global records that are not intended to be be updated by application programs. Application
programs can update nonkeypointable records, but even if they request it, ALCS never writes
nonkeypointable globals to DASD. They are reinitialized when ALCS restarts.
Note: Updating any global record or field requires care. See 7.5.5, “Global area serialization” on
page 104.
7.5.3 Logical global records
Physical DASD records include a 16-byte standard header (see 7.1.2, “Standard record header” on
page 83). ALCS can combine several physical records into one “logical” global record for easier
processing by application programs. See Figure 73.
Physical records
Logical global records
(on DASD)
(in storage)
┌────────────────┐
┌────────────────┐
│ Header
│K ─ ─ ─ ─ ─ ─ ─ ;│ Header
│
├────────────────┤
├────────────────┤
│
│
│
│
│
A
│K ─ ─ ─ ─ ─ ─ ─ ;│
A
│
│
│
│
│
│
│
│
│
└────────────────┘
├────────────────┤
│
│
┌────────────────┐
┌ ─ ─ ─ ─ ;│
B
│
│ Header
│
│
│
│
├────────────────┤
│
│
│
│
│
│
├────────────────┤
│
B
│K ─ ─ ┘
│
│
│
│
┌ ─ ─ ;│
C
│
│
│
│
│
│
└────────────────┘
│
│
│
│
└────────────────┘
┌────────────────┐
│
│ Header
│
│
├────────────────┤
│
│
│
│
│
C
│K ─ ─ ─ ─ ┘
│
│
│
│
└────────────────┘
Figure 73. Removing headers to create a logical global record
ALCS can keypoint header-stripped records; this is called logical global support.
Chapter 7. Data in ALCS
103
Data
7.5.4 Using globals – attention
Because global records are permanently in storage, application programs can access the data that they
contain without the need for any I/O.
However, if possible, instead of globals you should use fixed-file records defined with the virtual file access
(VFA) attribute described in ALCS Installation and Customization. In particular, the permanently resident
attribute and the time-initiated file attribute can allow application programs to use read and write records
with relatively few I/Os.
Using the application global area for records has several disadvantages:
5 Applications programs that share access to records in the global area must serialize access to the
records. This process can be complex. See 7.5.5, “Global area serialization”.
5 It is not easy to add new global records to the global area. (Similarly, it is difficult to remove records
from the global area.) By contrast, it is easy to change the VFA options for a record.
5 Existing application programs that use read and write macros (or functions) to access a record must
be changed to access records from the global area.
5 C language programs cannot update global records (they can only update global fields).
5 It might become necessary at some stage to run the application programs on a loosely coupled
system (for example, under TPF). Application programs that use the global area can require major
changes to work in a loosely coupled environment.
5 The use of globals greatly reduces the portability of a program.
7.5.5 Global area serialization
The global areas do not belong to any particular entry. They are shared by all entries.
Consider an ECB-controlled program that does the following:
1. Copies a field from a global record (for example, field @ABC1)
2. Updates the copy (for example, adds 1 to it)
3. Stores the updated copy back into the global record.
This sequence works correctly only when no other entry can update the global field @ABC1 during the
process. However, with a multiprocessor system this cannot be guaranteed. Even on a single-processor
system the first entry could lose control between steps 1 and 3.
When application programs update a global area, access must be serialized to avoid data corruption.
There are several methods of serializing access to the global area. The most universally applicable
method is for the entry to hold the global, using the SYNCC assembler macro or the global function during
the update. When update is complete the entry releases the hold and other entries can then access the
global field or record. See 7.3, “Serialization” on page 87.
Serialized access inevitably requires extra processing (additional to the update itself), particularly when the
application is to run in a loosely coupled environment.
104
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
Using resource hold
In assembler programs, the ALCS resource hold facility is controlled by the following assembler macros:
CORHC (used with CORUC) or
ENQC (used with DEQC) or
SYNCC LOCK (used with SYNCC UNLOCK or SYNCC SYNC).
All application programs which access the data must hold (using CORHC, ENQC, or SYNCC LOCK) before
accessing the data. After accessing the data, they must unhold (using CORUC, DEQC, SYNCC UNLOCK, or SYNCC
SYNC).
Note: Even application programs which only read (fetch access) the data must use resource hold. This
ensures that the data does not change while the program is accessing it. (This requirement does not
apply to data that never gets changed.)
Tightly coupled systems: In a tightly coupled system, SYNCC LOCK holds the referenced field, and SYNCC
UNLOCK unholds it. SYNCC SYNC marks the appropriate record as ready for keypointing before unholding the
referenced field.
Loosely coupled systems: In a loosely coupled system, SYNCC LOCK holds the referenced field in each
memory containing the global area. SYNCC UNLOCK unholds the referenced field in each memory. SYNCC
SYNC starts the process of updating the referenced field in other menbers of the complex. It also marks
the appropriate record as ready for keypointing before unholding the referenced field.
Note: Current releases of ALCS support tightly coupled systems only.
Other methods
Assembler programs can use other methods to perform global serialization. These include:
1. Block-concurrent referencing
2. Compare and swap instructions
3. Shared access (SHR) and exclusive access (XCL) parameters, together with tokens, on the BEGIN
macro.
Methods 1 and 2 only work on certain global fields and only if all other programs access the globals using
the same method. They do not work in a loosely coupled environment but some existing applications use
them.
TPF compatibility
Method 3 is not available under TPF.
7.5.6 C functions for processing globals
ALCS provides two functions glob and global for accessing the global area. These let C language
programs read global records or global fields, but C language programs can only update global fields (not
records). They are described in detail in ALCS Application Programming Reference – C Language.
Chapter 7. Data in ALCS
105
Data
Accessing global fields
In C language application programs, you can use either the glob function or the global function to access
global fields. You can use the glob function to read a global field or record. You can use the global
function to update global fields (but not global records), to do the necessary serialization for these
updates, and perform other actions.
Note: Because all entries share the same global area, you must not update variables in the global area
directly, using operators such as =, or ++. You must use the ALCS global function.
7.5.7 How a C language application program accesses the global area
If you need to read a global record, or read or write a global field, you must first check whether any
application program modifies the data you want to access. This is important even if your program does
not need to modify the data.
You must also check that your system programmer has created the header file <c$globz.h> for your
installation. Note that <c$globz.h> differs from installation to installation, it is not provided with ALCS.
ALCS Installation and Customization describes how to create the header file <c$globz.h>.
Read-only access to global records and fields
If no application programs modify the data you want to access, you can use the glob function. The glob
function returns a void pointer to the specified global data. If this is a global field, you can access the
data by casting this pointer as appropriate (remember, you must not modify the field). For example, if
_BYTE is a 1-byte global field, you might code:
#include <tpfglbl.h>
#include <c$globz.h>
..
.
my_variable=(unsigned char V) glob(_BYTE);
If the data is a global record, you use the pointer returned by the glob function to access your struct for
the record. (There is an example in the description of the glob function in ALCS Application Programming
Reference – C Language.) Again, remember that you must not modify any of the fields in the global
record.
Serializing access to globals
If any application program modifies the data you want to access, you must use the special serializing
facilities provided by the global function (see the ALCS Application Programming Reference – C
Language). You must use these serialization facilities even if your program does not modify the data.
Because the global function only provides a subset of the facilities available to assembler language
programs, you might need to call an assembler program to access read-write globals. In particular:
5 You cannot use the global function with global records (only with global fields). If your application
needs to access read-write global records, you must call an assembler language program to do this.
5 The global function serialization facilities involve significant processing overheads. If your application
is performance sensitive and requires many global area accesses, then you might need to call an
assembler language program which can use more efficient methods to serialize accesses.
5 The global function serialization facilities only serialize accesses correctly when all programs that
access the field use compatible serialization methods. These are:
– C language programs use the global function
– Assembler programs use the CORHC, CORUC, or SYNCCs.
106
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
If some programs use different serialization methods (available only in assembler programs) then you
must call an assembler program to access the data using the appropriate serialization method.
Using the global function
To access a read-write global field, you must first lock the field (using the GLOBAL_LOCK value of the
action parameter of the global service). After locking the field, you can access it using the
GLOBAL_COPY value of the action parameter of the global function.
If you do not need to modify the field, you can then unlock it using the GLOBAL_UNLOCK value of the
action parameter of the global function.
If you need to modify the field then you must do so using the GLOBAL_MODIFY value of the action
parameter of the global function. You must then use the GLOBAL_SYNC (not the GLOBAL_UNLOCK)
value of the action parameter of the global function to unlock the field.
TPF compatibility
If your program must be compatible with TPF, use the modec function to ensure that all accesses to the
global area (fields or records) are in 31-bit addressing mode.
The modec function has no effect under ALCS. All ALCS C programs run in 31-bit addressing mode.
7.5.8 ALCS services for global area handling
ALCS provides the following assembler macros and C functions for use in application programs:
Note: See also 7.6.3, “Additional ALCS services for TPF compatibility” on page 109.
Assembler
macro
function
Used to
glob
Address application global field or global record; this allows you read-only
access to a global field or global record
global
This function allows you to update, modify, keypoint, lock, unlock, and
synchronize a global field
GLOBZ
Establish the DSECT and the base register for a global area directory and for
the directly-addressable global records or records which follow the directory
GLOUC
Write keypointable records from the application global area to DASD
KEYUC
Write keypointable records from the application global area to DASD
SYNCC
global
Synchronize access to the application global area
Note: In ALCS, GLOUC and KEYUC both have the same effect.
7.6 Globals — compatibility with TPF
If your application program must be compatible with TPF, you must be aware of how TPF uses the global
area.
Chapter 7. Data in ALCS
107
Data
7.6.1 TPF global areas
TPF uses different storage protect keys for the three different global areas.
Some parts of the global area have the same protect key as the ECB and working storage blocks. These
parts are called unprotected globals. Application programs have read (fetch access) and write (store
access) to unprotected globals.
Other parts have a different key. These are called protected globals.
Application programs have fetch access, but not store access, to protected globals. You can get store
access to protected globals by changing the PSW protect key.
To change the PSW protect key, use TPF’s GLMOD or KEYCC. After updating the global area, use FILKW or
KEYRC to restore the previous protect key.
While the application program has store access to the protected global area, it cannot update the ECB,
working storage blocks, or unprotected globals. However, it can read them, because they are not fetch
protected by TPF. Figure 74 describes the TPF global areas.
Figure 74. TPF global areas
Global
area
Protection
Contents
1
Protected
Global area directory 0 (GL0BA)
Directly-addressable global records
Indirectly-addressable global records
2
Unprotected
Indirectly-addressable global records
3
Protected
Global area directory 1 (GL0BY)
Directly-addressable global records
Indirectly-addressable global records
Note: Global records which are not directly addressable may be either protected or unprotected,
depending on the requirements of your installation.
7.6.2 Using the ALCS global areas compatibly with TPF
Figure 75 describes the ALCS global areas.
Figure 75. ALCS global areas
Global
area
Protection
Contents
1
Unprotected
All ALCS global area directories
Directly-addressable global records
Indirectly-addressable global records
2
Unprotected
Indirectly-addressable global records
3
Unprotected
Indirectly-addressable global records
The ALCS global area directories are all held in global area 1. However, to allow for compatibility with
TPF, ALCS supports macro usages which refer to global area 3 under TPF. Under ALCS, these macros
refer to the second global directory (GL1BA). The REGS parameter of GLOBZ is an example of this kind of
macro usage. There are no TPF equivalents to the ALCS directories GL2BA, GL3BA, and so on.
108
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
Updating ALCS global areas
If you are not using ALCS global protection, you do not need to use the GLMOD or KEYCC to update an
ALCS global area. However, if you are using ALCS global protection, see the GLBLPROT parameter on
the ALCS system generation SCTGEN macro in the ALCS Installation and Customization Manual, or, if
you must remain compatible with TPF, use GLMOD or KEYCC when you update records in global areas 1
or 3. You should update records in global areas 1 or 3 as follows:
1. Issue GLMOD before storing into global areas 1 or 3.
2. Between GLMOD and FILKW, do not:
Store into the ECB or working storage blocks
Store into global area 2
Issue any monitor-request macro.
3. Issue FILKW after storing into global areas 1 or 3.
Figure 76 shows this procedure. It updates fields in global area 1, in a directly-addressable record
following directory 0 (GL0BA). The GL0BA directory slot @GBLCC contains the storage address and file
address of the record.
GLOBZ
GLMOD
MVC
ST
FILKW
REGR=R3
GLOBAL1
@FIELD1,EBW
R7,@FIELD2
R,@GBLCC
ADDRESS GLBA AND ADJACENT RECORDS
ACCESS PROTECTED GLOBAL
UPDATE A FIELD IN @GBLCC
UPDATE ANOTHER FIELD IN @GBLCC
RESTORE KEY AND KEYPOINT
Figure 76. Updating global area fields in TPF-compatible programs
7.6.3 Additional ALCS services for TPF compatibility
If your programs must be compatible with TPF you can use the following assembler macros and C
function in addition to those shown in 7.5.8, “ALCS services for global area handling” on page 107.
Assembler
macro
C function
Used to
FILKW
Reverse the effect of GLMOD and keypoint a global record
GLMOD
Set the protect key to allow access to a protected global area
KEYCC
Set the protect key to allow access to a protected global area
KEYRC
Restore the protect key to the entry storage key after access to a protected
global area
modec
Change the addressing mode of a C language program
7.7 Using Structured Query Language (SQL)
ALCS application programs can use SQL to retrieve and modify data held in relational databases
managed or accessed by DATABASE 2* (DB2*). For example, an application can build a record on the
real-time database, then use SQL to update a relational database for subsequent use by other
applications.
Chapter 7. Data in ALCS
109
Data
7.7.1 Preparation
The DB2 precompiler produces an output source module that is the same as the input source module,
except that SQL statements are replaced by instructions or statements in the appropriate language. For
example, in assembler language programs, the DB2 precompiler replaces SQL statements with assembler
DSECTs, BALR instructions, and so on. In order to allow reentrant programs, the precompiler puts all the
variables and structures it generates into a DSECT (array) called SQLDSECT, and generates a fullword
called SQLDSIZ (sqldsiz) which contains the length of the DSECT (size of the array).
Assembler programs must allocate an area of size SQLDSIZ (for example, in an attached storage block),
set it to zeros, and provide addressability to it as the DSECT SQLDSECT.
7.7.2 Making SQL calls
For detailed information about coding SQL statements in application programs, see IBM DATABASE 2
Application Programming and SQL Guide.
SQL communication area (SQLCA)
When an application program includes executable SQL statements, it must be able to communicate with
DATABASE 2. For it to do this, you must provide an SQL communication area (SQLCA) in the program
by coding an EXEC SQL INCLUDE SQLCA statement.
Assembler programs must allocate an area for the SQLCA (for example, in an attached storage block),
and provide addressability to that area.
When DB2 completes processing an SQL statement, it sends back a return code in field SQLCODE in the
SQLCA. The application program should test the return code to examine the results of the operation. For
information about possible return code values, refer to IBM DATABASE 2 Messages and Codes.
In application programs you can use the DSNTIAR service to convert an SQL return code to a text
message.
SQL descriptor area (SQLDA)
If the application program includes a varying-list SELECT statement, you must also provide an SQL
descriptor area (SQLDA), by coding an EXEC SQL INCLUDE SQLDA statement.
Assembler programs must allocate an area for the SQLDA (for example, in an attached storage block),
and provide addressability to that area.
Coding SQL calls
For detailed information about including SQL statements in application programs, refer to IBM
DATABASE 2 Application Programming and SQL Guide and Common Programming Interface Database
Reference.
You can code an SQL statement at any place in an assembler program where you can use an assembler
instruction. The SQL statement must begin with EXEC SQL. You can use a non-blank character in column
72 to continue the statement on a further record. For example, an UPDATE statement would look like
this:
110
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
EXEC SQL
UPDATE DSN822.DEPT
SET MGRNO = :MGRNUM
WHERE DEPTNO = :INDEPT
X
X
X
Figure 77. An SQL UPDATE statement — assembler
You can code an SQL statement at any place in a C language program where you can place an
executable C statement. The SQL statement must begin with “EXEC SQL.” The remainder of the
statement can appear on the same line and on following lines, terminated with a semicolon (;).
All SQL keywords must be in uppercase, and “EXEC SQL” must be on one line. For example:
EXEC SQL
UPDATE DSN822.DEPT
SET MGRNO = :mgrnum
WHERE DEPTNO = :intdept;
Figure 78. An SQL UPDATE statement — C language
7.7.3 Distributing application logic across several programs
ALCS allows SQL application logic to be distributed across several application programs. While the
application is processing an entry, it can execute several separate units of recovery. A unit of recovery
starts when the first DATABASE 2 object updates occur. It ends when the application program issues a
subsequent COMMIT or ROLLBACK statement, or when it exits.
If the application program requests the EXITC (exit) service before a unit of recovery has ended, ALCS
issues an implied COMMIT on its behalf.
If the application program terminates abnormally before a unit of recovery has ended, (for example, it
requests a SERRC (serrc_op) service with a SERRC_EXIT value of the status parameter), ALCS issues an
implied ROLLBACK on its behalf.
For more information about SQL, see DATABASE 2, Application Programming and SQL Guide.
7.8 Designing databases for use with ALCS
For information on designing databases, see ALCS Concepts and Facilities.
7.8.1 Performance and design
The record size that you chose for storing a particular type of data can make a big difference to the
performance of your application.
If the record size is too small, many of your prime records require overflow records and your application
often needs to do several reads to retrieve the data. Your application will run much faster and use less
processor power if it can retrieve the data with a single read.
But if the record size is too large, it will waste space both in the processor memory and on DASD. Also,
large records take slightly longer to read than small ones (in practice, the extra time taken to read large
records is unlikely to make much difference to the performance of your application).
Chapter 7. Data in ALCS
111
Data
As a general guide, you should try to chose a record size large enough that it rarely requires an overflow.
It is almost always better to chose a size that is too large rather than too small. The reasons for this
include:
112
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
Product-Sensitive Programming Interface
5 When your application requests a storage block, ALCS takes that storage from a much larger area
that is preallocated for the entry. Using a larger block (for a larger record size) may not actually
increase the storage that the entry uses.
End of Product-Sensitive Programming Interface
5 When your application program completes processing an entry, all the storage it uses is released for
use by other entries. The effect of keeping smaller amounts of storage (for small record sizes) for a
longer time (waiting for reads to complete) can be to increase the total amount of storage that ALCS
needs to process entries.
5 Very small record sizes, such as 381-byte L1 records, use DASD space inefficiently. For typical
modern DASDs, 381-byte records “waste” approximately half the available DASD space because of
the gaps which separate consecutive records.
5 As applications develop over a period of years, it often happens that they need to store more and
more information. What seems like an ideal record size today may prove too small in years to come.
The IPARS seat reservation application was originally designed to store passenger data in 381-byte
records. At the time, this was big enough to hold the information for a typical passenger. Increasing
sophistication of airline reservation systems means that the information saved for each passenger
requires, on average, a chain of two or more 381-byte records.
7.8.2 TPF Database Facility (TPFDF)
IBM’s TPFDF product allows a data administrator (instead of the application programmer) to specify the
record sizes to use for specified data. Subsequently, the data administrator can change the record sizes if
required to improve performance – this does not require changes to the application programs that access
the data.
7.8.3 Portability
To make your application as portable as possible, avoid organizing your data in a way that makes your
application programs contain dependencies on particular record sizes. For example, if your application
uses L5 records and depends on each L5 record containing (say) 16KB of application data then it may be
difficult to port the application to an ALCS system that has a different size for L5 records or to a TPF
system (TPF does not support size L5).
The IBM TPFDF product makes this particularly easy to do. TPFDF allows your program to store and
retrieve data without knowing the record size that TPFDF is using for the data. TPFDF automatically
handles overflow and chaining for you. (This is only one benefit of using TPFDF – there are many
others.)
Even if you do not use TPFDF, you can program to reduce or eliminate dependencies on record sizes.
For example, you should avoid using a constant as the size (number of bytes) of a record. One way to do
this is to define a symbol for the record size in an assembler data macro, C header file, or COBOL
WORKING-STORAGE SECTION.
This allows you to change the value of the symbol and reassemble or recompile the program if a different
installation chooses to use a different record size. Better still is to have your program determine the
record size at execution time. Your programs can do this by reading the record and loading the size from
the storage level (see 7.2, “Reading and writing DASD records” on page 84).
Chapter 7. Data in ALCS
113
Data
7.9 Organizing data
The way that you organize the data in your ALCS database – how you use lists, indexes, and other
structures – can make a big difference to the performance of your application.
As a general rule, you should aim to minimize the number of records that your application must read to
access the data that it needs.
You must also consider how your application will serialize access to the data, see 7.3, “Serialization” on
page 87.
7.9.1 Standard structures
The ALCS Recoup facility (described in ALCS Installation and Customization) supports a number of
“standard” structures for lists, indexes, and so on. IBM recommends you to use these standard structures,
where possible, rather than inventing new ones.
7.9.2 TPF Database Facility (TPFDF)
Designing and coding application programs to access data through structures of lists, indexes, and so on
can be a complex and time-consuming task. Also, over time the amount of data that you store can
change. If it increases, you may need to introduce indexes to improve performance. If it decreases,
existing index structures may become an unnecessary overhead. The cost of changing existing
application programs to do this can prevent you from optimizing your application's performance.
TPFDF makes the initial designing and coding of the application, and subsequent optimization, particularly
easy to do. TPFDF allows your program to store and retrieve data without knowing the indexes, lists, and
so on that TPFDF is using for the data. It also allows your database administrator to change the
structures, for example by adding or deleting indexes, without requiring any changes to the application
programs.
See the -- Heading 'BIB' unknown -- for information about TPFDF.
7.10 Record classes
There are three different classes of records for application use on the ALCS real-time database: fixed
file, long-term pool file, and short-term pool file. The long-term pool file and short-term pool file are
sometimes referred to collectively as “pool file” or just “pool”.
7.10.1 Fixed files
ALCS application programs access fixed files in much the same way that any application accesses direct
access (sometimes called “random access”) files. To access a particular record, the application specifies
the file and the relative record number of the record within the file.
ALCS application programs do not use data set names or file names for fixed files. Instead, they use a
special token called the fixed-file record type (in TPF, this is called the “FACE ID”). In ALCS, the
relative record number is called the fixed-file record ordinal number (in TPF, it is called the “FACE
ordinal”). Before actually reading or writing a fixed-file record, ALCS application programs use an ALCS
service to convert the fixed-file record type and ordinal into a 4-byte token called the file address.
114
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
ALCS application programs cannot create or delete fixed files, and they cannot change the number of
records in a fixed file. (Your system programmer or database administrator does these things.)
7.10.2 Pool files
In addition to the fixed files, ALCS supports a number of large pools of records. ALCS application
programs do not specify the file and the relative record number of a particular pool-file record. Instead,
they use an ALCS monitor service to allocate a record from one of these pools. This service is called
dispense.
The monitor service returns a file address that the application stores as a pointer in another record. For
example, an application program might use a pool-file record as an overflow record – storing its file
address in the prime record. Alternatively, the application program might store the file address in a list or
index record. Both these methods are described in ALCS Concepts and Facilities.
Note that to the application program it is unimportant which pool record ALCS allocates. However it is
important that the record is not already in use for some other purpose.
Subsequently, application programs access the record using the stored file address.
Note: An exception to this general rule is the PNR locator used in airline seat reservation systems.
These systems store passenger information in passenger name records (PNRs). PNRs are pool
records, and the application saves the file address of the PNR in another record (the passenger
name index) in the normal way. But the application also generates an encoded form of the file
address of the prime PNR. This encoded file address is called the PNR locator. The passenger is
provided with the PNR locator (it is, for example, printed on the ticket).
Since the PNR locator is effectively the file address of the prime PNR, the application can use it to
retrieve the PNR directly, without first accessing the passenger name index.
Eventually, if the data contained in the record is no longer needed, an application program can clear the
saved file address to zeros and use an ALCS monitor service to return the record to the available pool.
This service is called release.
7.10.3 Short-term pool file
Application programs can use short-term pool-file records to store data for short periods of time – a few
seconds or minutes.
Your application must release a short-term pool-file record within, at most, a few hours after the dispense.
If it does not release a short-term pool record within a reasonable time (typically 24 hours), ALCS releases
the record itself.
The actual amount of time before ALCS releases a short-term pool record depends on the rate at which
applications dispense and release short term pool. If many applications fail to release short-term pool
records, then the short-term pool becomes depleted (there are no available records left). To prevent
short-term pool depletion, ALCS dynamically adjusts the amount of time before it releases records itself.
IBM recommends that your system programmer or database administrator allocates enough short-term
pool records to ensure that this amount of time is 24 hours or more. But under conditions of exceptional
load, the actual time can be less than 24 hours.
A short-term pool-file record becomes available immediately after the release which means that the record
can be reused, destroying its previous contents. It is important to ensure that your application clears any
pointer to a short-term pool record to zeros before it releases the record.
Chapter 7. Data in ALCS
115
Data
Your system programmer or database administrator can allocate one short-term pool file for a record size.
For example, your installation may have four short-term pool files, one for for each of the sizes L1, L2, L3,
and L4.
7.10.4 Long-term pool file
Unlike short-term pool-file records, application programs can use long-term pool-file records to store data
for long periods of time – days, weeks, or years.
Like short-term pool-file records, your application should release a long-term pool record when the
information it contains is no longer required. And it is important to ensure that your application clears any
pointer to a long-term pool record to zeros before it releases the record.
But unlike short-term pool-file records, there is no time limit within which your application must release a
long-term pool record. Also, a long-term pool record does not become available immediately after the
release. Instead, an ALCS utility called Recoup must check that there are no pointers to the record saved
in the ALCS database before ALCS allows the record to be reused.
Your system programmer or database administrator can allocate one long-term pool file for a record size.
For example, your installation may have four long-term pool files, one for for each of the sizes L1, L2, L3,
and L4.
7.10.5 Choosing which class of record to use
For most ALCS applications, you will need to organize records in a way that combines efficient access
(minimizing the number of DASD I/Os) with efficient use of space (minimizing the number of “wasted”
records on the database).
You may need to design records in a way that allows overflow from a prime record to a chain of one or
more overflow records. In general, always use pool files for overflow records, even when the prime record
is a fixed-file record. Your application will only need to access an overflow record after it retrieves the
prime record (which contains the file address of the overflow record).
You may need to use list or index records to contain the addresses of the prime records. If so, use pool
file for both the prime records and the overflow records. Your application does not need to calculate the
file address of a particular prime record, because it gets the address from the list or index record.
It is often appropriate to use fixed file for list or index records (but only for the prime record – use pool file
for overflow list or index records).
When you are deciding between using long-term or short-term pool file, be aware that short-term pool file
is only suitable for transient data. You cannot safely store information in short-term pool for more than a
few hours. If your application routinely stores data for many hours in short-term pool records, you risk not
only losing that data, but also depleting the pool. This may force ALCS to reuse other short-term pool-file
records containing data belonging to other applications.
Also, short-term pool is much less secure than long-term pool. If an application error prematurely releases
a short-term pool record, or if ALCS itself releases the record while it still contains data then that data is
lost.
116
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
7.11 Commit and backout
When an entry needs to update several records, it can be important to be sure that either all the updates
complete (the entry completes normally) or none of them do (the entry fails). An example is electronic
funds transfer in banking applications. A transfer consists of debiting one account and crediting another.
If the program that is doing this debits one account and then abnormally terminates then money
“disappears”. This situation can arise because of application programming errors, or it can happen
because of equipment (hardware) errors or failures.
7.11.1 Single-phase commit
Many transaction processing systems include facilities that help protect the database against incomplete or
inconsistent updates when a transaction fails part way through. These systems allow an application to
identify a group of related database updates. For each group of related updates, the system guarantees
one of the following actions:
Commit
The system writes all of the updated records to the database. There are two types of commit:
5 The application requests the commit service from the transaction processing system.
5 The application completes normally (without error). This is called implied commit.
Backout
The system writes none of the updated records to the database. There are two types of backout:
5 The application requests the backout service from the transaction processing system.
5 The application completes abnormally (with error). This is called implied backout.
Some systems write each record as it is updated and perform backout by restoring the records to their
previous contents. Other systems do not write any records until commit time.
7.11.2 Two-phase commit
If a single set of related updates affects two or more separate databases, a more complex process called
two-phase commit is sometimes used. Two phase commit uses a synchpoint manager, and works as
follows:
1. The synchpoint manager asks each database to commit its part of the set of related updates. Each
database tells the synchpoint manager when it successfully completes this (phase 1) commit process,
2. When all the databases successfully complete the phase 1 commit process, the synchpoint manager
tells all the affected databases. This is phase 2.
If any database does not successfully complete that phase 1 commit, the synchpoint manager asks all
the databases to backout the change.
Chapter 7. Data in ALCS
117
Data
7.11.3 ALCS commit and backout services
ALCS provides single-phase commit services (commit, implied commit, backout, and implied backout) for
SQL updates to relational databases.
ALCS does not provide commit services for updates to the ALCS database, ALCS general files (GDSs), or
sequential files. Also, ALCS does not provide commit services for MQI MQPUT and MQGET.
It is important to remember this when designing and writing ALCS applications. In particular, you should
try to design your applications so that:
5 Each update should leave the database in a consistent form. There is a particular technique (see
7.11.5, “Sequential update technique”) that you can use to help achieve this.
5 Errors and inconsistencies in the database do not cause your application programs to “crash”.
Instead, your applications should detect and report this type of problem (possibly by requesting a
system error dump) in a way that helps your database administrator, end user, or whoever is
appropriate to take the required corrective action.
Note: On a typical ALCS system, only a very small proportion of entries (less than one in a million) fail
leaving inconsistent updates. However you can significantly reduce this proportion, and reduce the
undesirable consequences, by following the guidelines described here.
7.11.4 Keeping a transaction log
Many ALCS users find it useful to keep a record of some or all input messages. You may be able to use
a log of this type to help correct errors or inconsistencies in your database.
If you want to do this, you can write the input messages to an ALCS real-time sequential file.
7.11.5 Sequential update technique
By planning the sequence in which you update records on the database you can minimize, or even or
eliminate the possibility of being left with inconsistent data should a hardware or software error occur.
Most ALCS databases store the vast majority of the data in long-term pool records. Applications access
long-term pool records using a pointer (file address) stored in another record (the “refer-from” record).
You can exploit this to avoid introducing inconsistencies in the database when adding or changing
complex structures.
Adding a new structure
You can add a new structure, which can be either a chain of records or a more complex structure
including lists and indexes. See Figure 79 on page 119 for a list of actions.
118
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
Fixed or
pool storage
────────────
('refer-from' record)
Main storage
────────────
(processing)
Long-term pool storage
──────────────────────
(data records)
1. Obtain the pool records required to contain the data:
┌─ ─ ─ ┐
│ XX
│
└─ ─ ─ ┘
┌─ ─ ─ ┐
│
│
└─ ─ ─ ┘
┌─ ─ ─ ┐
│
│
└─ ─ ─ ┘
┌─ ─ ─ ┐
│ XX
│
└─ ─ ─ ┘
┌─ ─ ─ ┐
│
│
└─ ─ ─ ┘
┌─ ─ ─ ┐
│
│
└─ ─ ─ ┘
┌─ ─ ─ ┐
│ XX
│
└─ ─ ─ ┘
┌────
┌──────┐ ┌──────┐
│ AAAA │ │ BBBB │
└──────┘ └──────┘
2. Build the data in the records:
┌────
┌──────┐ ┌──────┐
│ AAAA │ │ BBBB │
└──────┘ └──────┘
3. Write the records:
┌────
┌──────┐ ┌──────┐
│ AAAA │ │ BBBB │
└──────┘ └──────┘
4. Read the 'refer-from' record with record hold:
┌──────┐
│ XX
│
└──────┘
┌─ ─ ─ ┐
│ XX
│
└─ ─ ─ ┘
┌────
┌──────┐ ┌──────┐
│ AAAA │ │ BBBB │
└──────┘ └──────┘
5. Store the pointer to the structure in the 'refer-from' record:
┌────;
┌──────┐
│ XXY │
└──────┘
┌─ ─ ─ ┐
│ XX
│
└─ ─ ─ ┘
┌────
┌──────┐ ┌──────┐
│ AAAA │ │ BBBB │
└──────┘ └──────┘
6. Write out the updated record and unhold it:
┌────;
┌──────┐
│ XXY │
└──────┘
┌──────────────
┌────
┌──────┐
┌──────┐ ┌──────┐
│ XXY │
│ AAAA │ │ BBBB │
└──────┘
└──────┘ └──────┘
Figure 79. Adding a new structure
If your application (or the entire ALCS system) fails before this process is complete, then the database
does not contain a pointer to the partially built structure. (The records in the structure are “lost”, but will
eventually be recovered for reuse by Recoup.)
Note that the above sequence only requires the entry to lock one record (the “refer-from” record), and only
for the short time taken to update the pointer.
Updating a structure
You can update a structure using a sequence of actions as shown in Figure 80 on page 120. (The
starting structure is assumed to be the structure added in Figure 79.)
Chapter 7. Data in ALCS
119
Data
Main storage
────────────
(processing)
Fixed or
pool storage
────────────
('refer-from' record)
Long-term pool storage
──────────────────────
(data records)
1. Obtain new pool records:
┌──────────────
┌─ ─ ─ ┐
┌─ ─ ─
│ XXY │
│ AAAA
└─ ─ ─ ┘
└─ ─ ─
┌────
┐ ┌─ ─ ─ ┐
│ │ BBBB │
┘ └─ ─ ─ ┘
┌─ ─ ─ ┐
│
│
└─ ─ ─ ┘
┌─ ─ ─ ┐
│
│
└─ ─ ─ ┘
2. Copy the data from the existing records into the new pool records:
┌────
┌──────┐ ┌──────┐
│ AAAA │ │ BBBB │
└──────┘ └──────┘
┌──────────────
┌─ ─ ─ ┐
┌─ ─ ─
│ XXY │
│ AAAA
└─ ─ ─ ┘
└─ ─ ─
┌────
┐ ┌─ ─ ─ ┐
│ │ BBBB │
┘ └─ ─ ─ ┘
┌─────
┌──────┐ ┌──────┐
│ AAAA │ │ BBBB │
└──────┘ └──────┘
┌────
┐ ┌─ ─ ─ ┐
│ │ BBBB │
┘ └─ ─ ─ ┘
┌─────
┌──────┐ ┌──────┐
│ CCCC │ │ DDDD │
└──────┘ └──────┘
┌────
┐ ┌─ ─ ─ ┐
│ │ BBBB │
┘ └─ ─ ─ ┘
┌─────
┌──────┐ ┌──────┐
│ CCCC │ │ DDDD │
└──────┘ └──────┘
┌────
┐ ┌─ ─ ─ ┐
│ │ BBBB │
┘ └─ ─ ─ ┘
┌─────
┌──────┐ ┌──────┐
│ CCCC │ │ DDDD │
└──────┘ └──────┘
3. Update the new records:
┌────
┌──────┐ ┌──────┐
│ CCCC │ │ DDDD │
└──────┘ └──────┘
┌──────────────
┌─ ─ ─ ┐
┌─ ─ ─
│ XXY │
│ AAAA
└─ ─ ─ ┘
└─ ─ ─
4. Read the 'refer-from' record with record hold:
┌────;
┌─ ─ ─ ┐
│ XXY │
└─ ─ ─ ┘
┌──────────────
┌─ ─ ─ ┐
┌─ ─ ─
│ XXY │
│ AAAA
└─ ─ ─ ┘
└─ ─ ─
5. Replace the pointer in the 'refer-from' record:
┌────;
┌──────┐
│ XXZ │
└──────┘
┌──────────────
┌─ ─ ─ ┐
┌─ ─ ─
│ XXY │
│ AAAA
└─ ─ ─ ┘
└─ ─ ─
6. Write out the updated record and unhold it:
┌────;
┌──────┐
│ XXZ │
└──────┘
┌───────────────────────────────────┐
│
┌────
┌─────
┌──────┐
┌─ ─ ─ ┐ ┌─ ─ ─ ┐
┌──────┐ ┌──────┐
│ XXZ │
│ AAAA │ │ BBBB │
│ CCCC │ │ DDDD │
└──────┘
└─ ─ ─ ┘ └─ ─ ─ ┘
└──────┘ └──────┘
7. Release the pool records previously used to contain the structure:
┌────;
┌──────┐
│ XXZ │
└──────┘
┌───────────────────────────────────
┌─────
┌──────┐
┌──────┐ ┌──────┐
│ XXZ │
│ CCCC │ │ DDDD │
└──────┘
└──────┘ └──────┘
Figure 80. Updating a new structure
Your application can fail at any stage in this process without leaving any reference to a partially updated
structure. Again, the above sequence only requires the entry to lock one record (the “refer-from” record),
and only for the short time taken to update the pointer.
7.11.6 Why ALCS does not provide a synchpoint manager
If you are happy that ALCS does not provide commit and backout services for its database and that it only
provides single-phase commit for SQL, you can skip this section. If you think that ALCS should provide
comprehensive commit and backout services, or if you are interested to know why it doesn't, then you
should read this section.
It might appear obvious that any transaction processing system should provide services to prevent
inconsistent or partial updates to the database – particularly since many systems do provide these
services.
120
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data
These services provide the following main benefits:
5 They safeguard your data by backing out partly completed transactions when an equipment
(hardware) or system program (software) failure terminates the entries.
5 They safeguard your data by backing out partly completed transactions when an application
programming error terminates the transactions.
5 They simplify application program design and coding by making the system responsible for database
consistency instead of the application program.
However, commit and backout facilities impose significant overheads. Transaction processing systems
that provide these facilities typically require several times as much processor power as ALCS systems do
for the same transaction rate. Similarly, the restart times for systems that guarantee to backout partly
completed transactions are dramatically longer than ALCS restart times.
7.11.7 Other considerations
Although commit and backout facilities can help reduce inconsistencies in databases, they cannot
guarantee the correctness of the data. Consider the following:
5 It is clearly undesirable if a system failure results in a debit to one bank account without a
corresponding credit to another. However, it is just as serious if a human error causes the wrong
account to be credited or debited (or both).
5 It is clearly undesirable if an application program error terminates a transaction part way through,
leaving inconsistent or incorrect data in the database. However, it is just as serious if an application
programming error stores incorrect or inconsistent data without terminating the transaction abnormally.
And generally, the first type of error is much more quickly identified and corrected than the second
type of error. Abnormal termination is a more obvious symptom than incorrect data on the database.
ALCS is designed to satisfy the requirements of systems where the costs of commit and backout facilities
outweigh the advantages.
Suppose your system processes 1000 transactions per second during the peak hour – equivalent to
perhaps 10 000 000 transactions per day. Suppose also that it runs for 3 months without a system
failure. Your system will probably process something like 2 000 000 000 transactions during the 3 month
period. When the system fails, perhaps 200 transactions will fail part way through. This means that
roughly one transaction in ten million would benefit from a full-blown transaction backout facility.
Admittedly, application programming errors can cause abnormal termination that leaves part-completed
updates. But even a full two-stage commit facility will not protect your database against application
programming errors. Two-phase commit only guarantees to write (or not write) the data provided by the
application. It does not guarantee that the data “makes sense”.
7.12 Utility programs
In addition to the services (assembler macros and C functions) which are used by ECB-controlled
programs, ALCS provides some utility programs that can be used by programs running under MVS:
DXCCDDLD
Load DASD configuration table load module.
DXCMRT
Return the highest used general file number, pool interval number, or fixed-file record type
number.
DXCFARIC
Return information about a supplied file address.
Chapter 7. Data in ALCS
121
Data
These programs are described in more detail in ALCS Application Programming Reference – Assembler.
122
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
Chapter 8. The entry control block (ECB) and other entry
storage
This chapter describes the ECB and other entry storage.
For each entry, ALCS creates a unique 4KB storage area called the entry control block (ECB).
Application programs can use the ECB to hold data and variables needed by a particular entry.
8.1 Format of the ECB
The areas of the ECB which concern the application programmer are shown diagrammatically in Figure 81
on page 124.
Most areas in the ECB consist of several fields. Each field has a label and the area as a whole usually
has a label. In assembler programs labels are in upper case (for example, EBW000). C language labels
are in lower case (for example, ebw).
Alternative names for fields in the ECB
Some fields in the ECB have two different names. One of these names starts with the characters 'EB'
('eb' in C language programs), the other starts with the characters 'CE1' ('ce1').
The two named fields are not necessarily exactly the same (their lengths might be different). In this book,
the most common field name is mentioned first.
Chapter 8. The entry control block (ECB) and other entry storage
123
Entry control block (ECB) and other entry storage
┌────────────────────────────┐
│ Reserved for ALCS's use
│
├────────────────────────────┴─────────────────────────────────────────┐
│ ECB work area 1: EBW - EBW13 (ebw - ebw13)
│
│
┌────────────────────────────┤
│
│ Work area 1 switch bytes
│
├─────────────────────────────────────────┴────────────────────────────┤
│ ECB work area 2: EBX - EBX13 (ebx - ebx13)
│
│
┌────────────────────────────┤
│
│ Work area 2 switch bytes
│
│
│
├─────────────────────────────────────────┴────────────────────────────┤
│ ECB local program work area: EBL - EBL13
│
│
┌────────────────────────────┤
│
│ LPW switch bytes
│
├─────────────────────────────────────────┴────────────────────────────┤
│ Data levels: EBCIDn - EBCFAn, CE1FXn (ebcidn - ebcfan, ce1fxn)
│
├─────────────────────────────────────────┴────────────────────────────┤
│
│
│ Exit intercept information: CE1SXI, CE1SXP, CE1SXEn
"
├──────────────────────────────────────────────────────────────────────┤
│ Storage levels: CE1CR - CE1CRF (ce1cr - ce1crf)
│
│
│
├──────────────────────────────────────────────────────────────────────┤
│ Register save areas: CE1ARS, CE1AFS
│
├──────────────────────────────────────────────────────────────────────┤
│ Entry origin fields: EBROUT (ebrout)
│
├──────────────────────────────────────────────────────────────────────┤
│ Error indicators: EBCSDn (ebcsdn), CE1SUD (ce1sud), CE1SUG (ce1sug) │
├──────────────────────────────────────────────────────────────────────┤
│ User area reserved for system-wide fields: CE1USA (ce1usa)
│
├──────────────────────────────────────────────────────────────────────┤
│ TCP/IP sockets descriptor: CE1SOCK
│
├──────────────────────────────────────────────────────────────────────┤
│ Routing control parameter list: CE1RCPL (ce1rcpl)
│
├──────────────────────────────────────────────────────────────────────┤
│ Reserved for ALCS's use
│
├──────────────────────────────────────────────────────────────────────┤
│ User area areserved for system-wide fields: CE1USA (ce1usa)
│
└──────────────────────────────────────────────────────────────────────┘
Figure 81. Format of the ALCS ECB (schematic)
8.2 ECB work areas 1 and 2
In C language programs you do not normally need to use these work areas, since you can define storage
automatically, as described in 8.15, “Automatically-allocated storage” on page 132. However, you might
need to use one or the other of the work areas to pass data to an assembler program called from a C
program.
The ECB contains two similar work areas, each 104 bytes long, plus 8 bytes of switch data, which
application programs can use. When ALCS creates an ECB, it sets both work areas to binary zeros.
ALCS does not use either work area itself, nor does it check the use that programs make of each work
area.
TPF compatibility
TPF systems might not set the work areas to binary zeros, this is installation-dependent.
124
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
8.2.1 Work area fields
You can access any of the first 104 bytes in either work area by using the names shown in Figure 82.
The assembler name is shown first followed by the C language name (in parentheses).
Figure 82. Names of work area fields
First work area
Second work area
Byte referenced
EBW000 (ebw)
EBX000 (ebx)
1st
EBW001 (ebw1)
EBX001 (ebx1)
2nd
EBW002 (ebw2)
EBX002 (ebx2)
3rd
......
EBW103 (ebw13)
......
.....
EBX103 (ebx13)
104th
The first byte of each work area starts on a doubleword boundary. Each field is 1 byte long (type char).
Switch bytes in work area 1
You can access the fields in this 8-byte area as follows:
EBSW01, EBSW02, EBSW03 (ebsw1, ebsw2, ebsw3): Conventionally, these three 1-byte fields are
used for 1-bit switch data.
EBRS01 (ebrs1): This 1-byte field is intended for 1-bit (switch) data. Application programs
conventionally use it to control application program linkage to assembler programs.
EBCM01, EBCM02, EBCM03 (ebcm1, ebcm2, ebcm3): These three 1-byte fields are conventionally used
for 1-bit (switch) data that is to be transferred between application programs.
EBER01 (eber1): This 1-byte field is conventionally used as an error indicator. Application programs
use it when one program detects an error and another program carries out the error processing. See
Chapter 9, “Error conditions and error processing” on page 146.
Switch bytes in work area 2
Work area 2 also contains 8 switch bytes, as follows:
EBXSW0 – EBXSW7 (ebxsw – ebxsw7): These eight 1-byte fields occupy positions in the second work
area corresponding to fields EBSW01 through EBER01 (ebsw1 through eber1). Application programs
can use these fields in any way.
Alternative names
Both work areas have alternative names:
CE1WKA, CE1WKB (ce1wka, ce1wkb): These are alternative names for the whole of work area 1 or work
area 2. Each has a length of 112 bytes. Use CE1WKA (ce1wka) to refer to work area 1 and CE1WKB
(ce1wkb) to refer to work area 2.
Chapter 8. The entry control block (ECB) and other entry storage
125
Entry control block (ECB) and other entry storage
8.3 ECB local program work area
Use of the local program work area is supported in assembler language programs that specify the BEGIN
macro parameter LPW=YES. It is not supported in C language programs.
TPF compatibility
Do not use the local program work area in programs that must be compatible with TPF.
This work area differs from work areas 1 and 2 in that it is “local” to the program. On entry to the program
ALCS clears the local program work area to binary zeros, so data in this area cannot be passed between
application programs.
When the program issues an ENTRC macro (return expected to this program), ALCS saves the contents of
the local program work area. It restores the contents of the local program work area when control returns
to the program following the ENTRC macro.
When the program issues an ENTNC macro (return to the program that last issued an ENTRC macro), ALCS
does not save the contents of the local program work area.
When the program issues an ENTDC macro (no return expected), ALCS discards all saved copies of the
local program work area.
Note:
1. Transferring control to a transfer vector has the same effect on the local program work area as
described above (that is, depends on the type of transfer). This is true even if the transfer vector is an
entry point in the same program, because the local program work area actually relates to the program
nesting level.
2. Transferring control to an exit intercept program (set by SXIPC macro) when an entry terminates has
the same effect on the local program work area as ENTDC.
Work area fields
You can access any of the first 104 bytes in the local program work area by using the names shown in
Figure 83.
Figure 83. Names of local program work area fields
Name of field
Byte referenced
EBL000
1st
EBL001
2nd
EBL002
3rd
.......
.......
EBL103
104th
The first byte of the local program work area starts on a doubleword boundary. Each field is 1 byte long.
Switch bytes
The local program work area contains 8 switch bytes, as follows:
EBLSW0-EBLSW7: These eight 1-byte fields occupy bytes 105-112 in the local program work area.
126
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
Alternative name
The alternative name for the whole of the local program work area is CE1WKC. This has a length of 112
bytes.
|
8.4 ECB data levels and storage levels
| There are 16 data levels and storage levels in the ECB, represented by the defined symbols D0 for level
0, D1 for level 1, ..., DF for level 15. Data levels and storage levels, used together, are called ECB
levels.
| Note: The data level and storage level in a DECB may be used as an alternative to an ECB level. For
| more details about the use of DECBs see 8.18, “Data event control blocks (DECBs)” on page 136.
|
8.4.1 ECB data levels
Applications (and ALCS) use each data level to identify a DASD record that is about to be read or written.
Each data level contains the following information:
5 2-byte record ID (optional)
5 1-byte record code check (RCC) character (optional).
5 4-byte file address (required).
Note: There is also a 1-byte reserved field in each data level.
Data level fields
The 16 data levels have identical formats. The last character of the field name identifies the level number
(hexadecimal 0 through F). In the following description of the data level labels this last character is
indicated by n.
EBCIDn (ebcidn): When required (or allowed) by the DASD I/O operation, the application program stores
the 2-byte record ID in this field.
EBCRCn (ebcrcn): Optionally for most DASD I/O operations, the application stores the record code
check (RCC) in this 1-byte field.
| EBCFAn (ebcfan): For most DASD I/O operations, the application program stores the file address of the
record it is reading or writing in this 4-byte (long int) field. The 4 bytes have individual names:
EBCFMn (ebcfmn)
EBCFCn (ebcfcn)
EBCFHn (ebcfhn)
EBCFRn (ebcfrn)
For more details of the use of data levels, see 7.2, “Reading and writing DASD records” on page 84.
CE1FXn (ce1fxn): These 16 1-byte (unsigned char) fields are known as the data level extensions.
They are used with the two macros (C functions) that process general data sets: GDSNC (gdsnc) and GDSRC
(gdsrc).
Chapter 8. The entry control block (ECB) and other entry storage
127
Entry control block (ECB) and other entry storage
|
8.4.2 ECB storage levels
ALCS uses 16 storage levels to attach storage blocks (see 8.16, “Storage blocks” on page 133) to the
ECB. Application programs can access storage level fields, but must not modify the contents, except as
described in ALCS Application Programming Reference – Assembler for the ATTAC and some
event-processing macros.
Storage levels contain the following information:
5 4-byte attached storage block address
5 2-byte block size field
5 2-byte block size indicator.
Storage level fields
The 16 storage levels in the ECB each contain 3 fields. As with data level field names, the last character
of the field name identifies the level number (hexadecimal 0 through F). The 3 fields are named CE1CRn
(ce1crn), CE1CCn (ce1ccn), and CE1CTn (ce1ctn).
CE1CRn (ce1crn): ALCS stores in this 4-byte (long int) field the address of the storage block that it
allocates to the program.
CE1CCn (ce1ccn): ALCS normally stores in this 2-byte field the length of the attached block. However,
when a tape read operation produces the error condition “incorrect size (small)” (see Figure 113 on
page 152), this field contains the length of the data read (see 9.4.2, “Recovery from wait-completion
errors” on page 158).
CE1CTn (ce1ctn): ALCS stores in this 2-byte field the block size value. It contains the block type
indicator value, L0, L1, L2, ...L8.
For more details of the use of storage levels, see 7.2, “Reading and writing DASD records” on page 84
and 8.16, “Storage blocks” on page 133.
8.5 Entry origin fields
The ECB contains a number of entry origin fields. EBROUT (ebrout) is the only one which application
programs can use. It is also known as CE1OUT (ce1out).
Application programs can use this 3-byte field to contain the communication resource identifier (CRI) of the
originating terminal (not WTTY). ALCS sets up this field for input messages.
8.6 User register save areas
The ECB contains two register save areas that assembler application programs can use. One area is
provided for general registers and one for floating-point registers. ALCS does not modify these areas.
8.6.1 General registers
Application programs can use the general register save area to save the contents of general registers 0
through 7 (RAC through RGF), 14 (RDA), and 15 (RDB). Figure 84 shows the labels that application
programs should use to refer to the general register save areas:
128
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
Figure 84. Labels for the general register save area
Label
Area referred to
CE1ARS
Entire save area (General registers 14, 15, 0
through 7)
CE1URA
General register 14
CE1URB
General register 15
CE1UR0
General register 0
CE1UR1
General register 1
CE1UR2
General register 2
CE1UR3
General register 3
CE1UR4
General register 4
CE1UR5
General register 5
CE1UR6
General register 6
CE1UR7
General register 7
Figure 85 shows an example of using the general register save area.
..
.
..
.
STM
R14,R7,CE1ARS
SAVE REGISTERS
L
R6,CE1UR6
RESTORE REGISTER 6
LM
R14,R7,CE1ARS
RESTORE REGISTERS
Figure 85. Using the general register save area
8.6.2 Floating-point registers
Figure 86 shows the labels that application programs should use to refer to the floating-point register save
area:
Figure 86. Labels for the floating-point register save area
Label
Area referred to
CE1AFS
Entire save area (floating-point registers 0
through 6)
CE1UF0
Floating-point register 0
CE1UF2
Floating-point register 2
CE1UF4
Floating-point register 4
CE1UF6
Floating-point register 6
Figure 87 on page 130 shows how you can use the floating-point register save area.
Chapter 8. The entry control block (ECB) and other entry storage
129
Entry control block (ECB) and other entry storage
..
.
STD
STD
STD
STD
FP,CE1UF
FP2,CE1UF2
FP4,CE1UF4
FP6,CE1UF6
SAVE FLOATING POINT REGISTERS
LD
LD
LD
LD
FP,CE1UF
FP2,CE1UF2
FP4,CE1UF4
FP6,CE1UF6
RESTORE FLOATING POINT REGISTERS
Figure 87. Using the floating-point register save area
TPF compatibility
TPF does not support the standard labels for the user floating-point save register area in the ECB. If
your program must be compatible with TPF, see the ALCS Application Programming Reference –
Assembler, which explains how you can define extra labels for TPF.
|
8.7 ECB error indicators
| The ECB contains 16 1-byte (unsigned char) error indicators, one for each ECB data level. They are
called EBCSDn (ebcsdn) where n is the data level (0 through hexadecimal F). When a program requests
a WAITC (waitc) service, ALCS might set one or more of these indicators.
For a description of these error indicators and how to test them, see 9.3.1, “Error indicators in the ECB
and DECB” on page 152.
|
8.8 ECB user area reserved for system-wide fields
| Your system programmer can use this 2248-byte field CE1USA (ce1usa) in the ECB to define system-wide
fields, as described in ALCS Installation and Customization.
8.9 TCP/IP socket descriptor
When the ALCS TCP/IP concurrent server (Listener) is started, it waits for connection on a specific TCP/IP
port. When a client connects to that port, the ALCS concurrent server creates a new ECB and passes
control to the installation-wide exit program ATCP if it exists. ALCS puts the TCP/IP socket descriptor for
this connection in a fullword field called CE1SOCK (ce1sock) in the ECB.
8.10 The routing control parameter list (RCPL) area
With each input message, ALCS provides a routing control parameter list (RCPL). The RCPL contains
information which identifies the origin and characteristics of the message. ALCS puts this RCPL in a
112-byte area called CE1RCPL (ce1rcpl) in the ECB.
An output message sent by requesting a ROUTC (routc) service also has an RCPL associated with it. This
identifies the destination (and characteristics) of the message. You can preserve the RCPL received with
the input message and change it to be used as an output message RCPL (for example, by swapping the
origin and destination addresses).
130
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
C language programs that only need to return a message to the originating terminal do not need to use
RCPLs, instead they use stdin and stdout as described in 8.16.1, “Input and output messages” on
page 134. However, by using an RCPL in combination with the C function routc an application program
can:
Send messages to terminals other than the originating terminal.
Send messages to other application programs (or to itself).
Send unsolicited messages to one or more terminals.
For details of the RCPL contents, see -- Heading 'MES' unknown --.
|
8.11 ECB areas reserved for ALCS use
The ECB contains a number of areas which are reserved for ALCS use. Application programs must not
use (or even refer to) fields unless they are part of the general use programming interface.
8.12 Accessing the ECB
Assembler programs access the ECB using the DSECT EB0EB.
The C data structure describing the ECB is called ebeb, and is defined in the header file <c$ebeb.h>.
Use the C function ecbptr to obtain access to fields in the ECB. (The ecbptr C function returns the
address of the ECB.)
Examples
The following examples show how you could use ecbptr to access three storage level fields.
ce1crn
struct cm1cm Vcm;
/V pointer to message structure V/
/V set pointer to message in block at level 1 V/
cm = ecbptr()->ce1cr1;
ce1ccn
int size;
size = ecbptr()->ce1cc1;
/V get size of block on level 1 V/
printf("size of block on level 1 is %d bytes\n",size);
ce1ctn
if (ecbptr()->ce1ct1 == L2)
/V is block on level 2 size L2 ? V/
puts("L2 size block on level 1");
You can also use the levtest C function to test whether a storage level is in use and to get the size of the
block. See ALCS Application Programming Reference – C Language.
Chapter 8. The entry control block (ECB) and other entry storage
131
Entry control block (ECB) and other entry storage
8.13 Other entry storage
As explained at the start of this chapter, ALCS allocates a unique 4KB ECB for each entry. This means
that ALCS application programs can process several entries at the same time. An application program
can safely store information (for example, an intermediate result) in an ECB field; the same program,
storing into the same ECB field for a different entry stores into a different ECB.
In addition to the ECB itself, ALCS can allocate other unique areas of storage for each entry. Like the
ECB, application programs can store into these areas without interfering with other entries. Storage that
has this property in ALCS is called entry storage.
ALCS application programs can use the following entry storage:
|
|
|
|
The ECB
ECB user data collection area
Automatically allocated storage
Storage blocks
Local save stack
Data event control blocks (DECBs).
8.14 ECB user data collection area
|
|
|
|
|
|
Product-Sensitive Programming Interface
ALCS provides services that allow application programs to update an area of entry storage called the user
data collection area. This area is an optional extension to the ALCS data collection area, and does not
exist unless the size is defined using the DCLECBU= parameter of the SCTGEN macro, as described in
ALCS Installation and Customization. Application programs can use the DCLAC macro to read or update
fields in the user data collection area.
End of Product-Sensitive Programming Interface
8.15 Automatically-allocated storage
High-level language programs usually obtain and use storage by defining variables. In addition, C
language programs can obtain storage by using the calloc, malloc, and related functions, PL/I programs
can obtain storage by using the ALLOCATE function.
At execution time, high-level language programs obtain and manage storage to contain dynamic variables
and to satisfy C language malloc, calloc, and related function calls. They also obtain and manage
storage for register save areas, for library routines to use as work areas, and so on.
As an application programmer, you do not need to understand in detail how your programs obtain and
manage this storage at execution time. The compiler generates code that obtains the storage, as
required, by requesting ALCS services. The services allocate entry storage so that different transactions
use different storage even when the same program is executing. Note that these services are intended for
use only by compiler-generated code – you must not attempt to invoke the services directly.
132
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
8.15.1 Initial storage allocation
When an ALCS ENTER-type service transfers control to a high-level language program, the high-level
language application program obtains a storage area called the initial storage allocation (ISA).
The size of the ISA depends on the version and release of the compiler and library environment, but is of
the order of 100KB.
The ISA storage is released when the high-level language program returns to the calling program, or if it
exits without returning control.
Note that the compiler automatically generates code to obtain and release the ISA. The high-level
language source code does not include any instructions to do these things.
8.15.2 Stack and heap storage
High-level language programs use stack and heap storage to contain dynamic variables.
|
|
|
|
During execution, the programs obtain and release stack and heap storage when required. The compiler
generates code that manages this storage. This code does not request storage separately for each
variable. Instead, it requests storage in amounts that are a multiple of 64KB for stack storage and 256KB
for heap storage. (In other environments the amounts can be multiples of a different constant.) Typically
a program can store many variables within 256KB, but it is possible that a single variable (for example a
large array) can require more than 256KB.
| When the program requires stack or heap storage, it requests the required amount (in multiples of 64KB
| and 256KB respectively) from ALCS. ALCS does not distinguish between stack and heap. The only
difference between the two is the way that the high-level language program uses the storage. For a
description of how stack and heap are used, see Language Environment Programming Guide.
Whenever an ALCS ENTER-type service transfers control to an HLL program, the entry needs at least
one type 2 storage unit (to hold the ISA) additional to any storage units it is already using. The type 2
storage unit size must be at least large enough to hold the ISA – any remaining space in the first type 2
storage unit is available for use as stack or heap storage.
If the program requires more stack or heap storage than fits in the first type 2 storage unit, ALCS can
allocate additional type 2 storage units.
You need to be aware that the largest contiguous amount of stack or heap storage that an application can
use is a whole type 2 storage unit. You must choose the size for type 2 storage units so that they are
large enough to hold the largest variable (which can be an array or structure) that your application uses.
Note: The system programmer allocates the number and size of type 2 storage units using the NBRSU=
and SUSIZE= parameters of the SCTGEN macro, as described in ALCS Installation and Customization
8.16 Storage blocks
Assembler and C language programs can request blocks of storage. One typical use of a storage block is
to build up a record before writing it to DASD.
An application program can request a block of storage by requesting a GETCC (getcc) service. ALCS
allocates a block of storage of the specified size (L0 through L8). It saves the address and size of that
block in the storage level that the program specifies in the assembler macro or C function call. The
application program can request up to 16 storage blocks to be attached to the ECB at any one time (one
Chapter 8. The entry control block (ECB) and other entry storage
133
Entry control block (ECB) and other entry storage
| on each of the 16 ECB storage levels), and can additionally request one storage block to be attached to
| each allocated DECB.
When an application program has finished using a storage block, it can request ALCS to release the block
by requesting the RELCC (relcc) service. The storage then becomes available for reuse and ALCS clears
| the storage level in the ECB or DECB to indicate that the level is free. ALCS automatically releases all
storage blocks when an entry exits.
A program can test if a storage level is currently in use by requesting the LEVTA (levtest) service.
8.16.1 Input and output messages
ALCS stores an input message in a block and attaches this at storage level 0 (D0) before it enters the first
application program that will process the message. The block containing the message is part of entry
storage.
ALCS treats an input message from a terminal as coming from the standard input stream (stdin)
Application programs can access data from this message using the gets and sscanf C functions.
Application programs can send output to the originating terminal by using C functions that direct output to
standard output stream (stdout). Applications can send messages to other terminals as described later.
See 8.10, “The routing control parameter list (RCPL) area” on page 130.
8.16.2 Entry storage on exit
| The stack, the heap, the ECB, storage blocks and DECBs are all examples of entry storage. ALCS
allocates entry storage automatically as and when your program requires it.
When an entry exits, ALCS releases all this entry storage so that other entries can use it. When ALCS
releases the storage, any information stored there is lost. Of course, if your program has written this
information to DASD, the DASD copy is not lost and can be read by another entry.
8.16.3 Swapping storage levels
Sometimes an application program might need to attach a storage block to a level where there is already
| an attached block. If there is an unused ECB storage level, then the application program can request the
| FLIPC (flipc) service to swap the contents of the two ECB storage levels.
| The application program can then attach a new storage block at the chosen ECB level. Later, it can
| release the new storage block and use flipc again to restore the ECB storage levels to their original
contents. For example, if an application needs to use level 0 (D0) that is already in use, but level 6 (D6)
is not in use, the program could use flipc as follows:
flipc(D,D6);
| An application program can also swap the contents of an ECB storage level and a DECB storage level by
| requesting the DECBC FUNC=SWAPBLK (tpf_decb_swapblk) service.
134
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
8.16.4 Detaching and attaching storage blocks
As an alternative to requesting the FLIPC (flipc) service, you can request the DETAC (detac) service. This
detaches a block from a specified level but does not release the block. The program can then attach a
new storage block at the detached level.
Later the application program can release the new storage block and request the ATTAC (attac) service to
reattach the original storage block.
| In the example in Figure 88, an application needs to use ECB level 2 (D2), which is already in use. It
| uses DETAC to detach the block at level 2 (D2), and later uses ATTAC to reattach the block on the same
level.
..
.
MVC
EBW(8),CE1FA2
DETAC D2,ADDRESS
SAVE FILE ADDRESS
DETACH BLOCK AT LEVEL 2
MVC
CE1FA2(8),EBW
ATTAC D2,FA
SET UP FILE ADDRESS
REATTACH BLOCK
Figure 88. Detaching and attaching a storage block – assembler
| If an application needs to use ECB level 0 (D0), which is already in use, a C language program could use
the detac and attac functions as shown in Figure 89.
detac(D);
/V
program uses level D
..
.
attac(D);
V/
Figure 89. Detaching and attaching a storage block – C language
A block detached by DETAC (detac) service does not use a storage level, but ALCS still regards the block
as belonging to the entry.
8.16.5 Storage block activity control
ALCS assumes certain storage block usage characteristics. If an application includes entries that use
more than 10 or 15 storage blocks simultaneously, the application program might need to request the
SLIMC (slimc) service to increase the amount of storage that the entry is allowed to use.
Note: The maximum number of blocks that you can use is system-dependent; see ALCS Installation and
Customization for details. A C language application program might also need to call the slimc function if it
uses a large amount of heap or stack storage.
It may also be necessary to change the activity control parameters. ALCS Operation and Maintenance
describes how to do this.
8.16.6 ALCS services for handling storage blocks
ALCS provides the following assembler macros and C functions for handling storage blocks:
Assembler macro
C Function
Used to:
ATTAC
attac
Reattach a storage block after a DETAC.
Chapter 8. The entry control block (ECB) and other entry storage
135
Entry control block (ECB) and other entry storage
|
|
|
|
|
|
|
Assembler macro
C Function
Used to:
DECBC FUNC=SWAPBLK
tpf_decb_swapblk
Swap the contents of an ECB storage level and
a DECB storage level. tpf_decb_swapblk does
not exchange the contents of data levels and
detail error indicators.
DETAC
detac
Detach the storage block from a level but do not
release it.
FLIPC
flipc
Flip (exchange) the contents of two ECB
storage levels. FLIPC also exchanges the
contents of ECB data levels and detail error
indicators.
GETCC
getcc
Get a storage block and attach it to a level.
LEVTA
levtest
Test if a storage block is attached to a specified
level.
RELCC
relcc
Detach a storage block from a level and release
it.
Note: In addition to the above, some ALCS services either get and attach, or detach and release, a
storage block as part of the requested service. For example, FINDC (findc) automatically gets and
attaches a storage block and reads a DASD record into it.
8.17 Local save stack
An application program can request a SAVEC service to save and restore the contents of one or more of:
5
5
5
5
5
The general purpose registers
The floating point registers
ECB work area 1 (CE1WKA)
ECB work area 2 (CE1WKB)
ECB local program work area (CE1WKC).
SAVEC uses a last-in first-out (LIFO) stack, called the local save stack, to save the information. The local
save stack uses entry storage and is “local” to your program. For full details of the SAVEC service see
ALCS Application Programming Reference – Assembler.
Note: ALCS does not provide SAVEC support for C language programs.
TPF compatibility
Do not use the SAVEC service in programs that must be compatible with TPF.
|
8.18 Data event control blocks (DECBs)
|
|
|
|
|
An application can use a data event control block (DECB) as an alternative to using an ECB level. An
ECB level is used to identify a DASD record that is about to be read or written and to attach a storage
block. Although a DECB does not physically reside in an ECB, the DECB fields specify the same
information without requiring the use of a level in the ECB. The same requirements and conditions that
apply to the fields in the ECB level also apply to the equivalent fields in the DECB.
136
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
┌────────────────────────────────────────────────────────────────────────┐
│ DECB name: IDECNAM (idecnam)
│
├────────────────────────────────────────────────────────────────────────┤
│ Reserved
│
├────────────────────────────────────────────────────────────────────────┤
│ Storage level: IDECCRW (ideccrw)
│
│
IDECDAD (idecdad), IDECCT (idecct), IDECDLH (idecdlh) │
├────────────────────────────────────────────────────────────────────────┤
│ Data level: IDECFRW (idecfrw)
│
│
IDECRID (idecrid), IDECRCC (idecrcc), IDECFA (idecfa)
│
├────────────────────────────────────────────────────────────────────────┤
│ Error indicator: IDECSUD (idecsud)
│
├────────────────────────────────────────────────────────────────────────┤
│ Reserved
│
├────────────────────────────────────────────────────────────────────────┤
│ Detached block count: IDECDET (idecdet)
│
├────────────────────────────────────────────────────────────────────────┤
│ Data level extension: IDECFX (idecfx)
│
├────────────────────────────────────────────────────────────────────────┤
│ User data: IDECUSR (idecusr)
│
├────────────────────────────────────────────────────────────────────────┤
│ Reserved for ALCS's use
│
└────────────────────────────────────────────────────────────────────────┘
| Figure 90. Format of the ALCS DECB application area (schematic)
|
8.18.1 DECB fields
| The DECB fields which concern the application programmer are described below. The data level and
| storage level, when used together, are called a DECB level.
|
DECB name (IDECNAM (idecnam))
| Optionally when creating a DECB, the application program can give it a name. ALCS stores the name in
| this 16-byte field. If no name is given, this field contains binary zeros.
|
DECB storage level (IDECCRW (ideccrw))
| The DECB storage level corresponds to an ECB storage level and contains the following information:
|
|
|
5 4-byte attached storage block address
5 2-byte block size field
5 2-byte block size indicator.
| IDECDAD (idecdad): ALCS stores in this 4-byte (long int) field the address of the storage block that it
| allocates to the program.
| IDECCT0 (idecct): ALCS stores in this 2-byte field the length of the attached block.
| IDECDLH (idecdlh): ALCS stores in this 2-byte field the block size value. It contains the block type
| indicator value, L0, L1, L2, ...L8.
| For more details of the use of storage levels, see 7.2, “Reading and writing DASD records” on page 84
| and 8.16, “Storage blocks” on page 133.
Chapter 8. The entry control block (ECB) and other entry storage
137
Entry control block (ECB) and other entry storage
|
DECB data level (IDECFRW (idecfrw))
| The DECB data level corresponds to an ECB data level and contains the following information:
|
|
|
5 2-byte record ID (optional)
5 1-byte record code check (RCC) character (optional)
5 8-byte file address (required).
| Note: There is also a 1-byte reserved field in the data level.
| IDECRID (idecrid): When required (or allowed) by the DASD I/O operation, the application program
| stores the 2-byte record ID in this field.
| IDECRCC (idecrcc): Optionally for most DASD I/O operations, the application stores the record code
| check (RCC) in this 1-byte field.
| IDECFA (idecfa): For most DASD I/O operations, the application program stores the file address of the
| record it is reading or writing in this 8-byte (defined type TPF_FA8) field.
| For more details of the use of data levels, see 7.2, “Reading and writing DASD records” on page 84.
|
DECB error indicator (IDECSUD (idecsud))
| This 1-byte field corresponds to an ECB detail error indicator. When a program requests a WAITC (waitc)
| service, ALCS might set this indicator.
| For a description of the error indicators and how to test them, see 9.3.1, “Error indicators in the ECB and
| DECB” on page 152.
|
DECB detached block count (IDECDET (idecdet))
| ALCS stores the number of storage blocks detached from this DECB in this 2-byte field.
| For more details about detaching and attaching storage blocks, see 8.16.4, “Detaching and attaching
| storage blocks” on page 135.
|
DECB data level extension (IDECFX0 (idecfx))
| This 8-byte field corresponds to an ECB data level extension. It is used with the two macros (C functions)
| that process general data sets: GDSNC (gdsnc) and GDSRC (gdsrc).
|
DECB user area (IDECUSR (idecusr))
| The application can store user data in this 8-byte field.
|
8.18.2 Managing DECBs
|
|
|
|
|
|
An application program can reference 16 storage blocks concurrently by using the storage levels of the
ECB. DECBs enable an application to reference more than 16 storage blocks concurrently. An application
program can dynamically acquire a DECB by requesting the DECBC FUNC=CREATE (tpf_decb_create)
service. The number of DECBs that the application is restricted to is limited only by the amount of entry
storage available to the ECB. An application program can release a DECB by requesting the DECBC
FUNC=RELEASE (tpf_decb_release) service.
138
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
| The first time the DECBC FUNC=CREATE (tpf_decb_create) service is requested for an entry, ALCS allocates
| a new overflow storage unit and reserves the first section of that storage unit for use as part of a DECB
| frame. The remaining space in this overflow storage unit is available to satisfy storage block requests.
|
|
|
|
A single DECB frame will contain a header and multiple DECBs. Each DECB is comprised of an
application area that is accessible to application programs and a system area that is accessible only to
ALCS. The application area resides in the overflow storage unit. The frame header and system areas
reside in the trap page preceding the overflow storage unit and are referred to as the DECB descriptor.
| It is possible for an entry to have more than one DECB frame. ALCS will allocate a new overflow storage
| unit for each DECB frame.
| An application program can release a DECB by requesting the DECBC FUNC=RELEASE (tpf_decb_release)
| service. When the final DECB is released by the application, ALCS leaves the DECB frame attached to
| the ECB in preparation for creating the next DECB. ALCS releases the DECB frame when the entry exits.
|
8.18.3 Using symbolic names
|
|
|
|
|
|
|
|
An application program can associate a symbolic name with each DECB. This allows different components
of an application to easily pass information in storage blocks attached to a DECB. Each component only
needs to know the name of the DECB to access it. However ALCS services that support the use of a
DECB (such as FILEC, FINDC, file_record_ext, find_record_ext, and so on) will only accept a DECB
address as a valid reference to a DECB. If an application does not maintain the address of a particular
DECB and, instead, maintains the name of the DECB, the caller must first request the DECBC FUNC=LOCATE
(tpf_decb_locate) service to obtain the address of the DECB. The DECB address can then be passed on
to the subsequent ALCS service call.
| See the ALCS Application Programming Reference – Assembler for more information about the DECBC
| service and the ALCS Application Programming Reference – C Language for more information about the
| tpf_decb_locate function.
|
8.18.4 ALCS services for managing DECBs
| ALCS provides the following assembler macro and C functions for managing DECBs.
| Note: ALCS C/C++ applications that use DECBs must be compiled with the C++ compiler.
|
Assembler macro
C Function
Used to
|
DECBC FUNC=CREATE
tpf_decb_create
Create a DECB.
|
DECBC FUNC=LOCATE
tpf_decb_locate
Locate a DECB.
|
DECBC FUNC=RELEASE
tpf_decb_release
Release a DECB.
|
|
|
|
DECBC FUNC=SWAPBLK
tpf_decb_swapblk
Swap the contents of an ECB storage level and
a DECB storage level. Does not exchange the
contents of the data level and detail error
indicator.
|
DECBC FUNC=VALIDATE
tpf_decb_validate
Validate a DECB.
|
8.18.5 8-byte file address support
| Although an ECB level and a DECB level are alike, there is a difference in the data level. The IDECFA
| (idecfa) field in the DECB, which contains the file address, is 8 bytes in length.
Chapter 8. The entry control block (ECB) and other entry storage
139
Entry control block (ECB) and other entry storage
|
TPF compatibility
|
|
|
The 8-byte file address is required for compatibility with TPF which allows 8-byte file addressing in
either 4x4 format or FARF6 format. In ALCS, if you want to use a DECB, you must use an 8-byte file
address in 4x4 format only.
|
|
|
|
The 4x4 format enables a standard 4-byte file address to be stored in an 8-byte field. In 4x4 format the
low-order 4 bytes of the IDECFA (idecfa) field contain an ALCS band format file address. The high-order
4 bytes of the IDECFA (idecfa) field contain an indicator (a full-word of zeros) that classifies it as a valid
4x4 format file address.
|
|
TPF compatibility
In TPF the high-order 4 bytes of a file address in FARF6 format contain a non-zero value.
| An application may request the FAC8C (tpf_fac8c), GETFC (getfc), GDSNC (gdsnc) or GDSRC (gdsrc) services
| to obtain the 8-byte file address in 4x4 format of the record it wants to read or write.
| An application may also request the FA4X4C (tpf_fa4x4c) service to convert a 4-byte file address to an
| 8-byte file address in 4x4 format, or to convert an 8-byte file address in 4x4 format to a 4-byte file
| address.
| When there is DASD I/O activity the data level must contain an 8-byte file address and may also contain a
| record ID (2 bytes) and record code check (1 byte). One byte is unused.
|
|
8.18.6 Accessing DASD records and using storage blocks with a
DECB
| Application programs can access DASD records and reference storage blocks using a DECB instead of an
| ECB data level. However only a subset of the assembler macros and C functions that reference ECB
| levels accept a DECB address in place of an ECB level.
|
|
|
|
Applications can request the following assembler macros and C functions specifying a DECB address or
an 8-byte file address in place of an ECB level. When these assembler macros and C functions are used,
and they reference the specified file address or the file address in the data level of the specified DECB,
ALCS will first verify that it is a valid 8-byte file address in 4x4 format.
| Note: ALCS C/C++ applications that request any of the following C functions using DECBs must be
| compiled with the C++ compiler.
|
Assembler macro
C Function
Used to
|
|
ATTAC
attac_ext
attac_id
Reattach a storage block after a DETAC
|
CRUSA
crusa
Release a storage block from specified ECB levels or DECB
|
|
DETAC
detac_ext
detac_id
Detach the storage block from a level but do not release it
|
FILEC
File (write) a DASD record
|
FILNC
File (write) a DASD record without detaching the storage block
|
FILSC
File (write) a single copy of a DASD record
|
FILUC
File (write) a held DASD record and unhold the file address
140
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
|
Assembler macro
|
C Function
Used to
file_record_ext
File (write) a DASD record with extended options
|
FINDC
Find (read) a DASD record
|
FINHC
Find (read) a DASD record and hold the file address
|
FINSC
Find (read) a single copy of a DASD record
|
FINWC
Find (read) a DASD record
|
FIWHC
Find (read) a DASD record and hold the file address
|
find_record_ext
Find (read) a DASD record with extended options
|
GDSNC
gdsnc
Open or close a general data set
|
GDSRC
gdsrc
Calculate the file address of a general data set record
|
GETCC
getcc
Get a storage block and attach it to an ECB level or DECB
|
|
GETFC
getfc
getfc_alt
Get a pool file address (dispensed by ALCS) and optionally get
and attach a storage block
|
|
LEVTA
levtest
Test if a storage block is attached to a specified ECB level or
DECB
|
LISTC
|
RCRFC
tpf_rcrfc
Release a pool file record address and storage block
|
RCUNC
rcunc
Release a storage block and unhold a file address
|
RELCC
relcc
Detach a storage block from an ECB level or DECB and release it
|
|
RELFC
relfc
Release a pool file address, and optionally detach and release the
storage block
|
SONIC
sonic
Extract information about a record
|
UNFRC
unfrc_ext
Unhold a held DASD record
Generate a storage list for SNAPC or SERRC
| Notes:
|
|
1. You can request the FAC8C (tpf_fac8c) service to obtain the 8-byte file address in 4x4 format for a
fixed-file record.
|
|
2. You can request the FA4X4C (tpf_fa4x4c) service to convert a 4-byte file address to an 8-byte file
address in 4x4 format, or to convert an 8-byte file address in 4x4 format to a 4-byte file address.
|
8.18.7 Error handling
| Each DECB has a detail error indicator, IDECSUD (idecsud). The gross error indicator CE1SUG (ce1sug)
| in the ECB will include any errors that occur on a DECB-related DASD I/O operation.
| For more information about the error indicator and how to test it, see 9.3.1, “Error indicators in the ECB
| and DECB” on page 152.
|
8.18.8 Accessing a DECB
| Assembler programs access a DECB using the DSECT IDECB.
| The C data structure describing the DECB is defined as type TPF_DECB, and is defined in the header file
| <c$decb.h>.
Chapter 8. The entry control block (ECB) and other entry storage
141
Entry control block (ECB) and other entry storage
|
8.18.9 Functional flow
| The DECB acts as an interface between the application and ALCS, and contains relevant information
| about storage block and DASD I/O requests. The following example shows DECBs being used by a
| sample application.
| When an airline passenger purchases a one-way ticket to Bermuda, the sample application is activated to
| update a database that maintains a list of all passengers with one-way flights.
|
|
|
|
The application consists of 2 programs, PGMA and PGMB. Program PGMA will validate the database
update request and verify that the passenger record does not already exist in the current passenger list.
Once the request has been validated, PGMA will forward the request to program PGMB which will add the
name of the new passenger to the current passenger list.
|
|
|
|
1. PGMA is entered from a reservation application with a copy of the passenger record attached on data
level 0 (D0) of the ECB. After verifying that there is a passenger record attached to D0, PGMA
allocates a DECB which will be used to hold the primary database record for Bermuda. The following
examples show the request to allocate a DECB.
|
|
|
|
IDECB REG=R1
DECBC FUNC=CREATE,
DECB=(R1),
NAME=DECBPRIM
|||
...
| DECBPRIM DC
DATA EVENT CONTROL BLOCK
CREATE PRIMARY DECB
X
X
CL16'BERMUDA.PRI'
| Figure 91. Allocating a DECB – assembler
|
|
TPF_DECB Vdecb;
DECBC_RC rc;
||
|
|
..
.
decb = tpf_decb_create ("BERMUDA.PRI", &rc);
| Figure 92. Allocating a DECB – C++ language
|
|
|
|
|
There were no DECBs previously allocated to this entry, therefore ALCS allocates a new overflow
storage unit to contain the DECB frame.
2. Now that a DECB is available for use, program PGMA attempts to obtain the file address of the
primary record for the Bermuda database. The following examples show a request for the FAC8C
(tpf_fac8c) service to compute the correct file address.
|
|
|
|
|
|
IFAC8
LA
MVC
MVC
MVI
FAC8C
REG=R4
FAC8C PARAMETER BLOCK
R4,EBX
IFACORD,=XL8'15'
ORDINAL
IFACREC,=CL8'#BERMUDA' RECORD TYPE SYMBOL
IFACTYP,IFACFCS
FACS TYPE CALL
PARMS=(R4)
COMPUTE FILE ADDRESS
| Figure 93. Computing an 8-byte file address – assembler
142
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
|
TPF_FAC8 Vfac8_parms;
||
|
|
|
|
|
|
..
.
fac8_parms
= (TPF_FAC8 V)&ecbptr()->ebx;
fac8_parms->ifacord = x15;
fac8_parms->ifactyp = IFAC8FCS;
memcpy (fac8_parms->ifacrec, "#BERMUDA", 8);
tpf_fac8c (fac8_parms);
| Figure 94. Computing an 8-byte file address – C++ language
|
|
|
|
|
|
|
3. PGMA now has the file address for the primary record and issues a FIND request to bring the record
into working storage and obtain a lock on the record for this ECB. The following examples show a
request for a FIND-type service.
MVC
MVC
XC
FIWHC
IDECFA,IFACADR
FILE ADDRESS
IDECRID,=CL2'AB'
RECORD ID
IDECRCC,IDECRCC
RCC
DECB=(R1),ERROR=ERROR_BRANCH
READ RECORD
| Figure 95. Requesting a FIND-type service using a DECB – assembler
|
|
|
decb->idecfa = fac8_parms->ifacadr;
find_record_ext (decb, NULL, "AB", '\',
HOLD_WAIT, FIND_DEFEXT);
| Figure 96. Requesting a FIND-type service using a DECB – C++ language
|
|
4. When the FIND request ends either successfully or unsuccessfully, ALCS updates the DECB
accordingly. For a successful call, ALCS attaches a storage block at the DECB storage level.
|
|
|
|
|
5. Now that the primary record has been read from the database, PGMA enters program PGMB to
complete the processing. PGMB searches the primary record for an available entry slot to which the
new passenger record can be added. If there are no available entries in the primary record, an
overflow record is obtained. To obtain the overflow record a new DECB must be created. The
following examples show a request to create a new DECB.
|
|
|
DECBC FUNC=CREATE,
DECB=(R2),
NAME=DECBOFLW
||
..
|
.
| DECBPRIM DC
| DECBOFLW DC
CREATE OVERFLOW DECB
X
X
CL16'BERMUDA.PRI'
CL16'BERMUDA.OVR'
| Figure 97. Creating a new DECB – assembler
|
|
TPF_DECB Vprime, Voverflow;
DECBC_RC rc;
||
|
|
..
.
overflow = tpf_decb_create ("BERMUDA.OVR", &rc);
| Figure 98. Creating a new DECB – C++ language
|
|
|
|
ALCS allocates the first available DECB in the DECB frame to the entry. There are now two DECBs in
the single DECB frame, which are marked as in use by the ECB.
6. Program PGMB must obtain a pool-file record to use as the new overflow record in the database.
PGMB must locate the DECB created by PGMA (which contains the primary record) so that the
Chapter 8. The entry control block (ECB) and other entry storage
143
Entry control block (ECB) and other entry storage
|
|
pool-file record can be chained to it. The following examples show the requests to obtain a pool-file
record address and locate the DECB containing the primary record.
|
|
|
|
|
|
GETFC DECB=(R2),
ID=C'AB',
BLOCK=YES
DECBC FUNC=LOCATE,
DECB=(R3),
NAME=DECBPRIM
||
..
|
.
| DECBPRIM DC
| DECBOFLW DC
GET POOL-FILE ADDRESS
X
X
LOCATE PRIMARY DECB
X
X
CL16'BERMUDA.PRI'
CL16'BERMUDA.OVR'
| Figure 99. Locating a DECB – assembler
|
TPF_FA8 pool_addr;
||
|
|
|
|
..
.
pool_addr = getfc (overflow, GETFC_TYPE, "AB",
GETFC_BLOCK, GETFC_SERRC);
prime = tpf_decb_locate ("BERMUDA.PRI", &rc);
| Figure 100. Locating a DECB – C++ language
|
|
The GETFC (getfc) request specifies that a storage block is required. ALCS attaches the storage
block at the DECB storage level for the overflow record.
|
|
|
|
|
7. Program PGMB must now copy the relevant information from the passenger record of the new
passenger, which is attached on ECB data level 0 (D0), to an available entry in the overflow record
attached to the DECB. After copying the data a FILE request must be issued to update the database
with the details of the new passenger. The following examples show the request for the FILE-type
service.
|
FILEC DECB=(R2)
WRITE RECORD
| Figure 101. Requesting a FILE-type service using a DECB – assembler
|
|
file_record_ext (overflow, NULL, "AB", '\',
NOHOLD, FILE_DEFEXT);
| Figure 102. Requesting a FILE-type service using a DECB – C++ language
|
|
|
8. Now that the overflow record is no longer being referenced by the ECB, program PGMB may choose
to release the DECB that was allocated to contain the record. The following examples show a request
to release the DECB.
|
|
DECBC FUNC=RELEASE,
DECB=(R2)
RELEASE DECB
X
| Figure 103. Releasing a DECB – assembler
|
tpf_decb_release (overflow);
| Figure 104. Releasing a DECB – C++ language
|
|
|
|
9. Program PGMB can now update the primary record with the file address of the overflow record to
chain them together. After performing this update, PGMB can now issue a FILE request to update the
primary record in the database and release the lock, which program PGMA had previously obtained on
the record. The following examples show the request for the FILE-type service.
144
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Entry control block (ECB) and other entry storage
|
FILUC DECB=(R3)
WRITE AND UNHOLD RECORD
| Figure 105. Requesting a FILE-type service using a DECB – assembler
|
|
file_record_ext (prime, NULL, "AB", '\',
UNHOLD, FILE_DEFEXT);
| Figure 106. Requesting a FILE-type service using a DECB – C++ language
| 10. Program PGMB may now choose to release the final DECB before it exits. If it does not, ALCS
|
releases the DECB frame when the entry exits.
Chapter 8. The entry control block (ECB) and other entry storage
145
Error conditions and error processing
Chapter 9. Error conditions and error processing
This chapter describes error conditions that ALCS and application programs might detect. It explains how
application programs can take action to avoid such errors from occurring and how they can deal with them
when they do.
It also describes the ALCS wait mechanism and how application programs can use it to detect single and
multiple errors on I/O operations.
9.1 Error conditions
Error conditions, described next, can be grouped as follows:
5 Error conditions that ALCS detects immediately
5 Error conditions that ALCS detects later
5 Error conditions that application programs detect.
9.1.1 Error conditions that ALCS detects immediately
When ALCS detects an error condition, it takes a dump of the relevant parts of storage. Depending on
the severity of the error, it terminates one or more entries. These errors include:
Application loop timeouts
ALCS terminates any entry which continues for too long without losing control. (See 9.2, “The ALCS
wait mechanism and error processing” on page 148.) It continues to process other entries normally.
Program check in an application program
ALCS terminates the entry.
Invalid assembler macro (or C function) parameters
ALCS terminates the entry.
Corruption of an ECB control area
ALCS terminates the entry.
I/O hardware errors
ALCS automatically retries any I/O operation that fails because of an I/O hardware error. If the error
persists, ALCS takes a dump, but continues processing the entry.
When a hardware error occurs during the processing of a requested I/O service, ALCS indicates this
error on return from the service (see 9.2, “The ALCS wait mechanism and error processing” on
page 148) and sets the ECB error indicators. Application programs must deal with this condition.
Deadlock
Deadlock can (potentially) suspend the processing of two or more entries indefinitely. It results, for
example, from the following sequence of events:
1.
2.
3.
4.
146
Entry
Entry
Entry
Entry
1
2
1
2
holds file address A.
holds file address B.
tries to hold file address B (which is currently held by entry 1).
tries to hold file address A (which is currently held by entry 2).
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Error conditions and error processing
Deadlock can be caused by application programs using any of the following (there are also more
subtle forms of deadlock than these):
5 Record hold facility (two entries each trying to hold the same two file addresses)
5 Resource hold facility (two entries trying to hold the same two resources)
5 The TASNC (tasnc) service (two entries trying to assign the same two sequential files or tapes).
To avoid deadlock, try to ensure that entries only hold one file address, resource, and so on, at a time.
If this is impossible, ensure that all entries request holds of file addresses, resources, or assign the
sequential files or tapes, in the same order.
If deadlock occurs, ALCS terminates one of the entries which caused the deadlock.
Other errors
ALCS detects corrupted data in some system-critical records and some control blocks. In addition, it
also detects storage blocks not attached to ECBs. In such cases, ALCS generally takes a diagnostic
dump.
9.1.2 Error conditions that ALCS detects later
Some application programming errors can result in error conditions that remain undetected for a long time.
They include the following:
Lost record updates
Updating a record that is not held can cause updates to that record to be lost.
Lost pool-file addresses
Pool-file addresses that are not released when they are no longer required are lost to the system.
Although pool management eventually recovers these “lost” pool addresses, you should request the
RELFC (relfc) service to release a pool-file address.
Transactions which create multiple entries
Some transactions use ALCS create services to create multiple entries that process a single
transaction. Incautious use of ALCS create services can “overload” ALCS. See 3.7, “Transactions
that create multiple entries” on page 50.
9.1.3 Error conditions that application programs detect
Application programs can detect error conditions. When this happens, the application program itself must
carry out (or at least initiate) the error processing. See 9.3, “Dealing with errors” on page 152.
Application programs can detect the following types of error:
Input data errors
These are errors in the format or parameters of an input message.
Wait completion errors
These are errors which cause a WAITC (waitc function), or a macro (function) that contains an implied
wait to return an error condition. See 9.3, “Dealing with errors” on page 152 for details of how to test
for these errors.
Logic errors
These are errors caused by incorrect entry conditions for a particular program, or by fields in a
retrieved record which have been incorrectly set up by application programs.
Chapter 9. Error conditions and error processing
147
Error conditions and error processing
9.2 The ALCS wait mechanism and error processing
This section describes the ALCS wait mechanism and the associated error testing. Application programs
use the ALCS wait mechanism when reading records from from, and writing records to, the real-time
database and sequential files.
For most DASD or sequential file write operations, the application program does not need to know when
the write has completed. ALAS I/O services that perform write operations do not allow the application
program to check that the operation has completed successfully.
An exception to this is the FILNC (filnc) service. See 9.2.2, “I/O services that require an implied wait”.
When an application requests a DASD or sequential file read service, it must check that the read has
completed successfully before it tries to use the data. There are two types of read service; those that
contain an implied wait, and those that do not.
9.2.1 I/O services that include an implied wait
Some read services contain an implied wait. When an application calls one of these services, ALCS
suspends the entry until the read is complete, or until it has detected an error.
These services are called implied-wait services.
For example, the FINWC (finwc) service requests ALCS to find a record and waits for I/O to complete (see
Figure 107).
│
D
┌───────────────┐
│ FINWC (finwc) │
└───────────────┘
...........................
(Read with implied wait)
(ALCS suspends the entry
until the read is complete)
Figure 107. Read using an implied-wait service
In assembler programs, when an error occurs in the read, ALCS branches to the error label specified with
the ERROR= parameter of the macro. This label must be the start of an error routine (see 9.3, “Dealing
with errors” on page 152).
Successful implied-wait C functions return a pointer to the record. When an error occurs, the C function
returns a value of NULL. The application program must test the return value of the function and deal with
errors as described in 9.3, “Dealing with errors” on page 152.
You can use an implied-wait read service when the application does not need to do any processing while
the read is taking place.
9.2.2 I/O services that require an implied wait
Other read services do not contain an implied wait. An application can request one of these services and
continue processing while the read is taking place. However, it must follow it with an implied-wait service
at some stage before it can access the record.
The FILNC (filnc) write service also behaves in this way. You must follow it with an implied-wait service.
148
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Error conditions and error processing
In this book these read services and the write service FILNC (filnc) are referred to as required-wait
services.
The simplest implied-wait service you can use is the WAITC (waitc) service. This causes ALCS to suspend
the entry until either the read is complete or ALCS has detected an error (see Figure 108).
│
D
┌───────────────┐
│ FINDC (findc) │
└───────────────┘
D
(other processing)
D
┌───────────────┐
│ WAITC (waitc) │
└───────────────┘
...........................
(Or other required-wait service)
(ALCS suspends the entry
until the read is complete)
Figure 108. Wait after a required-wait read service
If no error occurs, ALCS restarts the entry at the next instruction after the WAITC (waitc) service. The
storage level contains the record that has been read.
The WAITC contains a label to which ALCS branches when it detects an error. This label must be the start
of an error routine which must deal with the errors as described in 9.3, “Dealing with errors” on page 152.
The waitc function returns a nonzero value when it detects an error. The application program must test
the return value of waitc and deal with errors as described in 9.3, “Dealing with errors” on page 152.
9.2.3 Multiple required-wait services
An application can request several required-wait services before it requests an implied wait. It requests
the implied wait by requesting a WAITC (waitc) service or by requesting another implied-wait service.
Figure 109 shows an example with a terminating FINWC (finwc) service that contains an implied wait.
Note: The three reads must all be on different data levels (for example, L4, L5, L7).
│
D
┌───────────────┐
│ FINDC (findc) │
└───────────────┘
D
┌───────────────┐
│ FINDC (findc) │
└───────────────┘
D
┌───────────────┐
│ FINWC (finwc) │
└───────────────┘
...........................
(Read 1)
(Read 2)
(Read 3 containing an implied wait)
(ALCS suspends the entry
until all reads are complete)
Figure 109. Multiple reads followed by an implied-wait read
To deal with this situation, ALCS uses an I/O counter. ALCS increments this counter by 1 every time the
application requests a read service. Each time a read completes, ALCS reduces the I/O counter by 1.
When the I/O counter reaches zero ALCS restarts the suspended entry.
Chapter 9. Error conditions and error processing
149
Error conditions and error processing
In assembler programs, if an error has occurred in any of the reads, ALCS branches to the ERROR= label
of the FINWC macro. This label must be the start of an error routine (see 9.3, “Dealing with errors” on
page 152).
In C language programs, if an error has occurred in any of the reads, the finwc function returns a NULL
value. The application program must test the return value of finwc and deal with errors as described in
9.3, “Dealing with errors” on page 152.
9.2.4 Loss of control
Use of any of the read services can cause the entry to lose control. However, if the application program
calls a WAITC (waitc) service when the I/O counter is already zero, the entry does not lose control. So a
wait can, but does not necessarily, cause the entry to lose control.
9.2.5 Summary of ALCS I/O services
All read services either require a subsequent WAITC (waitc) service or are themselves implied-wait
services. The FILNC (filnc) service also requires a subsequent implied-wait service, other write services
do not require an implied wait.
Each I/O service description in ALCS Application Programming Reference – Assembler (and function
description in ALCS Application Programming Reference – C Language) explains if the service is a
required wait, an implied wait, or neither. This information is summarized in Figure 110.
|
|
No wait
────────────
Required wait
──────────────
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FILEC
FINDC
FILUC
filec
filec_ext
filuc
filuc_ext
FINHC
FILNC
(all others
not listed
here)
TDTAC
TPRDC
Implied wait
─────────────
findc
WAITC
findc_ext
FINWC
finhc
finhc_ext
FIWHC
filnc
filnc_ext
file_record
(with NOREL)
file_record_ext
(with NOREL)
find_record_ext
(with NOHOLD_NOWAIT
or
HOLD_NOWAIT)
waitc
finwc
finwc_ext
fiwhc
fiwhc_ext
find_record
find_record_ext
(with NOHOLD
or
HOLD
or
NOHOLD_WAIT
or
HOLD_WAIT)
tape_read
tprdc
Figure 110. Summary of ALCS I/O services
Figure 111 summarizes how ALCS reports I/O errors with the various ALCS services.
Figure 111 (Page 1 of 2). Reporting of I/O errors with ALCS service
|
|
Assembler
service
C function
Wait
service
required?
Result of error
(assembler)
Result of error (C
language programs)
FILEC
filec
filec_ext
No
Not available
Not available
file_record
file_record_ext
without NOREL
parameter
No
|
|
|
|
150
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Not available
Error conditions and error processing
Figure 111 (Page 2 of 2). Reporting of I/O errors with ALCS service
Assembler
service
|
|
|
|
C function
Wait
service
required?
file_record
file_record_ext
with NOREL
parameter
Yes
Result of error
(assembler)
Result of error (C
language programs)
Return value of waitc is
nonzero (see note 2)
|
|
FILNC
filnc
filnc_ext
Yes
WAITC error branch taken
(see note 1)
Return value of waitc is
nonzero (see note 2)
|
|
FILUC
filuc
filuc_ext
No
Not available
Not available
|
|
FINDC
findc
findc_ext
Yes
WAITC error branch taken
(see note 1)
Return value of waitc is
nonzero (see note 2)
|
|
find_record
Implied
Return value of
find_record is NULL
|
|
|
|
|
|
find_record_ext
with NOHOLD
or HOLD
or NOHOLD_WAIT
or HOLD_WAIT
parameter
Implied
Return value of
find_record_ext is
NULL
|
|
|
|
find_record_ext
with NOHOLD_NOWAIT
or HOLD_NOWAIT
parameter
Yes
Return value of waitc is
nonzero (see note 2)
|
|
FINHC
finhc
finhc_ext
Yes
WAITC error branch taken
(see note 1)
Return value of waitc is
nonzero (see note 2)
|
|
FINWC
finwc
finwc_ext
Implied
FINWC error branch taken
Return value of finwc or
finwc_ext is NULL
|
|
FIWHC
fiwhc
fiwhc_ext
Implied
FIWHC error branch taken
Return value of fiwhc or
fiwhc_ext is NULL
Yes
WAITC error branch taken
(see note 1)
Not available
tprdc
Yes
WAITC error branch taken
(see note 1)
Return value of waitc is
nonzero (see note 2)
tape_read
Implied
All others
No
TDTAC
TPRDC
All others
Return value of
tape_read is NULL
Not available
Not available
Notes:
1. If this service is followed by a implied-wait macro or WAITC, ALCS branches to the label specified in the
ERROR= parameter of the implied-wait service.
2. If this function is followed by a implied-wait function other than waitc, the return value of this
implied-wait service is NULL.
Chapter 9. Error conditions and error processing
151
Error conditions and error processing
9.3 Dealing with errors
ALCS indicates to an application when an error has occurred by branching to an error label (assembler
programs) or setting a nonzero value of waitc function or a NULL value of an implied-wait function (C
language programs).
The application has to determine what the error was and on what data level it occurred. The error
| indicators in the ECB and DECB allow applications to do this.
|
9.3.1 Error indicators in the ECB and DECB
The ECB contains 16 1-byte (unsigned char) error indicators, one for each data level. They are called
EBCSDn (ebcsdn) where n is the data level (0 through hexadecimal F). This 16-byte area is also called
CE1SUD. In addition, there is a 1-byte indicator CE1SUG. See Figure 112.
Detail error indicators
───────────────────────
EBCSD (ebcsd)
│
EBCSD1 (ebcsd1)
│
│
EBCSD2 (ebcsd2)
│
│
│
EBCSDF (ebcsdf)
D
D
D
D
┌───────┬───────┬───────┬───── ─ ─ ─ ──┬───────┐
│
│
│
│
│
│
└───────┴───────┴───────┴───── ─ ─ ─ ──┴───────┘
i
│
CE1SUD (ce1sud)
Gross error indicators
──────────────────────
┌───────┐
│
│
└───────┘
i
│
CE1SUG (ce1sug)
Figure 112. Error indicators in the ECB
| A DECB contains a single 1-byte (unsigned char) error indicator, called IDECSUD (idecsud).
When an application requests an implied-wait service, ALCS sets one or more of these indicators, as
follows:
EBCSDn (ebcsdn)
Each 1-byte (char) field contains bit indicators that ALCS sets when it discovers an error in processing an
| I/O request that specifies this particular ECB level (n).
The contents of EBCSDn (ebcsdn) are called the “detail error indicators”.
ALCS indicates error conditions in the EBCDn (ebcsdn) field in the ECB. The possible errors are defined
by the symbols shown in Figure 113.
152
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Error conditions and error processing
Figure 113. Symbols for error conditions
Symbol
Condition detected by ALCS
CXSGHE
I/O hardware error
CXSGAE
Incorrect file address specified (DASD only)
CXSGIE
Record identifier mismatch (DASD only)
CXSGRE
Record code check mismatch (DASD only)
CXSGSE
Incorrect size (small) record read (sequential file only)
CXSGLE
Incorrect size (large) record read (sequential file only)
CXSGEE
End-of-file detected (sequential file only)
CXSGEE
Record not allocated (fixed file only)
CE1SUD (ce1sud)
This 16-byte array gives you an alternative way of accessing the error indicators.
In C language programs, ebcsdn is a #defined name for ce1sud[n].
|
IDECSUD (idecsud)
|
|
|
|
This 1-byte (unsigned char) field contains bit indicators that ALCS sets when it discovers an error in
processing an I/O request that specifies a DECB. This field is equivalent to the "detail error indicator",
EBCSDn (ebcsdn), in the ECB. The possible errors are defined by the symbols shown in Figure 113 on
page 152.
CE1SUG (ce1sug)
ALCS sets this 1-byte (unsigned char) field to contain the result of a bitwise inclusive OR operation on all
| the 16 detail error indicators (EBCSDn (ebcsdn)) in the ECB and the detail error indicator (IDECSUD
| (idecsud)) in every DECB allocated to the ECB. If any of the detail error indicators have bits set this field
has corresponding bits set.
| The contents of CE1SUG (ce1sug) are called the “gross error indicators”. In C language programs, the
return value of the waitc function is the value of ce1sug. It is nonzero if an error has occurred.
9.3.2 Testing for errors
| When a program has detected an error, it must test the ECB error indicators in EBCSDn (ebcsdn) or the
| DECB error indicator in IDECSUD (idecsud) to identify the cause.
Read two DASD records and test for errors in assembler programs
In the example shown in Figure 114 on page 154, an assembler application program uses FINDC to read
two DASD records. They are fixed-file records with type #XMPRI. The application program reads record
ordinal 5 on level 3 (D3) and record ordinal 6 on level 4 (D4).
Before issuing each FINDC, it uses FACE to calculate the file address of the record. After issuing both
FINDCs, the application program issues WAITC to wait for I/O completion and test for I/O errors:
Chapter 9. Error conditions and error processing
153
Error conditions and error processing
LA
LA
LA
ENTRC
R,5
R6,#XMPRI
R7,CE1FA3
FACE
LOAD ORDINAL NUMBER
LOAD RECORD TYPE
ADDRESS DATA LEVEL
AND CALCULATE FILE ADDRESS
LTR
BZ
R,R
...
FILE ADDRESS OK
BRANCH IF NOT
MVC
EBCID3(3),...
FINDC D3
SET UP EXPECTED RECORD ID AND RCC
FIND THE RECORD ON D3
L
LA
LA
ENTRC
R,6
R6,#XMPRI
R7,CE1FA4
FACE
LOAD ORDINAL NUMBER
LOAD RECORD TYPE
ADDRESS DATA LEVEL
AND CALCULATE FILE ADDRESS
LTR
BZ
R,R
...
FILE ADDRESS OK
BRANCH IF NOT
Figure 114 (Part 1 of 2). Read two DASD records and test for errors – assembler
..
.
ERRRTN
MVC
EBCID4(3),...
FINDC D4
SET UP EXPECTED RECORD ID AND RCC
FIND THE RECORD ON D4
WAITC ERRRTN
WAIT FOR I/O ON D3 AND D4
EQU
TM
BO
V
EBCSD3,CXSGIE
...
ID ERROR ON D3
BRANCH IF YES
TM
BO
EBCSD4,CXSGIE
...
ID ERROR ON D4
BRANCH IF YES
Figure 114 (Part 2 of 2). Read two DASD records and test for errors – assembler
Read two DASD records and test for errors in C language programs
In the example shown in Figure 115 on page 155, a C language program reads two DASD records and
tests for errors. (The example assumes that the program has already set up the file addresses, record
IDs, and optionally RCC, on data levels D0 and D1).
154
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Error conditions and error processing
struct my_rec Vrec_ptr;
/V define pointer for record structure V/
findc(D);
..
.
if ( (rec_ptr = finwc(D1)) == NULL )
{
/V error detected in implied wait V/
if (ecbptr()->ebcsd)
{
/V error on level V/
..
.
}
if (ecbptr()->ebcsd1)
{
/V error on level 1 V/
..
.
}
}
else
{
/V records read on level and 1 are without error V/
}
Figure 115. Read two DASD records and test for errors – C language
9.3.3 Multiple errors
An application might contain several implied-wait service requests interspersed with required-wait service
requests. See Figure 116.
│
D
┌───────────────┐
│ FINDC (findc) │
└───────────────┘
D
┌───────────────┐
│ FINWC (finwc) │
└───────────────┘
...........................
:
D
(error processing)
│
D
┌───────────────┐
│ FINDC (findc) │
└───────────────┘
D
┌───────────────┐
│ FINWC (finwc) │
└───────────────┘
...........................
(Read 1)
(Read 2 containing an implied wait)
(ALCS suspends the entry
until all reads are complete)
(Read 3)
(Read 4 containing an implied wait)
(ALCS suspends the entry
until all reads are complete)
Figure 116. Multiple implied-wait services
If the first implied-wait service returns an error value, ALCS’s setting of the error indicators depends on
whether or not the second wait service detects a new error.
1. If the second implied-wait service does not detect a new error, it does not return an error value. ALCS
does not clear the old error indicators. (In the example, Figure 116, errors would refer to Read 1 or
Read 2.)
2. If the new implied-wait service detects a new error, it does return an error value. ALCS clears any
error indicators from the first implied-wait service. The error indicator settings all refer to the second
wait service. (In the example, Figure 116, errors would refer to Read 3 or Read 4.)
Chapter 9. Error conditions and error processing
155
Error conditions and error processing
In the C language program example shown in Figure 117 on page 156, if the first finwc returns an error
value, the error routine checks the type of error by testing ebcsd1. If the second finwc also returns an
error, a second error routine checks the type of error by testing ebcsd1.
struct my_rec Vrec_ptr;
/V define pointer for record structure V/
if ( (rec_ptr = finwc(D1)) == NULL )
{
/V first error routine V/
if (ecbptr()->ebcsd & CXSGAE)
{
/V invalid file address V/
..
.
}
..
.
if ( (rec_ptr = finwc(D1)) == NULL )
{
/V second error routine V/
if (ecbptr()->ebcsd & CXSGAE)
{
/V invalid file address V/
..
.
}
}
else
{
/V no error on second finwc()
/V ecbptr()->ebcsd still contains error code for first finwc() V/
..
.
}
}
Figure 117. Processing multiple I/O errors – C language
9.4 Sequential file errors
In processing sequential files, some of the conditions that ALCS detects might not be errors. Examples
are: incorrect size (small) block, and end-of-file. The application must take appropriate action, as shown in
the following examples.
You can test the return condition using the symbols shown in Figure 113 on page 152. For example, to
test for end-of-file, in a C language program, you could use the code shown in Figure 118.
topnc("VPH",INPUT,NOBUFF);
/V open VPH tape for input
tprdc("VPH",D4,L2);
/V read a record from VPH
if (waitc())
{
/V error occurred V/
if (ecbptr()->ebcsd4 & CXSGEE)
{
puts("end-of-file on VPH tape");
exit();
}
}
/V process the record V/
V/
V/
Figure 118. Test for sequential file errors – C language
156
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Error conditions and error processing
9.4.1 Testing for several conditions
You can test for one of several conditions at the same time, for example:
Testing for several conditions in assembler programs
The assembler code example shown Figure 119 reads a record from the general sequential file HOT into
a size L2 storage block. The example tests for and accepts records that are smaller than the L2 block.
..
.
TOPNC NAME=HOT,STATUS=I
OPEN THE FILE FOR INPUT
TPRDC NAME=HOT,LEVEL=DD,BLOCK=L2 READ A BLOCK
WAITC ERRRTN
AND WAIT FOR I/O
SHORT
..
.
EOF
..
.
ERRRTN
..
.
EQU
L
LH
V
R2,CE1CRD
R3,CE1CCD
LOAD RECORD ADDRESS
LOAD RECORD LENGTH
EQU
V
TCLSC HOT
CLOSE THE FILE
EQU
TM
BO
V
EBCSDD,CXSGSE
SHORT
SHORT RECORD
BRANCH IF YES - ACCEPT IT
TM
BO
EBCSDD,CXSGEE
EOF
END-OF-FILE
BRANCH IF YES - CLOSE THE FILE
Figure 119. Test for several sequential file errors – assembler program
Testing for several conditions in C language programs
A similar C language code example is shown in Figure 120 on page 158.
Chapter 9. Error conditions and error processing
157
Error conditions and error processing
/V define macro for ECB level 4 error indicator V/
#define EBCSD4 (ecbptr()->ebcsd4)
topnc("VPH",INPUT,NOBUFF);
/V open VPH tape for input V/
tprdc("VPH",D4,L2);
/V read a record from VPH
V/
if (waitc())
{
switch (EBCSD4)
{
case :
/V no error V/
break;
/V continue processing record V/
case CXSGHE:
puts("hardware error on reading VPH tape");
exit();
case CXSGEE:
puts("end-of-file on VPH tape");
exit();
case CXSGLE:
puts("record too large");
exit();
case CXSGSE:
puts("record too small");
break;
/V continue processing record V/
default:
printf("unexpected error %#2X on reading VPH\n",EBCSD4);
exit();
}
}
/V process the record V/
Figure 120. Test for several sequential file errors – C language
9.4.2 Recovery from wait-completion errors
The method of recovery depends on the type of error:
I/O hardware errors
Normally, an application program must terminate with a suitable message when an I/O hardware error
occurs. However, when the program is writing a pool record for the first time, the error routine can
itself attempt the recovery (see 9.6, “Error recovery” on page 159).
End-of-file when reading a sequential file
This might not indicate an error condition. It might just indicate that the program has reached the end
of the data. However, some sequential files might have a specific end-of-data record (for example, a
record containing '9999...'). If the program receives an end-of-file indication with such a file before it
has read the end-of-data record, then this is an error that the application must deal with.
Short records
When ALCS reads a short-length record from a sequential file, it puts the data into the storage block,
as normal. It also stores the record length in the associated storage level (see 8.4.2, “ECB storage
levels” on page 128). The application can then process the short record that is available.
Errors from find and hold services
When ALCS returns an error value from a FINHC (finhc) or FIWHC (fiwhc) service, the file address
might or might not be held. (This depends on what point in the processing the error occurred.) The
application program must determine whether or not the file address is held, because if it is held the
application program must unhold it.
|
|
The program can determine if the file address is held by testing whether the ECB or DECB storage
level specified in the macro or C function call is occupied. It does this by calling the LEVTA macro
158
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Error conditions and error processing
|
|
(levtest) service specifying the corresponding storage level or DECB address. If the storage level in
the ECB of DECB is occupied, then the error occurred after the file address was held and the
application program must unhold it.
9.5 Application program logic errors
Application programs can detect two types of logic errors:
5 Incorrect entry conditions
5 Database corruption.
Application programs should deal with them as follows:
9.5.1 Checking for logic errors
It is not practical for an application program to check every entry condition and every field in a referenced
record. However, you might like to consider the following points:
5 Where you can perform a check using a few extra statements, include them in the program.
5 Before converting data from one type or format to another, check the data.
5 Before performing calculations, check the values used in the calculation.
5 Check values used as counters in loops.
5 Check values which serve as indexes to tables against an appropriate maximum.
5 Functions that many programs call should check all entry conditions. The entry conditions should be
as simple as possible.
9.5.2 Recovery from logic errors
When an application program detects an application program logic error, it should do the following:
5 Identify all the errors that have occurred.
5 Call an error processing program, or request the ENTDC (entrc) service to transfer control to an error
processing program. The called program constructs an appropriate error response message, or
attempts an error recovery procedure, or both (see 9.6, “Error recovery”).
The error processing program sets a code in the ECB, for example, in EBER01 (eber1). This code
indicates the nature of the error or errors.
5 When the error-testing program returns to the calling program (using BACKC or return) the calling
program tests the error switches and takes appropriate action (for example, sends a message to the
originating terminal).
9.6 Error recovery
An application program can recover from an error situation by doing one or more of the following:
5 Requesting operator intervention
5 Retrying the process
5 Using a duplicate copy of the data
5 Falling back to an earlier version of the data
Chapter 9. Error conditions and error processing
159
Error conditions and error processing
5 Purging corrupted data that is of low importance
5 Attempting to reconstruct the data.
Each of these has advantages and disadvantages as described below.
Request operator intervention
The safest technique for error recovery is generally to inform the operator of the error, using a dump
or a message to RO CRAS, or both. The operator can then perform the necessary error recovery
procedures. To minimize the risk of operator error, supply as much relevant information as possible,
and subsequently check any corrective action taken by the operator.
Retry the process
When ALCS detects an I/O hardware error, it retries the I/O channel programs extensively before
returning to the calling program and indicating an error in the implied-wait service. For this reason,
application programs should not reissue an I/O macro (C function) call when ALCS indicates a
hardware error.
However, there is one occasion when application programs can do this. If ALCS indicates a hardware
error when the program is writing a record to a newly dispensed pool-file address, the application
program can issue a GETFC (getfc) service to obtain a second pool file address. The application
program can then write the record to this second address.
Note: The application program should not release the unused pool file address. If the unused
pool-file address is released, ALCS will dispense it again, and the hardware error will recur.
Use duplicated information
If an application program identifies invalid data in a record field, it might be able to get the valid data
from other fields in the record, or from other records. (This assumes some duplication of data in
records.)
Note: If your installation uses duplicated databases, ALCS maintains exact duplicates of all DASD
records in the duplicate databases. Application programs cannot directly access these duplicate
records. The duplicates are maintained only for protection against hardware errors. ALCS handling of
a duplicate database is transparent to application programs.
Fallback to a previous version
Critical data should be backed up regularly. If an application program finds that the current version of
the data on DASD is in error, it might be possible for it to use the last saved version instead.
However, this method of error recovery (known as fallback) is not generally used in application
programs.
Purge corrupt data
If an application program discovers errors in unimportant data, it might be able to delete that data and
all references to it. This process is known as purging. Purging should be used with caution, since it
is rarely possible to determine the consequences of deleting a data item. If you decide to purge data,
ensure that details of purged data are preserved for subsequent inspection.
Attempt to reconstruct the data
An application program might be able to compute a “most probable” value for a field containing an
incorrect value. However, it is difficult to predict the consequences if the data item should be
reconstructed incorrectly. Use this method of error recovery with caution.
9.6.1 Designing error recovery routines
When designing error recovery routines for an application, consider the following points:
160
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Response time
Input messages to ALCS applications typically require a fast response. Extensive error recovery can
take a long time and delay the response. If an application program detects a need for error recovery
while processing an input message, it can create a new entry to perform the error recovery. The
original entry can then construct and transmit a suitable error message without delay.
Compounding the error
Some error recovery techniques used by application programs can introduce new errors, which might
be more severe than the original error.
Concealing the cause of the error
Automatic activation of error recovery procedures can conceal the cause and even the occurrence of
an error. Because of this, you must ensure that information about errors and their recovery is kept for
inspection. You can do this using dumps, or messages to RO CRAS, or both.
Chapter 9. Error conditions and error processing
161
Trace facility
Chapter 10. Using the ALCS trace facility
ALCS provides a trace facility to help application programmers debug their programs. You can run the
ALCS trace facility either on a dedicated test system or on a production system. Use it with care on a
production system, because it degrades performance.
Application programs use monitor-request macros to request services from the ALCS online monitor.
The ALCS trace facility monitors the execution of these macros and interrupts processing at a specified
place to log selected data. See ALCS Application Programming Reference – Assembler for a full
description of all ALCS macros, and their group names.
You can trace all monitor-request macros, or you can specify trace control options to restrict tracing to:
5
5
5
5
Selected
Selected
Selected
Selected
entries
application programs
monitor-request macros
DASD records
You can use the ALCS trace facility to initiate source level debugging of C/C++ programs on a remote
workstation. This facility is called “workstation trace”.
10.1 Destinations
You can direct the trace output to the:
5 System macro trace block.
5 ALCS diagnostic file.
5 Terminal (this is called conversational tracing).
The three destinations provide different levels of tracing, as described next.
10.1.1 The system macro trace block
When operating normally, ALCS records information about each monitor-request macro call in the entry
macro trace block. This information relates to a specific entry. When a system error occurs, the system
error dump includes the contents of the entry macro trace block. This tells you about the monitor-request
macros issued by the entry before the system error.
If you start tracing to the system macro trace block, the contents of this block are also included in any
system error dump. The system macro trace block includes information about monitor-request macros
issued by all entries in the system.
A dump can occur when two or more entries fail to work cooperatively. You may need a single trace
block showing the macros issued by all the entries. This shows the relative sequence of actions for the
entries.
The maximum number of monitor-request macros that can be recorded in the system macro trace block is
specified by the system programmer during ALCS system generation.
You can examine the contents of the system macro trace block from your terminal (see 10.2, “Tracing to
the system macro trace block” on page 164).
162
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Trace facility
10.1.2 The ALCS diagnostic file
You can obtain more detailed information if you start tracing to the ALCS diagnostic file. When you use
this type of trace, you can specify what information is to be recorded and what is not.
After tracing, you can run the ALCS diagnostic file processor which produces a report containing the
following information:
5 Start-of-trace and end-of-trace identifier
This is a single line showing where the trace starts and stops.
5 Macro information
The report contains a line for each monitor-request macro showing:
– Address register of the ECB.
– Program name, or question marks (?) when the online monitor issued the monitor-request macro.
– Listing address of the monitor-request macro in the program, or question marks (?) when the
monitor-request macro is not in the application program.
– Name of the monitor-request macro.
– Operands of the monitor-request macro (in hexadecimal).
– CRI of the terminal that created the entry. For WTTY lines, the line number is the low-order byte
of the CRI.
5 Registers
The contents of the general and floating point registers as they are immediately before the
monitor-request macro executes (if requested).
5 Entry control block and attached storage blocks
The ALCS diagnostic file processor prints this data in the same format as a system error dump. The
selection of the data depends on the options you specify when starting the trace.
10.1.3 Conversational tracing
Conversational tracing provides you with the most flexibility in selecting and displaying information. See
10.7, “Conversational tracing” on page 171.
Chapter 10. Using the ALCS trace facility
163
ZTRAC
10.2 Tracing to the system macro trace block
You can control block tracing — from a Prime CRAS authorized terminal. However the Display
parameter can be used from any CRAS terminal.
The format of the command is:
;;──ZTRAC──Block,──┬─Start─┬────────────────────────────────────────────────────────────;K
└─sTop──┘
You can examine the contents of the system macro trace block — from any CRAS authorized terminal.
The format of the command is:
┌─,─────┐
;;──ZTRAC──Block,──Display──┼────────┼──────────────────────────────────────────────────;K
├─,count─┤
└─,All───┘
Where:
Start
Start tracing to the system macro trace block.
sTop
Stop tracing.
Display
Display the contents of the system macro trace block on the terminal.
Use Display with no other parameters to show whether trace is active or not.
count
Display the last count entries from the system macro trace block, where count is a decimal number. If
count is omitted or zero (the default), the response shows only whether trace is active or inactive.
All
Display all entries, from the system macro trace block.
This command invokes the ALCS scrolling function. You can print the display by using the ZSCRL PRINT
command. See -- Heading 'ZSCRL' unknown --.
164
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ZTRAC
10.3 Tracing to the ALCS diagnostic file
Control tracing to the ALCS diagnostic file — from a Prime CRAS authorized terminal. You can run the
ALCS diagnostic file processor later as a batch job. However the Display parameter can be used from
any CRAS terminal.
The format of the command is:
┌─,─────────┐
D┬─────────┬┴─┬───────────────────────────────────────;K
;;──ZTRAC──Diag,──┬─┬─Start,───┬───
│ ├─Add,─────┤ ├─D=dlist─┤ │
│ └─Replace,─┘ ├─F=flist─┤ │
│
├─I=ilist─┤ │
│
├─M=mlist─┤ │
│
├─P=plist─┤ │
│
└─T=tlist─┘ │
├─Display─────────────────────┤
└─sTop────────────────────────┘
Where:
Start
Start tracing to the ALCS diagnostic file, with or without trace control parameters.
Add
Add to trace control parameters.
Replace
Replace the specified trace control parameters with the new specifications.
Display
Show whether trace is active or not, and which trace control options are in effect.
sTop
Stop tracing.
10.3.1 Trace control parameters
You can restrict the scope of tracing by specifying trace control parameters, and you can change these
parameters during tracing.
The parameters are successively restrictive. For example:
ZTRAC DIAG,START,P=(AAAA,BBBB)
Traces all monitor-request macros in programs AAAA and BBBB.
ZTRAC DIAG,START,P=(AAAA,BBBB),M=(FIND)
Traces only find-type monitor-request macros in programs AAAA and BBBB. It does not trace
find-type monitor-request macros in other programs.
Incompatible trace control parameters
Do not specify either F= or I= with M=.
Chapter 10. Using the ALCS trace facility
165
ZTRAC
Multiple values for control parameters
Each control parameter can have a list of values enclosed in parentheses and separated by commas. If
only one value is specified, the parentheses can be omitted. For example, D=dlist can be:
D=(EBW,EBX)
or
D=EBW
The trace control parameters are as follows
D=dlist
At each trace intercept, write the specified data items to the ALCS diagnostic file, where dlist can be
one or more of the values in Figure 121.
Figure 121. Tracing to the ALCS diagnostic file: The D= parameter
|
|
|
|
dlist
Data written to the ALCS diagnostic file
Synonyms
ALL
Whole ECB (including the TPFDF stack, detached blocks, and in-use
DECBs)
AW EA
EBL
ECB local program work area
CE1WKC
EBW
ECB work area 1
CE1WKA
EW
EBX
ECB work area 2
CE1WKB
EX
EBD
ECB descriptor
EBP
ECB prefix
DECB
All DECB descriptors and application areas
LEVELs
ECB storage levels and data levels
LEVs
DLEVELS
Storage levels and data levels for in-use DECBs
DLEVs
ER
Relevant parts of ECB — those parts that the monitor-request macro
references
GPRs
General registers
Gr
REGs
FPRs
Floating-point registers
FP
Fr
SA
All attached storage blocks
SR
Relevant attached storage blocks — those blocks that the
monitor-request macro references
MAXimum
Maximum display (includes all the above)
EL
DL
R
MX
Omit D= to write minimum data to the ALCS diagnostic file giving the ECB address, the program name
and listing address, and the macro and macro parameters.
F=flist
Trace up to 8 file addresses. flist is the file address (8 hexadecimal digits), or the record type and
record ordinal number in the form:
type(ordinal)
Note that this restricts the trace to monitor-request macros that refer to file addresses; do not specify
F= with M=.
166
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ZTRAC
I=ilist
Trace references to up to 8 record IDs. ilist is the record ID (4 hexadecimal digits or 2 alphanumeric
characters). Note that this restricts the trace to monitor-request macros that refer to record IDs; do not
specify I= with M=.
M=mlist
Trace up to 8 monitor-request macros and up to 32 macro groups. mlist is the macro request type or
macro group name. The macro request type is usually the macro name, but see ALCS Application
Programming Reference – Assembler for a list of the exceptions and a list of macro group names.
Omit M= on a start command, or specify M=ALL to trace all monitor-request macros.
P=plist
Trace up to 8 programs. plist can be:
5 A 4-character program name, or
5 A 1-, 2-, or 3-character string, to mean all programs whose names begin with these characters.
Prefix the string with − (minus) to exclude that program or programs.
For example, P=(A,−AB) traces all programs whose names begin with A, except those whose names
begin with AB.
Omit P= on a start command, to trace all programs.
T=tlist
Trace messages from up to 8 terminals. tlist is the CRI or CRN of the selected terminal.
Omit T= on a start command, to trace all entries, including entries that are not messages.
Chapter 10. Using the ALCS trace facility
167
ZTRAC
10.4 Tracing to the MVS generalized trace facility
Control tracing of VTAM RPLs to the MVS generalized trace facility (GTF) — from a Prime CRAS
authorized terminal. However the Display parameter can be used from any CRAS terminal.
The format of the command is:
;;──ZTRAC──Gtf,──┬─┬─Start,───┬──┬─────────┬─┬──────────────────────────────────────────;K
│ ├─Add,─────┤ └─T=tlist─┘ │
│ └─Replace,─┘
│
├─Display───────────────────┤
└─sTop──────────────────────┘
Where:
Start
Start GTF tracing.
Add
Add to trace control parameters.
Replace
Replace the specified trace control parameters with the new specifications.
Display
Show whether GTF trace is active or not and which trace control options are in effect.
sTop
Stop GTF tracing.
T=tlist
Generate GTF trace for activity related to up to 8 SNA communication resources. tlist is the CRI or
CRN of the selected terminal. Specify T=000000 to trace SNA communication activity that is not
specific to a particular resource. Omit T= on a start command to trace all SNA communication
resources.
168
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ZTRAC
10.5 Workstation trace
Workstation and conversational trace can be made active or inactive by entering a command – from a
Prime CRAS authorized terminal only. See 10.7, “Conversational tracing” on page 171.
If workstation trace is active, you can run it to control the remote workstation debugger facility for C/C++
programs from any CRAS authorized display.
The format of the command is:
;;──ZTRAC──Ws,──┬─Start,──┬─wsAddr=address─┬─┬──────────────────────────────────────────;K
│
└─wsName=name────┘ │
├─Display────────────────────┤
└─sTop───────────────────────┘
Where:
Start
Start remote workstation debugger session.
Display
Show whether a remote workstation debugger session has been started for this terminal, and which
trace control option is in effect.
sTop
Stop remote workstation debugger session.
wsAddr=address
address is the identity of the remote workstation, as a TCP/IP address in the dotted decimal format:
iii.iii.iii.iii
Where iii is 1-3 decimal digits (0-255).
wsName=name
name is the identity of the remote workstation as a 1-60 character TCP/IP domain name.
Chapter 10. Using the ALCS trace facility
169
ZTRAC
10.6 TPFDF macro trace
The tracing of TPFDF macro calls can be made active or inactive by entering a command – from a Prime
CRAS authorized terminal only. You can obtain the status of TPFDF macro trace by entering the Display
command from any CRAS terminal.
The format of the command is:
;;──ZTRAC──cEp──┬─Start───┬─────────────────────────────────────────────────────────────;K
├─sTop────┤
└─Display─┘
Where:
Start
Make TPFDF macro trace active. Provide TPFDF trace data in ALCS dumps (in the entry
macro trace) and also provide it during conversational and diagnostic trace.
sTop
Make TPFDF macro trace inactive.
Display
Show whether TPFDF macro trace is active or inactive.
Note: The initial status of TPFDF macro trace is defined in the ALCS system generation. See
the SCTGEN macro for a description of the SCTGEN TPFDF parameter.
10.6.1 TPFDF macro trace data
When TPFDF macro trace is active, ALCS obtains trace data for each TPFDF macro call issued by an
application program. TPFDF trace data is provided in ALCS system error dumps (in the entry macro
trace) and provided in conversational and diagnostic trace. Each TPFDF macro call is shown in the
various traces as monitor-request macro "TDFAC".
170
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ZTRAC
10.7 Conversational tracing
Conversational and workstation trace can be made active or inactive by entering a command — from a
Prime CRAS authorized terminal only.
If conversational tracing is active, you can run it — from any CRAS authorized display. If you are
running conversational trace, you can start or stop asynchronous trace – from a Prime CRAS authorized
terminal or an Alternate CRAS AT1 to AT16 authorized terminal only.
The format of the command is:
┌─Conv,─┐
┌─,─────────────────────────┐
;;──ZTRAC──┴───────┴──┬─┬─Start,──┬────────┬─┬───D┬─────────────────────────┬┴─┬───────────────────;K
│ │
└─T=term─┘ │ ├─A=alist─────────────────┤ │
│ ├─Add,───────────────┤
├─D=dlist─────────────────┤ │
│ └─Replace,───────────┘
├─F=flist─────────────────┤ │
│
├─G=glist─────────────────┤ │
│
├─I=ilist─────────────────┤ │
│
├─M=mlist─────────────────┤ │
│
├─P=plist─────────────────┤ │
│
├─R=rlist─────────────────┤ │
│
└─Intercept,────┬─ON──┬───┘ │
│
└─OFF─┘
│
├─Display───────────────────────────────────────────────┤
├─Process,message───────────────────────────────────────┤
├─sTop──────────────────────────────────────────────────┤
└─Vary──┬─,Active───┬───────────────────────────────────┘
├─,Inactive─┤
└─,Display──┘
Where:
Start
Start conversational tracing, with or without trace control options.
T=term
Trace input messages from a remote terminal. term is the CRI or CRN of the remote terminal.
Before you start tracing a remote terminal, be sure to check that the user at the remote terminal
understands what you plan to do and agrees to it.
Note: term cannot be the CRN or CRI of the unique Prime CRAS.
Add
Add to trace control options.
Replace
Replace the specified trace control parameters with the new specifications.
Display
Show whether trace is active or not, and which trace control options are in effect.
Also show whether asynchronous trace is active or not.
Intercept ON/OFF
Start (ON) or stop (OFF) asynchronous trace.
At least one program must be included in your trace control options before starting asynchronous
trace.
Chapter 10. Using the ALCS trace facility
171
ZTRAC
Note: Intercept (ON) and Intercept (OFF) can only be entered from a Prime CRAS authorized
terminal, or an AT1 to AT16 authorized terminal.
Process,message
Process an input message or ALCS command without tracing it. message is the input message or
ALCS command.
sTop
Stop trace.
Vary,{Active|Inactive|Display}
Vary conversational and workstation trace for the whole system. Where:
Active
Inactive
Display
Make conversational and workstation trace active so that any CRAS terminal can use
them.
Make conversational and workstation trace inactive so that no terminal can use them.
Use this command from any CRAS display terminal to find out whether conversational
and workstation trace are active or inactive.
Note: Vary (Active) and Vary (Inactive) can only be entered from a Prime CRAS authorized
terminal.
10.7.1 Restrictions
Conversational tracing can trace entries that originate from terminal input messages. Asynchronous trace
can also trace entries that are created by the system – for example time-initiated processing, WTTY
processing, and so on. Many installations do not allow conversational tracing on production systems. If
you cannot use conversational tracing, trace to the ALCS diagnostic file instead.
Conversational trace can be used to trace ALCS macros issued by C language applications through the C
application programming interface routines. However you should not use instruction stepping with C
language application programs. See 10.22, “STEP — Control instruction stepping” on page 200.
10.7.2 Trace control parameters
You can restrict the scope of tracing by specifying trace control parameters, and you can change these
parameters during tracing.
The parameters are successively restrictive. For example:
ZTRAC CONV,START,P=(AAAA,BBBB)
traces all monitor-request macros in programs AAAA and BBBB.
ZTRAC CONV,START,P=(AAAA,BBBB),M=(FIND)
traces only find-type monitor-request macros in programs AAAA and BBBB. It does not trace find-type
monitor-request macros in other programs.
Incompatible trace control parameters
Do not specify either F= or I= with M=.
Multiple values for control parameters
Each control parameter can have a list of values enclosed in parentheses and separated by commas. If
only one value is specified, the parentheses can be omitted. For example, D=dlist can be:
D=(EBW,ER,SA)
or
172
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ZTRAC
D=EBW
The trace control parameters are as follows:
A=alist
Set up to 8 address stops at specified program displacements. The format for each value in the
A=alist can be either:
pname,disp
pname(disp)
where pname is the 4-character program name, and disp is the displacement in hexadecimal (as it
appears in the program listing). The displacement can be any value in the range X'20' through
X'FFFF'.
D=dlist
At each trace intercept, display the specified data on the terminal, where dlist is one or all of the
values in Figure 122.
Figure 122. Tracing to an ALCS terminal: The D= parameter
|
dlist
Contents of display
Synonyms
ALL[,W]
Full-screen display of registers, ECB storage and data levels,
ECB work area 1 (CE1WKA), and so on
AW EA
ALL,X
Same as ALL,W but with ECB work area 2 (CE1WKB)
AX
ALL,L
Same as ALL,W but with ECB local program work area.
AL
EBL
ECB local program work area.
CE1WKC
EBW
ECB work area 1
CE1WKA
EW
EBX
ECB work area 2
CE1WKB
EX
LEVELs
ECB storage levels and data levels
LEVs
DLEVELs
Storage levels and data levels for in-use DECBs
DLEVs
GPRs
General registers
Gr
REGs
FPRs
Floating-point registers
FP
Fr
EL
DL
R
Omit D= for a minimum display giving the program name and listing address, and the macro or
instruction.
Any unsupported trace display controls are ignored.
F=flist
Trace up to 8 file addresses. flist is the file address (8 hexadecimal digits), or the record type and
record ordinal number in the form:
type(ordinal)
Note that this restricts the trace to monitor-request macros that refer to file addresses; do not specify
F= with M=.
G=glist
Set up register stops for a specific register containing a specific value or range of values. This
parameter sets up the register/value combinations to be used later (see 10.19, “REGSTOP — Register
stop” on page 195 for more information about how they are used).
Up to 8 register/value combinations can be specified, and the format for each value in the glist can be
either:
Chapter 10. Using the ALCS trace facility
173
ZTRAC
register(value)
register(value1-value2)
Where:
register
The general purpose register (decimal digits, 0-9, 14-15)
value
Stop when the register contains this value (maximum 8 hex digits)
value1-value2
Stop when the register contains a value within this range (maximum 8 hex digits, value2 > value1)
I=ilist
Trace references to up to 8 record IDs. ilist is the record ID (4 hexadecimal digits or 2 alphanumeric
characters). Note that this restricts the trace to monitor-request macros that refer to record IDs; do not
specify I= with M=.
M=mlist
Trace up to 8 specified monitor-request macros and up to 32 macro groups. mlist is the macro
request type or macro group name. The macro request type is usually the macro name, but see
ALCS Application Programming Reference – Assembler for a list of the exceptions and a list of macro
group names.
For example:
ZTRAC CONV START M=(PROGRAM,FILE)
Start conversational trace, and trace all macros in groups PROGRAM and FILE.
ZTRAC CONV REPLACE M=(CREATE,FIND,SEND)
Replace the selection of macros to be traced by the macros in groups CREATE, FIND, and
SEND.
ZTRAC CONV ADD M=(DEFRC,PROGRAM)
Add the macro DEFRC and the macros in group PROGRAM to the selection of macros already
traced.
Omit M= or specify M=ALL to trace all monitor-request macros.
P=plist
Trace up to 8 programs. plist can be:
5 A 4-character program name, or
5 A 1-, 2-, or 3-character string, to mean all programs whose names begin with these characters.
Prefix the string with − (minus) to exclude that program or programs.
For example, P=(A,-AB) traces all programs whose names begin with A, except those whose names
begin with AB.
Omit P= to trace all programs.
R=rlist
Trace references to an address (or range of addresses) in main storage. This parameter sets up the
references to be used later (see 10.18, “REFSTOP — Reference stop” on page 194 for more information
about how the references are used).
Up to 8 addresses can be specified, and the format for each value in the rlist is:
refstop(range[,S|R])
Where:
174
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ZTRAC
refstop
The hexadecimal storage address or the name of an ECB field, for example, EBW000.
range
The number of consecutive locations to be included in the address range. For example,
R=EBW(3)
sets a check for any references to EBW000, EBW000+1, and EBW000+2. If refstop is the name
of an ECB field, the default range is the length of the ECB field. Otherwise, the default range is
one.
[S|R]
Specify S to set a stop when information is stored within the specified address range.
Specify R to set a stop when a reference is made within the specified address range.
Chapter 10. Using the ALCS trace facility
175
10.8 Running a conversational trace
The normal response to ZTRAC CONV,START,... is :
k
TRACE — ENTER THE MESSAGE TO TRACE
l
ALCS traces the next input message or ALCS command, except when it is:
Clear key
Null message
ZTRAC command
ZLOGF command
ALCS
ALCS
ALCS
ALCS
processes this without tracing it.
discards this without tracing it.
processes this without tracing it.
processes this without tracing it.
Note: The command ZTRAC PROCESS,message processes the message without tracing it. When you
enter the input message for ALCS to trace, the ALCS trace displays a message to show that processing
the new message is about to start. The message includes a header like this:
k
TRACE -- prog
NEW ENTRY
l
Where:
prog
The name of the first program that processes the new entry for the input message.
Depending on the display (D=) trace control option, there may be more information following the standard
header.
You can now either:
5 Press Enter to start processing.
5 Enter a trace control command.
If you press Enter, then the processing of your input message proceeds normally until the entry executes
a monitor-request macro. If your trace control options exclude that macro, processing proceeds until the
entry executes a macro that is not excluded.
Processing then stops and the trace displays a message that shows the entry is paused, waiting to
execute the macro. The message includes a header like this:
k
TRACE — prog list macro operand
l
Where:
prog
list
macro
operand
Name of the program that contains the macro.
Listing address of the macro within the program.
Request type. This is usually the macro name, but there are some exceptions (see ALCS
Application Programming Guide for more information).
Operand field of the macro. Note that this does not appear for all macros. Also the format is
not necessarily identical to the program source code.
If the monitor-request macro is not within a program (for example, if it is in the ECB) then the standard
header shows its 8-byte storage address instead of the program name and listing address.
176
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Depending on the display (D=) trace control option, there may be more information following the standard
header. You can now either:
5 Press Enter to proceed to the next monitor-request macro.
5 Enter a trace control command.
The following sections describe the ALCS trace control commands
10.9, “ADSTOP — Address stop” on page 182
Continue processing the entry (ignoring other trace control options) until the entry reaches one of the
selected address-stop locations.
10.10, “ANYSTOP — Any stop” on page 183
Continue processing the entry (ignoring other trace control options) until the entry reaches one of the
selected address-stop, reference-stop, or register-stop conditions.
10.11, “BRANCH — Branch to address” on page 184
Continue processing the entry starting at a specified address.
10.13, “DISPLAY — Display fields” on page 187
Display storage contents, register contents, and so on.
10.14, “EXIT — Exit current entry” on page 190
Simulate an EXITC monitor-request macro.
10.15, “FLUSH — Flush current entry” on page 191
Allow the entry to complete processing without further tracing.
10.16, “HELP — Display trace help information” on page 192
See also -- Heading 'ZHELP' unknown --.
10.17, “PROCESS — Process message” on page 193
Process an input message without tracing it.
10.18, “REFSTOP — Reference stop” on page 194
Continue processing the entry (ignoring other trace control options) until the entry reaches one of the
selected reference-stop locations.
10.19, “REGSTOP — Register stop” on page 195
Continue processing the entry (ignoring other trace control options) until the entry reaches one of the
selected register-stop conditions.
10.20, “SET — Set fields” on page 196
Set storage contents, register contents, and so on.
10.21, “SKIP — Skip next instruction or macro” on page 199
Branch past next instruction or macro.
10.22, “STEP — Control instruction stepping” on page 200
Start or stop instruction stepping3.
10.23, “SWAP — Swap current entry” on page 203
Swap from tracing the current entry to tracing a created entry.
3
ALCS trace facility also supports the old ISTEP and UNSTEP commands for the benefit of users who are familiar with these
commands. ISTEP is a synonym for STEP ON. UNSTEP is a synonym for STEP OFF.
Chapter 10. Using the ALCS trace facility
177
Z...
Any input message starting with Z. ALCS trace facility processes the message as an ALCS
command. Note that this unconditionally passes the input message to the ALCS command processor.
To pass the message to an application, use PROCESS Z....
Note that ALCS trace facility can support user-defined commands. The format and function of these
user-defined commands (if any) are installation-dependent.
10.8.1 Restriction
You cannot use the ZAKEY command to set trace commands.
10.8.2 Tracing create-type macros
When processing stops at a create-type monitor-request macro (CREMC, CREDC, or CREXC), the ALCS trace
facility behaves slightly differently. When you press Enter following the normal ALCS trace facility
message, ALCS does not proceed immediately to the next macro to be traced. Instead, it displays a
message to show that there is a new entry. This message includes a header like this:
k
TRACE — prog
NEW ENTRY
l
Where:
prog
Name of the program that processes the new entry.
Depending on the display (D=) trace control option, there may be more information following the standard
header.
Following this message, press Enter again to proceed to the next macro in the program that issues the
create-type monitor-request macro (not to the first monitor-request macro in the new entry). 10.23, “SWAP
— Swap current entry” on page 203 explains how to swap from tracing one entry to another.
10.8.3 Tracing system errors
Program exceptions, SERRC or SYSRA monitor-request macros, and application program errors detected by
the ALCS online monitor normally generate a system error dump and send a system error message to the
RO CRAS. But when ALCS trace facility is tracing an entry, it intercepts these system errors. It does not
generate a dump and does not send a message to the RO CRAS. Instead, it:
1. Stops processing the entry.
2. Displays the system error message.
3. Resets the next sequential instruction address for the entry to re-execute the failing instruction or
monitor-request macro.
4. Displays the normal ALCS trace facility message (on the next line, following the system error
message).
This provides an opportunity to correct the error condition (see, for example, 10.20, “SET — Set fields” on
page 196). After correcting the error, press Enter to re-execute the failing instruction or monitor-request
macro. Alternatively, you can branch past the failing instruction or monitor-request macro (see 10.21,
“SKIP — Skip next instruction or macro” on page 199 and 10.11, “BRANCH — Branch to address” on
page 184).
178
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Note: ALCS conversational tracing always traces system errors, regardless of the trace options
specified.
10.8.4 Tracing EXITC
Eventually, all the entries that process the input message terminate with an EXITC monitor-request macro.
When this happens, the ALCS trace facility starts tracing any exit intercept program set up by the SXIPC
monitor-request macro, and then shows that it is ready to trace another input message by displaying:
k
l
TRACE — ENTER MESSAGE TO TRACE
Enter the next message to trace, or ZTRAC STOP to stop conversational trace.
Note: ALCS conversational tracing always traces EXITC, regardless of the trace options you specify.
If records are held when the EXITC macro is reached then the following message is produced:
k
l
TRACE — prog list EXITC — WARNING — n RECORDS HELD
If resources are held when the EXITC macro is reached then the following message is produced:
k
l
TRACE — prog list EXITC — WARNING — n RESOURCES HELD
If TPFDF files are open when the EXITC macro is reached then the following message is produced:
k
l
TRACE — prog list EXITC — WARNING — n TPFDF FILES OPEN
If you want a dump to be placed on the diagnostic file, reply to these messages by pressing Enter.
If you do not want a dump to be placed on the diagnostic file, reply to the messages with the EXIT
command
10.8.5 Tracing High Level Language (HLL) Programs
You can use conversational trace to trace the execution of ALCS macros called from HLL programs. You
can also trace the execution of assembler instructions in assembler library routines called from a HLL. It
is not possible to trace the instructions generated by the language compilers or any code that modifies the
ALCS reserved registers.
HLL language support uses the HLLCC macro to interface with ALCS. The following messages are
displayed by conversational trace when a HLL program is executed:
k
TRACE – prog list HLLCC CREATING HLL ENVIRONMENT
l
A new HLL environment is created for the ECB. A control block will be attached at monitor level 3.
Chapter 10. Using the ALCS trace facility
179
k
TRACE – prog list HLLCC LOADING MODULE=module
l
The module module is loaded (if not previously loaded). HLL support loads various modules from the LE
runtime library depending on the languages being used.
k
TRACE – prog list HLLCC GETMAIN LENGTH=length
l
A contiguous area of length length is obtained from the entry's HLL storage units.
k
TRACE – prog list HLLCC GETMAINSHARED LENGTH=length
l
A contiguous area of length length is obtained from main storage.
k
TRACE – prog list HLLCC FREEMAIN LENGTH=length
LOCATION=address
l
A previously obtained area of storage is returned to the entry's HLL storage unit. The storage is at
location address and is length bytes long.
k
TRACE – prog list HLLCC DELETING HLL ENVIRONMENT
l
The entry's current HLL environment is deleted. The control block at monitor level 3 and associated HLL
storage units are released.
If you use the DISPLAY verb in COBOL application programs during debugging, then the messages created
are routed to the display terminal.
10.8.6 Tracing a remote terminal
The normal response to ZTRAC CONV,START,T=term,... is:
k
TRACE — AWAITING INPUT FROM term
l
ALCS traces the next input message or ALCS command from terminal 'term', except when it is:
Clear key
ALCS processes this without tracing it.
Null message
ALCS discards this without tracing it.
ZTRAC command
ALCS processes this without tracing it.
ZLOGF command
ALCS processes this without tracing it.
Trace continues as for normal conversational trace.
180
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
10.8.7 Asynchronous trace
The normal response to ZTRAC CONV,INTERCEPT,ON is:
k
l
TRACE — AWAITING PROGRAM EXECUTION
ALCS traces the next entry that uses any of the programs included in your trace control options.
Processing then stops and the trace displays a message that shows the entry is paused, waiting to use
the program. The message includes a header like this:
k
l
TRACE — prog INTERCEPTED ENTRY
Where:
prog
prog The name of the program that is about to process the entry.
Depending on the display (D=) trace control option, there may be more information following the header
shown above.
You can now either:
5
5
Press Enter to start processing.
Enter a trace control command.
Trace continues as for normal conversational trace. When you have finished tracing the entry, you can
restart asynchronous trace by entering ZTRAC CONV,INTERCEPT,ON.
Chapter 10. Using the ALCS trace facility
181
ADSTOP
10.9 ADSTOP — Address stop
When conversational tracing is active, use the ADSTOP command to continue processing the entry without
tracing it, ignoring all other trace control options, until the program reaches one of the address-stop
locations specified in the A= trace control parameters.
The format of the command is:
;;──┬─Adstop─┬──────────────────────────────────────────────────────────────────────────;K
└─ADstop─┘
ALCS trace facility stops before the instruction at the address-stop location executes. Then it sends a
display that is the same as the instruction step display (see 10.22, “STEP — Control instruction stepping”
on page 200). Then ALCS trace facility continues as before the ADSTOP command.
It is possible that the entry never gets to an address-stop location. To guard against this, ALCS trace
facility stops the entry if any of the following occurs before it gets to an address-stop location:
5
5
5
5
The
The
The
The
entry
entry
entry
entry
exits.
sends a response message to the originating terminal.
executes 10 000 monitor-request macros.
executes 30 000 instructions.
Note: For this purpose, DLAYC and DEFRC count as 100 macros to prevent a long wait before the response
is received.
10.9.1 Normal responses
The same as for instruction step. See 10.22, “STEP — Control instruction stepping” on page 200.
If ALCS trace facility stops the entry before it gets to an address-stop location, one of the following lines
can precede the standard header:
k
k
TRACE — STEP/ADSTOP/REFSTOP/REGSTOP halt after 1 macros
TRACE — STEP/ADSTOP/REFSTOP/REGSTOP halt after 3 instructions
In either case, you can re-enter ADSTOP to continue searching for the address stop location.
182
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
l
l
ANYSTOP
10.10 ANYSTOP — Any stop
When conversational tracing is active, use the ANYSTOP command to continue processing the entry without
tracing it, ignoring all other trace control options, until the program reaches one of the stop conditions
specified in any of the A=, G= or R= trace control parameters.
The format of the command is:
;;──ANYstop─────────────────────────────────────────────────────────────────────────────;K
See 10.9, “ADSTOP — Address stop” on page 182, 10.18, “REFSTOP — Reference stop” on page 194, and
10.19, “REGSTOP — Register stop” on page 195 for information as to where the trace facility stops
depending on whether the stop condition reached is that specified on the A=, R= or G= trace control
parameter.
When the trace facility stops it sends a display that is the same as the instruction step display (see 10.22,
“STEP — Control instruction stepping” on page 200). Then ALCS trace continues as before the ANYSTOP
command.
It is possible that the entry never reaches an address-stop, reference-stop or register-stop condition. To
guard against this, ALCS trace facility stops the entry if any of the following occurs before it reaches an
address-stop, reference-stop or register-stop condition.
5
5
5
5
The
The
The
The
entry
entry
entry
entry
exits.
sends a response message to the originating terminal.
executes 10 000 monitor-request macros.
exceeds 30 000 instructions.
Note: For this purpose, DLAYC and DEFRC count as 100 macros to prevent a long wait before the
response is received.
10.10.1 Normal response
The same as for instruction step. See 10.22, “STEP — Control instruction stepping” on page 200.
If ALCS trace facility stops the entry before it reaches an address-stop, reference-stop or register-stop
condition, one of the following lines can precede the standard header:
k
k
TRACE –
STEP/ADSTOP/REFSTOP/REGSTOP halt after 1 macros
TRACE –
STEP/ADSTOP/REFSTOP/REGSTOP halt after 3 instructions
l
l
In either case, you can reenter ANYSTOP to continue searching for the address-stop, reference-stop or
register-stop condition.
Chapter 10. Using the ALCS trace facility
183
BRANCH
10.11 BRANCH — Branch to address
When conversational tracing is active, use the BRANCH command to branch to an address; that is, to set the
next instruction address. BRANCH is equivalent to SET IA=.
The format of the command is:
;;──┬─Branch─┬──,address────────────────────────────────────────────────────────────────;K
└─BRanch─┘
Where:
address
Branch-to address. That is, the new value of the next sequential instruction address. One of:
hex
Main storage address in hexadecimal.
disp(gpr)
Displacement (disp) in hexadecimal from the address in general register
gpr.
Where gpr can be:
R0, R00, RG0, or RAC
R1, R01, or RG1
R2, R02, RG2, or RGA
R3, R03, RG3, or RGB
R4, R04, RG4, or RGC
R5, R05, RG5, or RGD
R6, R06, RG6, or RGE
R7, R07, RG7, or RGF
R8, R08, RG8, or RAP
R9, R09, RG9, or REB
R14, RG14, or RDA
R15, RG15, or RDB
General
General
General
General
General
General
General
General
General
General
General
General
register
register
register
register
register
register
register
register
register
register
register
register
0
1
2
3
4
5
6
7
8
9
14
15
disp(gpr1,gpr2)
Displacement (disp) in hexadecimal from the address in general register
gpr2 plus the index value in gpr1. gpr1 and gpr2 can be any general
register names (see the above list).
disp(SBx)
Displacement (disp) in hexadecimal into the storage block attached at level
x.
disp(AUT)
Displacement (disp) in hexadecimal into the automatic storage block.
LIST disp
Displacement (disp) in hexadecimal into the application program.
BRANCH first evaluates address in any of the above formats as a 4-byte (32-bit) number. It interprets
the 4-byte number as a 24-bit address (ignores the high-order byte) if the entry is running in 24-bit
addressing mode, or as a 31-bit address (that is, it ignores the high-order bit) if the entry is running in
31-bit addressing mode.
You can use SET IA= or BRANCH during macro trace as well as during instruction step. This allows you, for
example, to branch around a monitor-request macro You can also set the instruction address to
addresses outside the active program — for example, to a subroutine in an ECB work area or in an
attached block.
184
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
BRANCH
10.11.1 Normal response
The same as for instruction step. See 10.22, “STEP — Control instruction stepping” on page 200.
Chapter 10. Using the ALCS trace facility
185
DETAIL
10.12 Display internal TPFDF macro calls
When conversational trace and TPFDF macro trace are active, use the DETAIL command to display
internal TPFDF macro calls and other internal monitor-request macros issued by TPFDF programs.
The format of the command is:
;;──DETAIL──┬─ON──┬─────────────────────────────────────────────────────────────────────;K
└─OFF─┘
Where:
ON
Display internal TPFDF macro calls and other internal monitor-request macros.
OFF
Do not display internal TPFDF macro calls and other internal monitor-request macros.
186
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
DISPLAY
10.13 DISPLAY — Display fields
When conversational tracing is active, use the DISPLAY command to display the contents of main storage,
registers, and so on.
The format of the command is:
|
|
|
|
|
;;──Display,──┬────────────────────────┬────────────────────────────────────────────────;K
│
┌─,W─┐
│
├─ALL──┼────┼────────────┤
│
├─,L─┤
│
│
└─,X─┘
│
├─AUT──┬───────┬─────────┤
│
└─,disp─┘
│
├─CC─────────────────────┤
├─DCx────────────────────┤
├─DTx────────────────────┤
├─DT,decb────────────────┤
├─┬─EBL─┬────────────────┤
│ ├─EBW─┤
│
│ └─EBX─┘
│
├─ecb_label──┬────────┬──┤
│
└─,words─┘ │
├─┬─FPR─┬────────────────┤
│ ├─GPR─┤
│
│ └─reg─┘
│
├─IA─────────────────────┤
├─┬─LEVELs─┬─────────────┤
│ └─LEVs───┘
│
├─┬─DLEVELs─┬────────────┤
│ └─DLEVs───┘
│
├─LIST,disp──┬────────┬──┤
│
└─,words─┘ │
├─MS,address──┬────────┬─┤
│
└─,words─┘ │
├─MTB────────────────────┤
├─NeST───────────────────┤
├─SBx──┬───────┬─────────┤
│
└─,disp─┘
│
└─SB,decb──┬───────┬─────┘
└─,disp─┘
Where:
Display with no parameters repeats the trace display for the current monitor-request macro (or for the
current instruction if instruction stepping).
ALL[,W|,L|,X]
Full-screen display of registers, storage and data levels, ECB work area, and so on, where:
L
W
X
Display includes ECB local program work area (CE1WKC, fields EBL...).
Display includes ECB work area 1 (CE1WKA, fields EBW...).
Display includes ECB work area 2 (CE1WKB, fields EBX...).
Chapter 10. Using the ALCS trace facility
187
DISPLAY
AUT[,disp]
Display contents of the current automatic storage block. disp is the displacement within the block
where the display starts; it is in hexadecimal and defaults to 0.
CC
Display the current setting of the condition code.
DCx
Display information about blocks detached by TPFDF. Specify DC0 for information about detached
blocks for level D0, and so on.
DTx
Display information about detached blocks for level x. Specify DT0 for information about detached
blocks for level D0, and so on.
| DT,decb
|
Display information about detached blocks for the DECB at address decb.
EBL|EBW|EBX
Display contents of ECB local program work area CE1WKC (EBL) , or ECB work area 1, CE1WKA (EBW)
or ECB work area 2, CE1WKB (EBX).
ecb_label[,words]
Display contents of ECB field. ecb_label is the name of the field in the EBEB DSECT. words is the
number of fullwords to display; it is in decimal and it defaults to 4.
FPR|GPR|reg
Display contents of all floating-point registers (FPR), of all general registers (GPR), or of an individual
register (reg). reg is one of:
F, FR, FPR, or FPRS
All floating-point registers
FP0
Floating-point register 0
FP2
Floating-point register 2
FP4
Floating-point register 4
FP6
Floating-point register 6
G, R, GR, GPR, GPRS, REG, or REGS All general registers (except registers 10—13, which cannot
be displayed)
R0, R00, RG0, or RAC
General register 0
R1, R01, or RG1
General register 1
R2, R02, RG2, or RGA
General register 2
R3, R03, RG3, or RGB
General register 3
R4, R04, RG4, or RGC
General register 4
R5, R05, RG5, or RGD
General register 5
R6, R06, RG6, or RGE
General register 6
R7, R07, RG7, or RGF
General register 7
R8, R08, RG8, or RAP
General register 8
R9, R09, RG9, or REB
General register 9
R14, RG14, or RDA
General register 14
R15, RG15, or RDB
General register 15
IA Display the next instruction address.
|
LEVELs|LEVs
Display the contents of the ECB data and storage levels.
| DLEVELs|DLEVs
|
Display the contents of the data and storage levels for in-use DECBs.
188
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
DISPLAY
LIST,disp[,words]
Display the contents of the program that is currently executing. disp is the displacement (listing
address) where the display starts; it is in hexadecimal. words is the number of fullwords to display; it
is in decimal and defaults to 4.
MS,address[,words]
Display the contents of main storage at address, one of:
hex
disp(gpr)
disp(gpr1,gpr2)
|
|
|
|
disp(SBx)
disp(SB,decb)
disp(AUT)
LIST disp
Main storage address in hexadecimal.
Displacement (disp) in hexadecimal from the address in general register
gpr. gpr can be any general register name (see list above).
Displacement (disp) in hexadecimal from the address in general register
gpr2 plus the index value in gpr1. gpr1 and gpr2 can be any general
register names (see list above).
Displacement (disp) in hexadecimal into the storage block attached at ECB
level x.
Displacement (disp) in hexadecimal into the storage block attached to the
DECB at address decb.
Displacement (disp) in hexadecimal into the automatic storage block.
Displacement (disp) in hexadecimal into the application program.
DISPLAY first evaluates address in any of the above formats as a 4-byte (32-bit) number. Then it
interprets the 4-byte number as a 24-bit address (that is, it ignores the high-order byte) if the entry is
running in 24-bit addressing mode. It interprets it as a 31-bit address (that is, it ignores the high-order
bit) if the entry is running in 31-bit addressing mode.
words is the number of fullwords to display; it is in decimal and defaults to 4.
MTB
Display the entry macro trace block.
NEST|NST
Display program nesting information.
SBx[,disp]
|
Display the contents of the storage block attached at ECB level x. Specify SB0 for the block attached
at level D0, and so on. disp is the displacement within the block where the display starts; it is in
hexadecimal and it defaults to 0.
| SB,decb[,disp]
|
Display the contents of the storage block attached to the DECB at address decb. disp is the
|
displacement within the block where the display starts; it is in hexadecimal and it defaults to 0.
Chapter 10. Using the ALCS trace facility
189
EXIT
10.14 EXIT — Exit current entry
When conversational tracing is active, use the EXIT command to force the current entry to exit by
simulating an EXITC monitor-request macro, including taking any exit intercept program set up by the SXIPC
monitor-request macro. Unlike the real EXITC, it does not dump if it detects that records or resources are
held, or general tapes are assigned. The format of the command is:
;;──Exit────────────────────────────────────────────────────────────────────────────────;K
190
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FLUSH
10.15 FLUSH — Flush current entry
When conversational tracing is active, use the FLUSH command to allow processing of the current entry to
complete without further tracing. The format of the command is:
;;──Flush───────────────────────────────────────────────────────────────────────────────;K
10.15.1 Normal responses
k
TRACE — Hit enter to proceed
l
If the entry being traced generates an output message, this is sent to the terminal and processing stops.
Press Enter to continue. When processing of the current entry is complete, the following message is sent
to the terminal:
k
TRACE — Enter message to be traced
l
Chapter 10. Using the ALCS trace facility
191
HELP
10.16 HELP — Display trace help information
When conversational tracing is active, use the HELP command to display help information about
conversational mode trace commands. The format of the command is:
;;──┬─HELP─┬────────────────────────────────────────────────────────────────────────────;K
└─?────┘
See also -- Heading 'ZHELP' unknown -- for further information on invoking help.
192
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
PROCESS
10.17 PROCESS — Process message
When conversational tracing is active, use the PROCESS command followed by any input message to
process the message (without tracing it) while conversational trace is active. The normal message
response appears on the screen.
The format of the command is:
;;──Process──message────────────────────────────────────────────────────────────────────;K
Where:
message
Any input message.
Note: Some applications use terminal hold (AAA hold) to prevent concurrent processing of different input
messages from the same originator. These applications either discard a second input message that
arrives while the first is being processed, or do not process the second message until the first completes.
Using the PROCESS command with this type of application does not work unless the application contains
special instructions to allow a second input message from a terminal that is being traced. The IPARS –
ALCS application contains an example of this special logic in program UII1.
10.17.1 Normal responses
The response is the normal response generated by the input message.
If the input generates an output message, this is sent to the terminal and processing stops. Press Enter
to continue. When processing of the current entry is complete, the following message is sent to the
terminal:
k
TRACE — Enter message to be traced
l
Chapter 10. Using the ALCS trace facility
193
REFSTOP
10.18 REFSTOP — Reference stop
When conversational tracing is active, use the REFSTOP command to continue processing the entry without
tracing it, ignoring all other trace control options, until the program refers to one of the reference-stop
locations specified in the R= trace control parameter.
The format of the command is:
;;──┬─Refstop─┬─────────────────────────────────────────────────────────────────────────;K
└─REFstop─┘
ALCS trace facility stops before the instruction which refers to the reference stop. Then it sends a display
that is the same as the instruction step display (see 10.22, “STEP — Control instruction stepping” on
page 200). Then ALCS trace facility continues the same as before the REFSTOP command.
It is possible that the entry never reaches a reference-stop location. To guard against this, ALCS trace
facility stops the entry if any of the following occurs before it gets to a reference-stop location:
5
5
5
5
The
The
The
The
entry
entry
entry
entry
exits.
sends a response message to the originating terminal.
executes 10 000 monitor-request macros.
executes 30 000 instructions.
Note: For this purpose, DLAYC and DEFRC count as 100 macros to prevent a long wait before the response
is received.
10.18.1 Normal responses
The same as for instruction step. See 10.22, “STEP — Control instruction stepping” on page 200.
If ALCS trace facility stops the entry before it gets to a reference stop location, one of the following lines
can precede the standard header:
k
k
TRACE — STEP/ADSTOP/REFSTOP/REGSTOP halt after 1 macros
TRACE — STEP/ADSTOP/REFSTOP/REGSTOP halt after 3 instructions
l
l
In either case, you can re-enter REFSTOP to continue searching for the reference stop location.
194
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
REGSTOP
10.19 REGSTOP — Register stop
When conversational tracing is active, use the REGSTOP command to continue processing the entry without
tracing it, ignoring all other trace control options, until the program reaches one of the register-stop
conditions specified in the G= trace control parameter.
The format of the command is:
;;──REGstop─────────────────────────────────────────────────────────────────────────────;K
ALCS trace facility stops after the instruction which modifies the register such that a register-stop condition
is matched. When the trace facility stops it sends a display that is the same as the instruction step display
(see 10.22, “STEP — Control instruction stepping” on page 200). Then ALCS trace continues as before
the REGSTOP command.
It is possible that the entry never reaches a register-stop condition. To guard against this, ALCS trace
facility stops the entry if any of the following occurs before it reaches a register-stop condition.
5
5
5
5
The
The
The
The
entry
entry
entry
entry
exits.
sends a response message to the originating terminal.
executes 10 000 monitor-request macros.
exceeds 30 000 instructions.
Note: For this purpose, DLAYC and DEFRC count as 100 macros to prevent a long wait before the
response is received.
10.19.1 Normal responses
The same as for instruction step. See 10.22, “STEP — Control instruction stepping” on page 200.
If ALCS trace facility stops the entry before it reaches a register-stop condition, one of the following lines
can precede the standard header:
k
k
TRACE — STEP/ADSTOP/REFSTOP/REGSTOP halt after 1 macros
TRACE — STEP/ADSTOP/REFSTOP/REGSTOP halt after 3 instructions
l
l
In either case, you can reenter REGSTOP to continue searching for the register-stop condition.
Chapter 10. Using the ALCS trace facility
195
SET
10.20 SET — Set fields
When conversational tracing is active, use the SET command to set the contents of main storage, registers,
and so on.
The format of the command is:
|
;;──Set,──┬─CC=cc────────────────────────┬──────────────────────────────────────────────;K
│
┌─,─────┐ │
D──hex──┴─┤
├─┬─ecb_label=────┬───
│ ├─AUT,disp=─────┤
│
│ ├─LIST,disp=────┤
│
│ ├─SBx,disp=─────┤
│
│ ├─SB,decb,disp=─┤
│
│ └─MS,address=───┘
│
└─┬─IA=address──┬──────────────┘
├─gpr=address─┤
└─fpr=address─┘
Where:
CC=cc
Set the condition code. cc is the new condition code value: 0, 1, 2, or 3.
ecb_label=hex,...
Store the replacement data hex,... in the ECB at field ecb_label,
ecb_label
hex,...
Name of field in the EBEB DSECT.
One or more strings each of one or more hexadecimal digits. A comma (or space)
separates each string from the next. SET adds leading zeros if necessary so that each
string forms a whole number of bytes. Then it updates the ECB by storing the first
string at ecb_field. It stores the second string (if any) immediately following the first,
and so on.
AUT,disp=hex,...
Store the replacement data hex,... in the automatic storage block at displacement disp, where:
disp
hex,...
Displacement in hexadecimal within the automatic storage block.
One or more strings each of one or more hexadecimal digits. A comma (or space)
separates each string from the next. SET adds leading zeros if necessary so that each
string forms a whole number of bytes. Then it updates the automatic storage block by
storing the first string at displacement disp. It stores the second string (if any)
immediately following the first, and so on.
LIST,disp=hex,...
Store the replacement data hex,... at displacement disp in the program that is currently executing,
where:
disp
hex,...
196
Displacement in program in hexadecimal.
One or more strings each of one or more hexadecimal digits. A comma (or space) separates
each string from the next. SET adds leading zeros if necessary so that each string forms a
whole number of bytes. Then it updates the program by storing the first string at
displacement disp. It stores the second string (if any) immediately following the first, and so
on.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
SET
SET LIST can only modify a program that is loaded for test. See -- Heading 'ZPCTL' unknown -- for a
description of this.
|
SBx,disp=hex,...
Store the replacement data hex,... in the storage block attached at ECB level x at displacement disp,
where:
disp
hex,...
Displacement in hexadecimal within the storage block.
One or more strings each of one or more hexadecimal digits. A comma (or space)
separates each string from the next. SET adds leading zeros if necessary so that each
string forms a whole number of bytes. Then it updates the storage block by storing the
first string at displacement disp. It stores the second string (if any) immediately
following the first, and so on.
| SB,decb,disp=hex,...
|
Store the replacement data hex,... in the storage block attached to the DECB at address decb, where:
|
|
|
|
|
|
disp
hex,...
Displacement in hexadecimal within the storage block.
One or more strings each of one or more hexadecimal digits. A comma (or space)
separates each string from the next. SET adds leading zeros if necessary so that each
string forms a whole number of bytes. Then it updates the storage block by storing the
first string at displacement disp. It stores the second string (if any) immediately
following the first, and so on.
MS,address=hex,...
Store the replacement data hex,... at address in main storage, where:
address
hex,...
Main storage address in any of the formats that SET gpr=address supports.
One or more strings each of one or more hexadecimal digits. A comma (or space)
separates each string from the next. SET adds leading zeros if necessary so that each
string forms a whole number of bytes. Then it updates main storage by storing the first
string at address address. It stores the second string (if any) immediately following the
first, and so on.
SET first evaluates address as a 4-byte (32-bit) number. Then it interprets the 4-byte number as a
24-bit address (that is, it ignores the high-order byte) if the entry is running in 24-bit addressing mode.
It interprets it as a 31-bit address (that is, it ignores the high-order bit) if the entry is running in 31-bit
addressing mode.
IA=address
Set the address of the next sequential instruction (NSI). This is the same as branching to address.
address can be any of the formats that SET gpr=address supports.
SET first evaluates address as a 4-byte (32-bit) number. Then it interprets the 4-byte number as a
24-bit address (that is, it ignores the high-order byte) if the entry is running in 24-bit addressing mode.
It interprets it as a 31-bit address (that is, it ignores the high-order bit) if the entry is running in 31-bit
addressing mode.
You can use SET IA= or BRANCH during macro trace as well as during instruction step. This allows you,
for example, to branch around a monitor-request macro. You can also set the instruction address to
addresses outside the active program — for example, to a subroutine in an ECB work area or in an
attached block.
Chapter 10. Using the ALCS trace facility
197
SET
gpr=address
Set the contents of general register, where:
gpr
address
|
|
|
|
Name of general register, one of:
R0, R00, RG0, or RAC
General register 0
R1, R01, RG1, or RG1
General register 1
R2, R02, RG2, or RGA
General register 2
R3, R03, RG3, or RGB
General register 3
R4, R04, RG4, or RGC
General register 4
R5, R05, RG5, or RGD
General register 5
R6, R06, RG6, or RGE
General register 6
R7, R07, RG7, or RGF
General register 7
R8, R08, RG8, or RAP
General register 8
R14, RG14, or RDA
General register 14
R15, RG15, or RDB
General register 15
Replacement data. A 4-byte value that replaces the previous contents of the general
register. One of:
hex
One to 8 hexadecimal digits. SET adds leading zeros if necessary to
form a 4-byte value.
disp(gpr)
Value formed by adding disp in hexadecimal to the contents of
general register gpr. gpr can be any general register name (see list
above).
disp(gpr1,gpr2)
Displacement (disp) in hexadecimal off the address in general
register gpr2 plus the index value in gpr1. gpr1 and gpr2 can be any
general register names (see list above, with the addition of REB,
general register 9).
disp(SBx)
Value formed by adding disp in hexadecimal to the address of the
storage block attached at ECB level x.
disp(SB,decb)
Value formed by adding disp in hexadecimal to the address of the
storage block attached to the DECB at address decb.
disp(AUT)
Value formed by adding disp in hexadecimal to the address of the
automatic storage block.
LIST,disp
Storage address corresponding to displacement (disp) in
hexadecimal into the application program. Note that this address is
evaluated without regard to the address mode of the program.
fpr=hex
Set the contents of floating-point register, where:
fpr
Name of floating-point register, one of:
FP0
FP2
FP4
FP6
hex
Floating-point
Floating-point
Floating-point
Floating-point
register
register
register
register
0
2
4
6
Replacement data, 1 to 16 hexadecimal digits. SET adds leading zeros if necessary to form an
8-byte value that replaces the previous contents of the floating-point register.
Restrictions
SET MS can only modify main storage that an application program can modify; that is, entry storage and
global area storage.
SET LIST and SET MS,LIST can only modify a program that is loaded for test. -- Heading 'ZPCTL' unknown
-- describes this.
198
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
SKIP
10.21 SKIP — Skip next instruction or macro
When conversational tracing is active, use the SKIP command to skip (branch past) the next instruction or
macro.
The format of the command is:
;;──SKip────────────────────────────────────────────────────────────────────────────────;K
Notes:
1. When instruction stepping is active, ALCS trace facility stops twice for each monitor-request macro. It
first sends the display for the BRANCH SAVE AND SET MODE (BASSM) instruction that links to the
ALCS monitor. Do not enter SKIP at this time. (This is because SKIP branches past the BASSM
instruction to constants that are part of the macro expansion. These constants are called macro
parameters.) Instead, press Enter; ALCS trace facility then sends the display for the monitor-request
macro. Now enter SKIP to skip the monitor-request macro.
2. Some monitor-request macros generate executable instructions before the BASSM and some generate
executable instructions after the macro parameters. For example, FINWC generates a conditional
branch following the macro parameters. When the trace display shows FINWC, then SKIP branches to
the conditional branch instruction within the macro expansion, not to the next instruction following the
macro.
10.21.1 Normal response
The same as for instruction step. See 10.22, “STEP — Control instruction stepping” on page 200.
Chapter 10. Using the ALCS trace facility
199
STEP
10.22 STEP — Control instruction stepping
When conversational tracing is active, use the STEP command to turn on (start) or turn off (stop) instruction
stepping. During instruction stepping, ALCS trace facility stops at each instruction (as well as at each
monitor-request macro).
The format of the command is:
;;──STep──┬─ON──┬───────────────────────────────────────────────────────────────────────;K
└─OFF─┘
Where:
ON
Turn on (start) instruction stepping.
OFF
Turn off (stop) instruction stepping.
The ALCS trace facility also supports the old ISTEP and UNSTEP commands for the benefit of users who are
familiar with these commands. ISTEP is a synonym for STEP ON. UNSTEP is a synonym for STEP OFF.
It is possible that during instruction stepping the entry may enter a program which is not being traced and
get into a loop in that untraced program. To guard against this, ALCS trace facility stops the entry if any
of the following occurs before it returns to a traced program:
5
5
5
5
The
The
The
The
entry
entry
entry
entry
exits.
sends a response message to the originating terminal.
executes 10 000 monitor-request macros.
executes 30 000 instructions.
Note: For this purpose, DLAYC and DEFRC count as 100 macros to prevent a long wait before the response
is received.
10.22.1 Restriction
When tracing assembler library routines called by C applications, be aware that instruction stepping is
disrupted when execution switches back to the C environment. Set STEP OFF before executing any
instruction that modifies an ALCS reserved register.
10.22.2 Normal responses
k
TRACE — Hit enter to proceed
l
For STEP OFF, press Enter to execute the macro or instruction. ALCS trace facility then proceeds to the
next monitor-request macro. Trace is no longer instruction stepping.
For STEP ON, press Enter to execute the macro. ALCS trace facility then proceeds to the next instruction
(the instruction that follows the monitor-request macro). ALCS trace facility then displays a message that
begins with a standard header.
Depending on the display (D=) trace control option, more information can follow the standard header.
200
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
STEP
Following the normal response, press Enter to execute the instruction. ALCS trace facility executes the
instruction and then displays information about the next instruction. Press Enter again to execute that
instruction, and so on. Optionally, enter any trace control command or ALCS command before pressing
Enter.
Standard header:
k
TRACE — address
opcode
operand
contents1
l
contents2
Where:
address
Location of the instruction. If this is within an application program, then it appears as the
program name followed by the hexadecimal displacement (listing address). If not (for example,
if it is in the ECB) it appears as the 8-digit hexadecimal storage address.
opcode
Symbolic operation code of the instruction. See ESA/390 Principles of Operation for details. If
ALCS trace facility cannot recognize the instruction operation code, then the header includes
the whole instruction in hexadecimal notation instead of the symbolic operation code and
operand field.
operand
Operand field of the instruction. All terms in the operand field appear in hexadecimal. For
example:
MVC
18(2,9),6(5)
shows a move to displacement hexadecimal 18 (decimal 24) from the address in general
register 9 (REB).
contents
The contents or values of the operands, in hexadecimal, displayed as 2 fields of up to 8 bytes
each. If the operand is a register, the display shows the contents of the register; if the operand
is a storage location, the display shows the storage contents; if the operand is an address, the
display shows the value at the address.
If the contents are more than 8 bytes, the last hexadecimal digit is replaced by 2 periods (..) to
show that the displayed contents are not complete. If the storage location is not accessible,
the display shows question marks (??).
Not all operation codes include a display of contents.
Branch instructions: If ALCS trace facility recognizes the instruction as a branch, it checks to see if the
branch is taken. One of the following standard headers is displayed:
If the branch is taken:
k
TRACE — address
operation
operand
—> destination
operand
destination
l
If the branch is not taken:
k
TRACE — address
operation
l
Where:
destination
The instruction branches to this location, or would if the branch was taken.
Chapter 10. Using the ALCS trace facility
201
STEP
When ALCS trace facility stops at a monitor-request macro while instruction stepping is active, it first
sends the display for the BRANCH SAVE AND SET MODE (BASSM) instruction that links to the ALCS monitor.
After pressing Enter, ALCS trace facility then sends the display for the monitor-request macro. Note that
even during instruction stepping, ALCS trace facility does not trace the instructions in the ALCS monitor.
If ALCS trace facility stops the entry before it returns to a traced program, one of the following lines can
precede the standard header:
k
k
TRACE — STEP/ADSTOP/REFSTOP/REGSTOP halt after 1 macros
TRACE — STEP/ADSTOP/REFSTOP/REGSTOP halt after 3 instructions
In either case, you can press Enter to continue instruction stepping.
202
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
l
l
SWAP
10.23 SWAP — Swap current entry
When more than one entry (ECB) is processing a traced input message, use the SWAP command, to swap
from tracing one entry to another.
The format of the command is:
;;──SWap────────────────────────────────────────────────────────────────────────────────;K
Initially only one entry processes an input message. However, that entry can create other entries. The
original entry and the created entries are all processing the same input message.
Conversational trace can trace only one entry at a time. It keeps all the entries that are processing the
input message in a stack, with the entry that it is tracing at the top of the stack. If that entry creates
another entry, the ALCS trace facility adds the new entry to the bottom of the stack.
SWAP moves the current entry to the bottom of the stack and makes the second entry in the stack the
current entry. If there are many entries in the stack, SWAP can be entered repeatedly to make any entry
the current entry. This command has no effect when there is only one entry processing the message.
Restrictions
SWAP is not allowed when the entry being traced (the entry at the top of the stack):
5 Holds records (for example by FIWHC macro).
5 Holds resources (for example by CORHC or ENQC macro), or
5 Assigns sequential files (by TOPNC or TASNC macro).
Chapter 10. Using the ALCS trace facility
203
MVS diagnostic facilities
Chapter 11. Maintaining ALCS
In many cases, the system programmers in an ALCS installation will determine and fix any problems that
arise by means of the facilities provided by MVS and subsystems such as VTAM, using the appropriate
MVS and subsystem manuals.
The Network Program Products: General Information Manual provides a summary of network problem
determination facilities for standard programs such as VTAM, Network Control Program, and NetView.
Specialized programs such as NPSI, NTO, NEF, and ALCI all have their own problem determination
processes, which are documented in their program libraries.
This section describes some aspects of maintaining ALCS, including:
5 Fixing system problems
5 Tuning ALCS
11.1 MVS diagnostic facilities
This section contains descriptions of the following:
5 Generalized trace facility (GTF)
5 MVS dumps
5 SLIP command
5 Interactive problem control system (IPCS)
11.1.1 Generalized trace facility (GTF)
The generalized trace facility is a service aid program that is available for determining and diagnosing
system problems. GTF records system and user-defined program events. Through GTF you can trace:
5 Any combination of system events, such as all I/O interruptions and all SVC interruptions.
5 Specific incidences of one type of system event, such as all I/O to a particular device.
5 User-defined events that are generated by the GTRACE macro. ALCS uses GTRACE to record the
beginning and completion of VTAM operations. VTAM uses GTRACE for terminal buffer tracing.
GTF produces output trace records either to buffers in virtual storage or to a data set.
You should use GTF for tracing events that cannot be recorded by ALCS problem determination facilities.
For example, use GTF to obtain a buffer trace of VTAM I/O to a terminal, or for VTAM request parameter
lists (RPLs) used by ALCS.
204
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
MVS diagnostic facilities
The following example shows how to start GTF to record VTAM RPLs used by ALCS. See the MVS/ESA
Service Aids manual for detailed information on how to use GTF, and for an explanation of the user
options shown in the example.
User:
System:
User:
System:
User:
System:
User:
System:
User:
System:
s gtf.gtf
$HASP1 GTF
ON STCINRDR
$HASP373 GTF
STARTED
TRACE=RNIO,USR,SLIP
AHL121I SYS1.PARMLIB INPUT INDICATED
AHL13I TRACE OPTIONS SELECTED --USR,RNIO,SLIP
V28 AHL125A RESPECIFY TRACE OPTIONS OR REPLY U
28trace=usr,jobnamep
IEE6I REPLY TO 28 IS;TRACE=USR,JOBNAMEP
V29 AHL11A SPECIFY TRACE EVENT KEYWORDS --JOBNAME=
29jobname=alcsrun
IEE6I REPLY TO 29 IS;JOBNAME=ALCSRUN
V3 AHL12A CONTINUE TRACE DEFINITION OR REPLY END
3end
IEE6I REPLY TO 3 IS;END
AHL13I TRACE OPTIONS SELECTED --USR
AHL13I JOBNAME=(ALCSRUN)
V31 AHL125A RESPECIFY TRACE OPTIONS OR REPLY U
31u
IEE6I REPLY TO 31 IS;U
AHL31I GTF INITIALIZATION COMPLETE
To stop GTF:
User:
System:
P gtf
$HASP395 GTF
ENDED
AHL6I GTF ACKNOWLEDGES STOP COMMAND
After stopping GTF, use IPCS to format, display, and print the GTF output. See 11.1.4, “Interactive
problem control system (IPCS)” on page 208.
11.1.2 MVS dumps
Use MVS dump services when you need information that is not dumped by ALCS (for example, the ALCS
communication table).
MVS produces four types of dumps:
1. SYSUDUMP is a dump of user areas. It is formatted, so it can be printed directly. MVS produces this
dump when a job abends and there is a SYSUDUMP DD statement in the JCL.
2. SYSABEND is a dump of user and system areas. It is formatted, so it can be printed directly. MVS
produces this dump when a job abends and there is a SYSABEND DD statement in the JCL.
3. SYSMDUMP is an unformatted dump of user and system areas. MVS produces this dump when a job
abends and there is a SYSMDUMP DD statement in the JCL. You must use IPCS to format, print or
display SYSMDUMP dumps (see 11.1.4, “Interactive problem control system (IPCS)” on page 208).
4. SVC dump is an unformatted dump of user and system areas. You do not need to supply a DD card
to point to the dump data set, as MVS uses pre-allocated dump data sets with a data set name of
SYS1.DUMPxx, where xx is a 2-digit decimal number ranging from 00 to an installation specified
Chapter 11. Maintaining ALCS
205
MVS diagnostic facilities
maximum. You must use IPCS to format, print or display SVC dumps (see 11.1.4, “Interactive
problem control system (IPCS)” on page 208).
You can take an SVC dump of the ALCS address space by using the DUMP MVS system command
(see the example below). You can also direct MVS to take an SVC dump when ALCS abends by
setting a SLIP trap (see 11.1.3, “SLIP command”). If dump speed is important to your installation, you
should use SVC dumps, as they are faster than the other types of dump.
For detailed information on the different types of dumps and their contents, see the appropriate MVS/ESA
Initialization and Tuning manual.
The following example shows how you can take an SVC dump of the ALCS address space. See MVS
System Commands manual for a description of the commands used.
User:
System:
User:
System:
User:
System:
User:
System:
d d,t
IEE853I 15.41.1 SYS1.DUMP TITLES 812
SYS1.DUMP DATA SETS AVAILABLE=1 AND FULL=
NO DUMP DATA AVAILABLE FOR THE FOLLOWING EMPTY SYS1.DUMP DATA SETS:
-9
DUMP COMM=(ALCS TEST SYSTEM)
V12 IEE94D SPECIFY OPERAND(S) FOR DUMP COMMAND
12jobname=ialegr1,sdata=(nosqa),end
IEE6I REPLY TO 12 IS;JOBNAME=IALEGR1,SDATA=(NOSQA),END
VIEA911E COMPLETE DUMP ON SYS1.DUMP 169
FOR ASID (1D)
d d,t
IEF196I IEF237I 424 ALLOCATED TO SYS25
IEF196I IEF285I
SYS1.DUMP
KEPT
IEF196I IEF285I
VOL SER NOS= IASC2.
IEE853I 15.58.11 SYS1.DUMP TITLES 384
SYS1.DUMP DATA SETS AVAILABLE=9 AND FULL=1
DUMP TITLE=ALCS TEST SYSTEM
DUMP TAKEN TIME=15.5.9 DATE=12/1/9
NO DUMP DATA AVAILABLE FOR THE FOLLOWING EMPTY SYS1.DUMP DATA SETS:
1-9
11.1.3 SLIP command
The SLIP command controls serviceability level indication processing (SLIP), a diagnostic aid designed to
intercept or trap certain system events. You can indicate what kinds of event you want trapped and what
the system is to do when these events occur.
The following is an example of the kinds of events you can intercept. For a detailed description, see the
MVS/ESA System Commands Manual.
5 Instruction fetch program event recording (PER) interruption. Use this event to trace the execution of
instructions when ALCS trace does not apply. For example, you can trace the execution of a monitor
installation-wide exit (see the example below).
5 Storage alteration PER interruption. Use this event to produce an SVC dump or a trace to identify
sources of storage damage. For example, you can identify application programs that damage the
application global area.
5 Abend. Use this event to take SVC dumps, or inhibit dumping, for certain ALCS abend codes. See
the example below.
206
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
MVS diagnostic facilities
An event defined by the SLIP command is usually called a SLIP trap.
SVC dumps are written to SYS1.DUMPxx.
Examples of using SLIP
To produce an SVC dump when ALCS abends, use the commands:
SLIP SET,ID=AL1,J=jobname,C=Uxxxx,A=SVCD,AL=CU,ML=9999,END
SLIP SET,ID=AL2,J=jobname,C=S122,A=SVCD,AL=CU,ML=9999,END
Where:
ID=AL1
Assigns a unique 4-character ID to this trap.
J=jobname
This trap applies to job or started task jobname. Specify the ALCS job name here.
C=Uxxxx
User completion code. The trap is activated when there is an abend with any user
completion code. C=XXXX activates traps for all user abends. However you can be more
specific, for example: C=U42 activates the trap for a User 42 abend only.
C=S122
System completion code. The trap is activated when the operator cancels ALCS with dump.
A=SVCD
Directs SLIP to take an SVC dump when the trap is activated. (Not included in the
command as SVCD is the default action.)
AL=CU
Address space list. Dump the current address space only.
ML=9999
Match limit. Number of times the trap occurs before it is disabled. This is used to limit the
number of dumps. For example, to take only one dump of abend U795, specify
C=U795,ML=1 (ML=1 is the default.)
To inhibit an SVC dump when an abend SD6 occurs, use:
SLIP SET,ID=XD6,C=SD6,A=NODUMP,END
Where:
C=SD6
System completion code.
A=NODUMP
Directs SLIP to inhibit dumps when a D6 abend occurs.
To trace instruction execution in a monitor installation-wide exit, set the following trap:
SLIP SET,IF,ID=USVC,J=jobname,
RA=(start,end),
A=TRACE,TRDATA=(STD,REGS),
ML=5,PL=5,END
Where:
IF
Trap type is instruction fetch
ID=USVC
Trap identification
J=jobname
ALCS job name
RA=(start,end)
Range of addresses to trace. Whenever the processor executes instructions in
this range, a SLIP trap occurs.
A=TRACE
Action is trace. When the trap takes place, SLIP writes a GTF trace record.
(Remember to start GTF).
Chapter 11. Maintaining ALCS
207
MVS diagnostic facilities
TRDATA=(STD,REGS)
Trace the standard information plus the contents of the general registers.
ML=5
Disable the trap after 5000 instructions.
PL=5
Disable the trap if processing takes more than 50% processor utilization.
To find out who is storing X'00000000' at address X'0250A080', use:
SLIP SET,SA,ID=GBL1,J=jobname,
RA=(25A8,25A83),DATA=(25A8,EQ,),
A=TRACE,TRDATA=(STD,REGS),
ML=5,PL=5,END
Where:
SA
Trap type is storage alteration.
RA=(...)
Range of addresses to trace. When storage is altered in that range, a SLIP trap occurs.
DATA=(...)
You can use this operand to distinguish between “good” and “bad” alterations. SLIP
ignores alterations that do not match the DATA conditions (in this case, that the storage
contents are X'00000000'). This operand is optional.
To check whether the dump data sets are empty use the display command:
D D,T
Where:
D D,T
Display dump titles. Display the titles of dumps in the SYS1.DUMPxx data sets.
To clear dump data sets, use the DUMPDS commands as follows:
DD CLEAR,DSN=
Clears SYS1.DUMP00
DD CLEAR, DSN=(–9) Clears SYS1.DUMP00 through SYS1.DUMP09
DD CLEAR,DSN=ALL
Clears all dump data sets
Note: These examples work only for ALCS user abends. If you enter
CANCEL alcsjob,DUMP
no dump is produced, as the AL01 trap is not activated by a system-122 abend. Enter the following SLIP
command to set a trap for S122 abends:
SLIP SET,ID=AL2,J=jobname,C=122,AL=CU,ML=9999,END
or
SLIP SET,ID=AL2,JSPGM=DXCMON,C=122,AL=CU,ML=9999,END
11.1.4 Interactive problem control system (IPCS)
IPCS provides installations with an interactive facility for diagnosing software failures. IPCS formats and
analyzes unformatted dumps and GTF traces to produce reports that you can either view at the terminal or
print.
For information on how to use IPCS, see the appropriate Interactive Problem Control System Guide. or
the appropriate MVS manual.
208
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: Recoup
11.2 Problem determination in ALCS
This section contains the following subsections:
5
5
5
5
5
5
5
5
Recoup and pool error information
System error dumps
Format of system error dumps
Program driver
SLC link trace facility
TCP/IP trace facility
ALCS test facilities
Information and error messages
11.2.1 Recoup and pool error information
Recoup (see -- Heading 'RUNRCP' unknown --) detects errors in long-term pool file records. These errors
are called pool chain errors.
While Recoup is running, ALCS records information about Recoup progress on the ALCS diagnostic file.
When an application program gets, reads, writes, or releases a pool file record, ALCS checks the pool
control information that the record contains. In this way, ALCS detects errors such as:
5 A record which is read or written after release.
5 A record which is released more than once.
5 Missing release for a record (lost address).
These are called pool usage errors.
When the ALCS monitor detects a pool usage error, it records information about the error on the ALCS
diagnostic file.
As with pool usage errors, ALCS records information about pool chain errors on the ALCS diagnostic file.
These include:
5 Excessively long chains
5 Looping chains
5 Multiple references to the same chain — except where allowed
When application programs use the ALCS release chain service, ALCS can detect errors in the chain of
records. ALCS records information about these errors on the ALCS diagnostic file.
The ALCS diagnostic file processor formats and prints information about Recoup progress, pool usage
errors, pool chain errors and release chain errors.
Recoup progress
During Recoup, ALCS writes Recoup progress information to the ALCS diagnostic file. The ALCS
diagnostic file processor prints this information as follows:
Chapter 11. Maintaining ALCS
209
Problem determination: Recoup
hh.mm.ss RECOUP DXC844I CMD i time_stamp RECP
group_details
This prime group group_read_counts
This recoup
recoup_read_counts
Errors
error_counts
Where:
hh.mm.ss
Time-of-day (TOD) clock time. This is the MVS local time.
i
ALCS system identifier.
time_stamp
ALCS time stamp. This is the ALCS local time.
group_details
Identifies the Recoup group:
5 Recoup descriptor=program_name
Program name of the Recoup descriptor program.
5 Group=group_name
Group name.
group_read_counts
Record read counters for this Recoup prime group:
5 total reads...count
Total number of records, fixed file, pool file, and general file.
5 pool reads...count
Number of pool file records.
recoup_read_counts
Record read counters for this Recoup:
5 total reads...count
Total number of records, fixed file, pool file, and general file.
5 pool reads...count
Number of pool file records.
error_counts
Error counters for this Recoup:
5 I/O...count
Total number of I/O errors.
5 ID...count
Total number of record ID compare errors (ID checks).
5 RCC...count
Total number of RCC compare errors (RCC checks).
5 F/A...count
Total number of file address errors (invalid F/A).
5 control-field...count
Total number of control field errors.
210
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: Pool usage errors
A possible (self-explanatory) error message is:
DXC8387I CMD i time_stamp RECP
Missing descriptor program – Recoup continues
MISSING DESCRIPTOR PROGRAM program
hh.mm.ss RECOUP
11.2.2 Pool usage errors
For each pool usage error, the ALCS diagnostic file processor prints the following:
hh.mm.ss POOL RECORD USAGE ERROR -- error_description
event_information
DISPENSE FOR
LAST WRITE FOR
CHAIN-CHASE FOR
RELEASE FOR
START TIME LAST
nnnn
nnnn
nnnn
nnnn
RECP
yyyy.ddd
yyyy.ddd
yyyy.ddd
yyyy.ddd
yyyy.ddd
hh.mm.ss
hh.mm.ss
hh.mm.ss
hh.mm.ss
hh.mm.ss
Where:
hh.mm.ss
Time-of-day (TOD) clock time of the error.
error_description
Type of error.
The error_description for each type are described in:
5 “Long-term pool errors”
5 “Short-term pool errors” on page 213
nnnn
The name of the application program or (for chain-chase) of the Recoup descriptor program.
yyyy.ddd hh.mm.ss
Julian date and time of the activity, using the time-of-day (TOD) clock time.
Long-term pool errors
5 RELEASE OF UNDISPENSED RECORD
The application program released a long-term pool file record that was never dispensed. ALCS sets
this record as dispensed and released.
5 MULTIPLE RELEASE OF RECORD
The application program released a long-term pool file record that was already released. Note that
either this release, or the previous release, can be in error. ALCS ignores this release.
5 RELEASE OF LOST ADDRESS
The application program released a long-term pool file record that was a lost address. A long-term
pool file record becomes a lost address after the following sequence of events:
1. An application program gets (dispenses) the record.
2. No application program releases the record.
3. Recoup does not find the record.
This can be due to an error or omission in the Recoup descriptors. ALCS processes this release
normally.
Chapter 11. Maintaining ALCS
211
Problem determination: Pool usage errors
5 LOST ADDRESS FOUND BY DISPENSE ROUTINE
ALCS attempted to dispense a long-term pool file record that was a lost address. This can be due to
an error or omission in the Recoup descriptors. ALCS releases the record; it does not dispense the
record, unless the long-term pool dispense installation-wide exit routine alters the standard ALCS
options.
5 SYSTEM DISPENSE OF RECORD ON WRITING
The application program wrote a long-term pool file record that was never dispensed. ALCS
dispenses the record.
5 SYSTEM SHIFT RELEASE OF RECORD ON WRITING
The application program wrote a long-term pool file record that was already released. Note that either
this write, or the previous release, can be in error. ALCS shifts the release time; that is, it resets the
release time for the record to the time of the write.
5 WRITE OF LOST ADDRESS RECORD
The application program wrote a long-term pool file record that was a lost address. This can be due
to an error or omission in the Recoup descriptors. ALCS writes the record in the normal way.
5 READ OF UNDISPENSED RECORD
The application program read a long-term pool file record that was never dispensed. ALCS reads the
record in the normal way.
5 SYSTEM DISPENSE OF RECORD ON READING DURING RECOUP
Recoup read a long-term pool file record that was never dispensed. ALCS dispenses the record.
5 READ OF PREVIOUSLY RELEASED RECORD
The application program read a long-term pool file record that was already released. ALCS reads the
record in the normal way.
5 READ OF ERRONEOUSLY AVAILABLE RECORD DURING RECOUP
Recoup read a long-term pool file record that was already released. ALCS clears the release time for
the record.
5 READ OF LOST ADDRESS RECORD
The application program read a long-term pool file record that was a lost address. This can be due to
an error or omission in the Recoup descriptors. ALCS reads the record in the normal way.
5 READ OF LOST ADDRESS RECORD DURING RECOUP
Recoup read a long-term pool file record that was a lost address. This can be due to an error or
omission in the Recoup descriptors. The record is no longer a lost address.
5 AMBIGUOUS RECORD ID REQUESTED
The application program attempted to get (dispense) a long-term pool file record, but the record ID is
ambiguous (duplicate). The application program specifies a record ID that is defined for more than
one pool file type. But the application does not specify enough information (long- or short-term, size,
or qualifier) to identify the type that it requires.
5 UNDEFINED RECORD ID REQUESTED
The application program attempted to get (dispense) a long-term pool file record, but either:
– The record ID is undefined in the ALCS generation. The application program specifies a record ID
that is not defined.
– The record ID is undefined for the pool type. The application program specifies a record ID
together with long- or short-term, or size information. But the record ID is not defined for any pool
type that satisfies the request.
5 INVALID FILE ADDRESS ON RELEASE RING
The application program released a valid file address but there is no corresponding record on the
database, so no record can be released.
212
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: Pool usage errors
5 CLASS MISMATCH FOR LT POOL RELEASE
The application program released a valid file address but the record to which it refers was filed using a
different file address, that is using a different record class. A record can only be released if the file
address that has been used in the release macro is the same address that was used to file the record.
Short-term pool errors
5 WRITE OF TIMED OUT ST POOL RECORD
The application program wrote a short-term pool record that was timed out.
5 WRITE OF UNDISPENSED ST POOL RECORD
The application wrote a short-term pool record that was never dispensed.
5 WRITE OF PREVIOUSLY RELEASED ST POOL RECORD
The application wrote a short-term pool record that was previously released.
5 DISPENSE OF TIMED OUT ST POOL RECORD
ALCS dispensed a short-term pool record that was a lost address.
5 RELEASE OF TIMED OUT ST POOL RECORD
The application program released a short-term pool record that was timed out. ALCS ignores this
release.
5 RELEASE OF UNDISPENSED ST POOL RECORD
The application program released a short-term pool record that was never dispensed. ALCS ignores
this release.
5 MULTIPLE RELEASE OF ST POOL RECORD
The application program released a short-term pool record that was already released. Note that either
this release or the previous release can be in error. ALCS ignores this release.
5 READ OF TIMED OUT ST POOL RECORD
The application program read a short-term pool record that had been timed out. ALCS reads the
record in the usual way.
5 READ OF UNDISPENSED ST POOL RECORD
The application program read a short-term pool record that was never dispensed. ALCS reads the
record in the usual way.
5 READ OF PREVIOUSLY RELEASED ST POOL RECORD
The application program read a short-term pool record that was already released. ALCS reads the
record in the normal way.
event_information
Information about the event (the monitor-request macro that the application program issued) when
ALCS detected the error. This information includes the following:
5 F/A=file_address
File address of the record, 8 hexadecimal digits.
5 PROGRAM=program_name
The name of the application program that issued the monitor-request macro.
5 OFFSET=macro_offset
The offset of the monitor-request macro in the application program.
5 MACRO=macro_name
The name of the monitor-request macro.
5 ID=record_id
Record ID of the record, 2 characters or 4 hexadecimal digits. For write operations, this is the
record ID before the write.
Chapter 11. Maintaining ALCS
213
Problem determination: Pool chain errors
5 RCC=record_code_check
Record code check of the record, 2 hexadecimal digits. For write operations, this is the record
code check before the write.
5 NEW-ID=record_id
For write operations, the record ID after the write.
5 NEW-RCC=record_code_check
For write operations, the record code check after the write.
When short-term file pool event logging is enabled, the most recent event details for the record are
included as follows:
yyyy.ddd
yyyy.ddd
yyyy.ddd
yyyy.ddd
hh.mm.ss
hh.mm.ss
hh.mm.ss
hh.mm.ss
F/A=file_address
F/A=file_address
F/A=file_address
F/A=file_address
Dispensed by ...prog
Filed by ..........prog
Found by ....prog
Released by ....prog
This information can be useful for analyzing errors in short-term pool handling.
Fixed-file usage errors
For each fixed-file usage error, the ALCS diagnostic file processor prints the following:
hh.mm.ss FIXED FILE RECORD USAGE ERROR -- error_description
event_information
5 ACCESS OF DELETED RECORD
The application program read or wrote a fixed-file record, which had previously been marked as
deleted by loading a new DASD configuration. The access is a normal access to the application
program. However once the deleted records are purged the application will receive an invalid file
address return.
The event_information is similar to that described in “Short-term pool errors” on page 213.
Pool chain errors
Pool chain errors are normally detected by Recoup (see -- Heading 'RUNRCP' unknown --).
Pool chain errors can show that data is lost or damaged, but it is not possible to correct the errors
automatically. Be sure to investigate and correct them as soon as possible, using, for example, the ZGAFA,
ZDFIL, and ZAFIL commands. These are described in:
-- Heading 'ZGAFA' unknown --.
-- Heading 'ZDFIL' unknown --.
-- Heading 'ZAFIL' unknown --.
For each pool chain error, the ALCS diagnostic file processor prints:
hh.mm.ss POOL CHAIN ERROR -- error_description
CHAIN-FROM record_details CHAIN-TO record_details
or, if the error occurs for a record in a prime group, the ALCS diagnostic file processor prints:
hh.mm.ss RECORD READ ERROR -- error_description
prime_group_record_details
Where:
214
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: Pool chain errors
hh.mm.ss
Time-of-day (TOD) clock time when Recoup detects the error.
error_description
Type of error, one of:
5 INVALID F/A
Recoup cannot read the chain-to record because the file address is invalid.
5 I/O ERROR
Recoup cannot read the chain-to or prime group record because of an I/O error.
5 CONTROL ERROR
Recoup cannot read the chain-to record because:
– There is an error in the Recoup descriptor, or
– There are fields in the record that show where (in the record) there is a file address. The field
contents are invalid, so Recoup cannot locate the file address.
5 ID CHECK — ID IS record_id
The record ID in the chain-to or prime group record is not the expected record ID. record_id is
the record ID in the chain-to or prime group record; 2 characters or 4 hexadecimal digits.
5 RCC CHECK — RCC IS record_code_check
The RCC in the chain-to or prime group record is not the expected RCC.
record-code-check is the record code check in the chain-to or prime group record; 2 hexadecimal
digits.
CHAIN-FROM record_details
Information about the chain-from record:
5 F/A=file_address
File address of the chain-from record, 8 hexadecimal digits.
5 ID=record_id
Record ID of the chain-from record, 2 characters or 4 hexadecimal digits.
5 RCC=record_code_check
RCC of the chain-from record, 2 hexadecimal digits.
5 CTL=control_byte
Control byte of the chain-from record, 2 hexadecimal digits. The control byte is byte 3 of the
record; that is, the byte that follows the record code check.
CHAIN-TOrecord_details or prime_group_record_details
Information about the chain-to or prime group record:
5 F/A=file_address
File address of the chain-to or prime group record; 8 hexadecimal digits.
5 EXPECTED-ID=record_id
Expected record ID of the chain-to or prime group record; 2 characters or 4 hexadecimal digits.
5 EXPECTED-RCC=record_code_check
Expected RCC of the chain-to or prime group record; 2 hexadecimal digits.
5 CTL=control_byte
Control byte of the chain-to or prime group record; 2 hexadecimal digits.
Chapter 11. Maintaining ALCS
215
Problem determination: Release chain pool errors
Release chain pool errors
When an application issues the RLCHA monitor-request macro, the program ALCS releases a chain of
records. In the process of releasing the records, ALCS checks for various errors in the chain of records.
If an error is found, information about the error is written to the diagnostic file and no further records are
released. The ALCS diagnostic file processor formats and prints the information recorded on the
diagnostic file for these errors.
For each error detected, the ALCS diagnostic file processor prints:
hh.mm.ss.RLCH ff message FAE-fae HOC-hoc
PIC-pic ID-id RCC-rcc PROG-program
Where:
message
The type of error. This is one of the following:
5 INVALID MESSAGE NUMBER
This error should not occur; if it does, inform your IBM programming support representative.
5 INVALID FILE ADDRESS
The file address fae is invalid.
5 RELEASE OF A NON-POOL TYPE RECORD
The file address fae is not the file address of a long- or short-term pool file record.
5 RELEASE OF A NON-DISPENSED LT RECORD
The file address fae is the file address of a long-term pool file record, but this pool file record has
not been dispensed.
5 RELEASE OF A RELEASED LT RECORD
The file address fae is the file address of a long-term pool file record that has already been
released.
5 LT RECORD CHAINED FROM A ST RECORD
The file address fae is the file address of a long-term pool file record that is chained from a
short-term pool file record whose file address is pic. As short-term pool file records have a life of
only minutes at the most, this type of chaining is considered to be an error.
5 CIRCULAR CHAIN IN ST CHAIN
The file address fae is the file address of a short-term pool file record whose forward chain
contains the file address of a short-term pool file record that has been released earlier in the
chain.
5 TOO MANY ST RECORDS IN CHAIN
There are more than 255 records in a chain of short-term pool file records.
5 ID COMPARE CHECK
The record whose file address is fae has a record ID that is different from the record ID passed in
the RLCHA parameter list.
5 RCC COMPARE CHECK
The record whose file address is fae has an RCC that is different from the RCC passed to the
RLCHA parameter list.
FAE-fae
File address in error. File address of the record at which the error was detected. It is 8 hexadecimal
digits.
216
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
HOC-hoc
Head of chain. File address of the first record in the chain. It is 8 hexadecimal digits.
PIC-pic
Previous in chain. File address of the record previous to the record at which the error was detected.
It is 8 hexadecimal digits. If the record in error is the first record in the chain, this contains '********'.
ID-id
The record ID in the RLCHA parameter list. It is either 2 alphanumeric characters or 4 hexadecimal
characters.
RCC-rcc
The RCC field in the RLCHA parameter list. It is 2 hexadecimal characters.
PROG-program
The name of the program which issued the RLCHA monitor-request macro.
11.2.3 System error dumps
ALCS produces system error dumps to help with problem determination. ALCS does not print system
error dumps. Instead, it writes each dump to the ALCS diagnostic file. Use the ALCS diagnostic file
processor to print the dump. See -- Heading 'RUNDIAG' unknown -- for further information.
ALCS normally (but not always) produces a system error dump when one of the following occurs:
Control error
The online monitor program detects an error condition that requires analysis. The dump is called a
control (CTL) dump.
Operational error
An application program detects an error condition that requires analysis; the application issues SYSRA,
SERRC, or SNAPC to request a system error dump. The dump is called an operational (OPR) dump.
Manual dump
The ZDUMP command, described in -- Heading 'ZDUMP' unknown --, requests a system error dump.
The dump is called a manual dump. It is a type of control dump.
Dump sequence number and system error number
Each system error dump has a dump sequence number and a system error code.
The dump sequence number is a 6-digit decimal number that increases by 1 for each dump.
The system error code is a 6-digit hexadecimal number that indicates the type of error condition. System
error codes that start with 000 are reserved for ALCS to use. The ALCS Messages and Codes lists them.
Application programs can use other system error codes.
System error message
When ALCS produces a system error dump, it normally (but not always) prints a message at RO CRAS.
This is called the system error dump message, or the system error message. It includes the dump
sequence number and the system error code. It also identifies the first ALCS diagnostic file that contains
the system error dump.
Chapter 11. Maintaining ALCS
217
Problem determination: System error dumps
System error options
ALCS supports user-specified options that specify, for example:
5 Whether or not ALCS produces a system error dump in certain situations.
5 What storage areas ALCS includes in system error dumps.
5 Whether or not ALCS prints a system error message.
These are called the system error options.
Specify system error options as ALCS generation parameters (see ALCS Installation and Customization
for an explanation of the SCTGEN macro). Use the ALCS commands ZDSER to display and ZASER to alter the
system error options. This is described in -- Heading 'ZDSER' unknown --.
Regardless of the setting of the system error options:
5 ALCS suppresses or truncates system error dumps if the ALCS diagnostic file is not available.
5 ALCS can suppress the system error message if the ALCS load is too high.
Catastrophic system errors
In most cases, ALCS continues processing after it produces a system error dump. Depending on the type
of error, ALCS sometimes cancels (exits) the entry that is active when the error occurs. However, some
errors are so severe that ALCS cannot continue. In this case, ALCS abnormally terminates (abends).
These are called catastrophic system errors.
If a catastrophic system error occurs, ALCS attempts to produce a system error dump. Whether or not it
is able to produce a system error dump, ALCS then abnormally terminates. If the ALCS job or procedure
includes a suitable data definition (DD) job control statement, MVS produces an abend dump. -- Heading
'INIT' unknown -- describes how to run the ALCS monitor.
11.2.4 Format of system error dumps
This section describes the format of ALCS system error dumps. The ALCS diagnostic file processor prints
system error dumps in several sections. These sections are described below. However, the ALCS
diagnostic file processor does not always print all the sections. The sections that it prints depend on, for
example:
5 The type of error. For example, control dumps can contain different information from operational
dumps. Usually they contain more information.
5 Conditions at the time ALCS detects the error. For example, if there is an active entry when ALCS
detects the error, the dump includes information about the active entry (the contents of the ECB and
so on). If there is no active entry, the dump does not include this information.
5 System error options in force at the time ALCS detects the error. These depend on the ALCS
generation (see ALCS Installation and Customization). The ZASER command, described in -- Heading
'ZASER' unknown --, can change the system error options.
5 ALCS diagnostic file processor control statements. These control statements can request that the
ALCS diagnostic file processor does not print some dump sections. -- Heading 'CTDTP' unknown -describes how to use them.
218
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
Standard system error dump format
The ALCS diagnostic file processor uses a standard format to print most sections of a system error dump.
This standard format shows the contents of up to 32 bytes on each print line. Figure 123 on page 219
shows an example of this standard format.
2EEFD6
2EEFD8
2EEFDA
VVVVVVVV
U W B 5C2
2 135 178B68
4 13A 17A4584
8 C 17817 ...
28 135 17A68 ...
48 139 17A558 ...
Figure 123. Standard system error dump format (with offsets)
The first (leftmost) column is the storage address (8 hexadecimal digits). It is the address of the first byte
on the line. The ALCS diagnostic file processor does not print lines if the entire 32 bytes of storage
contain binary zeros. Instead it prints eight asterisks (********) in the address column. This indicates that
ALCS has suppressed one or more lines of zeros.
The rest of the line consists of up to four groups of columns. Each group contains three columns that
show the displacement and contents of 8 bytes of storage (that is, the displacement from the start of this
storage area (3 or 4 hexadecimal digits) followed by the contents of the 8 bytes). The contents are in
hexadecimal or character notation. The ALCS diagnostic file processor uses character notation if the
storage area can contain character data and if two or more consecutive bytes contain printable characters,
as specified in the TRANSLATE control statement. See -- Heading 'CTDTP' unknown --.
The ALCS diagnostic file processor does not print offsets greater than hexadecimal X'7FFF'. Instead, it
prints blanks in the offset columns.
Figure 123 shows the contents of an area of storage that starts at address hexadecimal X'2EEFD60'.
At displacement 0, 2 bytes contain hexadecimal X'E4E6' (EBCDIC characters UW). The next 2 bytes
contain 0B00. The byte at displacement 48 (address 2EEFDA8) contains 13, and so on. Bytes from
address 2EEFDC0 onwards contain binary zeros.
Note: The byte at displacement 6 contains hexadecimal X'C2' (the EBCDIC character B). The ALCS
diagnostic file processor uses hexadecimal notation for this, not character notation, because the byte is
not part of a string of two or more consecutive printable characters.
For some storage areas, the ALCS diagnostic file processor prints character “tags” instead of hexadecimal
offsets. Figure 124 shows an example of this. It shows the first few lines of an ECB dump. The ECB
starts at address hexadecimal X'2EED4A0'. The first two fullwords are CE1CHW and CE1BAD. Both
are reserved fields. Next is the ECB work area, EBW000, and so on.
2EED4A CHW 3ABD BAD
2EED4A8 W 3R O M 1D3
W8 71 ...
2EED4C8 W32 8D2C 5
W4 43 ...
Figure 124. Standard system error dump format (with tags)
Notice that the first line of the ECB dump contains only 8 bytes (not 32 bytes). The ALCS diagnostic file
processor sometimes prints storage contents in this way, so that it can start a group of related fields on a
new line.
Chapter 11. Maintaining ALCS
219
Problem determination: System error dumps
System error dump header
The ALCS diagnostic file processor prints a header at the start of each system error dump. This header is
similar to the system error message that ALCS prints at RO CRAS when it produces a dump. Figure 125
on page 220 shows examples of the system error dump header.
hh.mm.ss SE-11 OPR-F11CC2 PROG-XERA OFFSET-14
VOLUME=volser DSNAME=dsname ALCS - yyyy.ddd hh.mm LOCAL,
MVS - yyyy.ddd hh.mm LOCAL,
hh.mm.ss SE-NODUMP OPR-F11CC2 PROG-XERA OFFSET-14
VOLUME=volser DSNAME=dsname ALCS - yyyy.ddd hh.mm LOCAL,
MVS - yyyy.ddd hh.mm LOCAL,
hh.mm.ss SE-12 CTL- PSW-77D1 8237E6
VOLUME=volser DSNAME=dsname ALCS - yyyy.ddd hh.mm LOCAL,
MVS - yyyy.ddd hh.mm LOCAL,
yyyy.ddd hh.mm GMT
yyyy.ddd hh.mm GMT
yyyy.ddd hh.mm
yyyy.ddd hh.mm
MSG='ZDUMP'
yyyy.ddd hh.mm
yyyy.ddd hh.mm
GMT
GMT
GMT
GMT
Figure 125. Examples of system error dump header
The system error dump header contains the following information (different system error dump headers
can contain different information, depending on the error):
ALCS – yyyy.ddd hh.mm LOCAL, yyyy.ddd hh.mm GMT
The ALCS year, day of year, and time (local and GMT) at the time of the dump.
MVS – yyyy.ddd hh.mm LOCAL, yyyy.ddd hh.mm GMT
The MVS year, day of year, and time (local and GMT) at the time of the dump.
SE-number
Dump sequence number, a 6-digit decimal number. SE-NODUMP means that there is no dump
for the error; usually this is because the error duplicates a previous dump.
CTL-code or OPR-code
System error code, a 6-digit hexadecimal number. CTL indicates that the error is a control
system error. That is, an error that the online monitor detects. OPR indicates that the error is
an operational system error. That is, an error that an application program detects. The ALCS
Messages and Codes lists the system error codes that ALCS uses.
PROG-name or PROG-name1/name2
Name of the application program or ALCS monitor CSECT (name) executing at the time of the
error. The dump header contains this only if ALCS can determine that the error is in a
particular application program or ALCS monitor CSECT. If a TPFDF program is executing at
the time of the error, this is in the format "name1/name2". This provides the name of the
TPFDF program (name1) executing at the time of error and the application program (name2)
which invoked the TPFDF program.
OFF-listing_address
Offset of error within the ALCS monitor CSECT, a hexadecimal number. This address
corresponds to the address (LOC) in the assembler listing of the ALCS monitor CSECT. The
dump header only contains this if ALCS can determine that the error is in a particular monitor
CSECT.
OFFSET-listing_address
Offset of error within the application program, a hexadecimal number. This address
corresponds to the address (LOC) in the assembler listing of the application program. The
dump header only contains this if ALCS can determine that the error is in a particular
application program.
220
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
AT-address
Address of error in memory, a hexadecimal number. The dump header contains this only if
ALCS can determine that a particular application program was executing at the time of the
error, but the failing instruction is outside the program.
PSW-psw
Corrected program status word (PSW) at the time of the error. “Corrected” means that the
instruction address in the PSW is adjusted to point to the failing instruction, not to the next
sequential instruction. The dump header contains this if ALCS cannot determine that the error
is in a particular application program.
CRN-crn
The CRN of the originating communication resource. The dump header contains this only if
ALCS can determine that the error is in an entry that originates from a particular
communication resource.
CRI-cri
The CRI of the originating communication resource. The dump header contains this only if
ALCS can determine that the error is in an entry that has an associated CRI, but the CRI does
not match any known communication resource.
MSG=‘text’ Explanatory message associated with the error. The dump header contains this only if there is
an explanatory message.
VOLUME-volser
Volume serial of ALCS diagnostic file data set that contains the system error dump. (Note that
the system error dump can overflow to other MVS data sets.)
DSNAME-dsname
Data set that contains the system error dump. (Note that the system error dump can overflow
to other MVS data sets.)
If there is no dump for the error (SE-NODUMP), the system error dump header does not include the ALCS
diagnostic file processor data set name and volume serial number.
If the system error is a program interruption that is not a SERRC, the system error dump header includes an
extra line showing the type of program interruption.
If the system error is an MVS abend that is not a program interruption, the system error dump header
includes an extra line showing the system completion code.
General and floating-point registers
This dump shows the contents of the general and floating-point registers at the time of the error (that is,
when the online monitor detects the error, or when the application program issues SYSRA or SERRC). The
dump also shows the corrected program status word (PSW) at the time of the error. “Corrected” means
that the instruction address in the PSW is adjusted to point to the failing instruction4, not to the next
sequential instruction.
The register contents and the PSW are in hexadecimal notation. Figure 126 on page 222 shows an
example.
4
An “imprecise interrupt” can occur, which does not point accurately to the failing instruction, but this is extremely rare.
Chapter 11. Maintaining ALCS
221
Problem determination: System error dumps
GENERAL PURPOSE REGISTERS
RAC 1313 7F7597 RG1
RAP 7F5FDDA 2F414A REB
PSW 77D 82F41548
RGA FF5FDEAC 7F7D ...
RLA 83C5EC 3BF2 ...
Figure 126. Example of a general register dump
Area addressed by program status word
This dump shows the contents of 128 or 4096 bytes of storage that include the storage that the PSW
addresses, if that storage is accessible to ALCS. Figure 127 shows an example. In the example, the
PSW is hexadecimal X'077D000082F41540'. This PSW instruction address points to the character string
'SE' (hexadecimal X'E2C5') (a SERRC monitor-request macro).
AREA ADDRESSED BY PSW
2F41518
T M 2F45138
X Z 68 344
VVVVVVVV
X Q B324 ...
S E 61F1 13137F2 ...
Figure 127. Example of an area addressed by PSW dump
Areas addressed by general registers
This dump shows the contents of 128 or 4096 bytes of storage that include the storage addressed by
each of the general registers at the time of the error, if that storage is accessible to ALCS. For example:
AREA ADDRESSED BY RG1
7F7579
VVVVVVVV
X W 64A C V S N
AREA ADDRESSED BY RGA
7F5FDEA8
4D29A8 58E913
7F5FDEC8
81F4AE 83DE47F
..
.
582E14 1BFF41FF ...
8116CAA 53 ...
...
Figure 128. Example of areas addressed by general registers dump
Storage unit block list descriptor
This dump shows the contents of the storage unit block list descriptor for the entry active at the time of the
error. Figure 129 shows an example.
BLOCK LIST DESCRIPTOR -- PRIME SU -- TIME 12.27.28.2
7856 PCH 77D2 2F41 PBA PPI 3C58 C ...
7858 FOP LOP 4 ...
..
.
Figure 129. Example of a storage unit block list descriptor dump
Tags identify fields in the storage unit block list descriptor. They relate to labels that the LSLS macro
generates in the LS0LS DSECT. For example, PCH is the tag for the field LS0PCH, FOP is the tag for
field LS1FOP, and so on.
222
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
If the entry is using more than one storage unit, there is a storage unit block list descriptor for each
storage unit.
hh.mm.ss.t (hours, minutes, seconds, and tenths of a second) is the time (TOD clock) that ALCS stores in
the descriptor when it creates the ECB. For entries that process VTAM input messages, ALCS creates
the ECB ready to receive the message; later (when the message arrives) ALCS replaces the TOD clock in
the descriptor with the time that the message arrives.
If an entry is using more than one storage unit, the first appears with the heading:
BLOCK LIST DESCRIPTOR -- PRIME SU -- TIME hh.mm.ss.t
the rest appear with the heading:
BLOCK LIST DESCRIPTOR -- OVERFLOW SU -- TIME hh.mm.ss.t
with the same tags. The time is the TOD clock that ALCS stores in the descriptor when it dispenses the
storage unit.
Entry control block descriptor
This dump shows the contents of the ECB descriptor for the entry active at the time of the error.
Figure 130 shows an example.
ENTRY CONTROL BLOCK DESCRIPTOR
2F4 BDA 7856 2F42 ACEE ..
.
PIA STA ...
FEX 8 ...
Figure 130. Example of an entry control block descriptor dump
Tags identify fields in the ECB descriptor. They relate to the CE3 labels that the DXCECBD macro generates
in the DXCECBD DSECT. For example, BDA is the tag for the field CE3BDA, and so on.
If the entry is using more than one storage unit, there is an ECB descriptor only for the first storage unit.
The ECB descriptor is positioned just before the first storage unit.
|
Data event control block (DECB) descriptor
| This dump shows the contents of the DECB descriptor for the entry active at the time of the error.
| Figure 131 shows an example.
|
|
|
||
|
DECB DESCRIPTOR
F71E DESC F75768 F71E2 2 DECBDECB 1
..
.
322E ...
28 ...
| Figure 131. Example of a DECB descriptor dump
| Tags identify fields in the DECB descriptor. They relate to the CE5 labels that the DXCECBD macro
| generates in the DXCECBD DSECT. For example, DESC is the tag for the field CE5DESC, and so on.
Chapter 11. Maintaining ALCS
223
Problem determination: System error dumps
| There can be more than one DECB descriptor for the entry. A DECB descriptor contains the DECB
| header and the system areas for several DECBs. Each DECB descriptor is positioned just before the
| storage unit containing the associated DECB application areas.
|
Data event control block (DECB) application areas
| This dump shows the contents of DECB application areas for the entry active at the time of the error.
| Figure 132 shows an example.
|
|
|
|
|||
DECB APPLICATION AREAS
F71F2 CNAM C1D5D5F F1444
F71F4 CFRW F71F6
...
4444 4444 ...
3D58F3 ...
...
| Figure 132. Example of a DECB application areas dump
| Tags identify fields in the DECB application areas. They relate to labels that the IDECB macro generates in
| the IDECB DSECT. For example, CNAM is the tag for the field IDECNAM, and so on.
Entry control block prefix
This dump shows the contents of the ECB prefix for the entry active at the time of the error. Figure 133
shows an example.
ENTRY CONTROL BLOCK PREFIX
2F41A PFX 2F41C
..
.
...
...
Figure 133. Example of an entry control block prefix dump
Tags identify fields in the ECB prefix. They relate to labels that the EBEB macro generates in the EB0EB
DSECT. For example, PFX is the tag for the field CE2PFX and so on.
Entry macro trace block
The entry macro trace block is formatted to show the monitor-request macros that the entry issues before
the error. The monitor-request macros are in time sequence, the most recent last. Figure 134 shows an
example.
ENTRY
PROG
XERA
XERA
..
.
MACRO TRACE DATA
MACRO ADDR REPEAT
GETCC 34
FILNC EE
PROG
XERA
XERA
MACRO
FACEC
WAITC
ADDR
4E
F4
REPEAT ...
...
...
Figure 134. Example of an entry macro trace block dump
The macro trace block dump is in four groups of columns. Each group contains information about one
monitor-request macro under the following headings:
PROG
224
Name of the program that issues the monitor-request macro.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
MACRO Name of the monitor-request macro.
ADDR
Hexadecimal offset (listing address) of the monitor-request macro in the program.
REPEAT Repeat count if the program issues the monitor-request macro repeatedly.
In the example shown in Figure 134 on page 224, program XERA issues the GETCC monitor-request
macro at displacement hexadecimal X'034'. It then issues FACEC (ENTRC FACE) hexadecimal X'04E', and
so on. Note that the macro request type, not the macro name, appears in the dump. For most macros,
the macro request type and the macro name are the same.
Entry control block
This dump shows the contents of the ECB for the entry active at the time of the error. Figure 135 shows
an example.
ENTRY CONTROL BLOCK -- CREATED BY CRETC -- LAST MACRO ...
2F415A CHW 3C58 BAD
2F415A8 W
2F435FE
W8 11E ...
2F415C8 W32 19 197197
W4 2F4255C ...
..
.
Figure 135. Example of an entry control block dump
Tags identify fields in the ECB. They relate to labels that the EBEB macro generates in the EB0EB
DSECT. For example, CHW is the tag for the field CE1CHW, W000 is the tag for field EBW000, and so
on.
The contents of the register save area in the ECB (dump tags RDA, RDB, RAC, RG1, ...) can be useful.
They show the register contents at the time that the entry issued the last monitor-request macro before the
error was detected.
Communication table item
This dump shows the contents of the communication table item for the originating communication
resource. This is for the CRI in field CE3CRI in the ECB descriptor for the entry active at the time of the
error. Figure 136 shows an example.
COMMUNICATION
7F2595 CRB
7F2595 SW1
7F259538 38
7F259558 58
7F259578 78
VVVVVVVV
..
.
TABLE ITEM -- CRI - 2ED
D7E8C5E2 C1D9C5F3
2C212 SW2
E8 578
CRI
TOD
4
6
8
2ED
AB4DF64
28
F13E694
185B
...
...
...
...
...
Figure 136. Example of an entry control block dump
Tags identify fields in the communication table item. They relate to labels that the CORE macro generates
in the CO0RE DSECT. For example CRN is the tag for the field RECOCRN, CRI is the tag for the field
RECOCRI, and so on.
Chapter 11. Maintaining ALCS
225
Problem determination: System error dumps
Blocks associated with entry
This dump shows the contents of storage blocks associated with the entry active at the time of the error.
These include:
5
5
5
5
5
5
5
5
Attached storage blocks
Automatic (ALASC) storage blocks
Detached block control table
Detached (DETAC) storage blocks
TPFDF stack blocks
Detached TPFDF storage blocks
HLL control blocks
Local save stack blocks
Figure 137 shows an example of an attached storage block.
STORAGE BLOCK -- LEVEL 3
2F4315 X T 848 C B X N
VVVVVVVV
..
.
8 ...
Figure 137. Example of an attached storage block dump
The heading shows the level where the block is attached.
Programs associated with entry
This dump shows the application programs associated with the entry that was active at the time of the
error.
The dump shows these programs in order of execution. For example, if program PRG1 calls (ENTRC)
program PRG2 and program PRG2 then calls (ENTRC) program PRG3, they appear in the dump in the
order PRG1, PRG2, PRG3. A program that issues ENTNC or ENTDC is no longer associated with the entry;
it does not appear in the dump.
Figure 138 shows an example of an application program.
PROGRAM XERA
7F5FDD88 LNG 4 4 VSN
7F5FDDA8 2 9519135 47881C
..
.
SHR FFFFFFFF FFFFFFFF ...
28 S E 61F1 1F9CAA ...
Figure 138. Example of an application program dump
The heading shows the program name and the version number. Figure 138 shows program XERA
version 00.
The first line has tags that identify fields in the program header, as follows:
LNG
VSN
SHR
XCL
BSE
226
Length (bytes) of application program, low-order halfword.
Program version number, 2 characters.
Shared global resource indicators, 32 bits.
Exclusive global resource indicators, 32 bits.
Program base (general register 8 (RAP) points to this field).
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
NAM
Program name, 4 characters.
User storage list items
These are the storage areas (if any) that the program requested with the SLIST parameter of the SERRC
macro. They appear in standard system error dump format, with offsets.
MVS system diagnostic work area
This dump shows the contents of the MVS system diagnostic work area (SDWA) at the time of the error.
Figure 139 shows an example.
OS SYSTEM DIAGNOSTIC WORK AREA
BASE AREA
98B938 PARM 4C1 ABCC CTL1 FF751 ...
98B958 GR2 FF5FDEAC 7F7D GR3 GR4 7F75E28 2F44B5A ...
..
.
Figure 139. Example of a system diagnostic work area dump
See the appropriate MVS Data Areas for a description of the format and contents of the SDWA. Tags
relate to the field descriptions in that document. For example, PARM is the tag for the field SDWAPARM,
and so on.
If general register 10 (RLA) points to an online monitor CSECT at the time of the error, ALCS saves the
CSECT name in SDWACSCT (tag CSCT).
Remember that the SYSRA and SERRC monitor-request macros provoke a program interruption, operation
exception. MVS records this as system completion code 0C1 in SDWAABCC (tag ABCC).
System macro trace block
This dump shows the system macro trace block formatted to show the monitor-request macros that all
entries issue before the error. The monitor-request macros are in time sequence, with the most recent
last. Figure 140 shows an example.
SYSTEM MACRO TRACE DATA
ECB
PROG MACRO ADDR
2E514A CGTD GTFCC 32
2E594A SLCI CXFRC E2
..
.
ECB
2E514A
2E594A
PROG
CVIA
NUC
MACRO
SENDA
ENTDC
ADDR
1C8
1D7E
...
...
...
Figure 140. Example of a system macro trace block dump
See also “System macro trace block”.
The system macro trace block dump is in four groups of four columns each. Each group contains
information about one monitor-request macro under the following headings:
ECB
PROG
MACRO
ADDR
Address of the ECB of the entry that issues the monitor-request macro.
Name of the program that issues the monitor-request macro.
Name of the monitor-request macro.
Hexadecimal offset (listing address) of the monitor-request macro in the program.
Chapter 11. Maintaining ALCS
227
Problem determination: System error dumps
In the example in Figure 140, the entry with ECB at address hexadecimal X'2E514A0' issues GTFCC at
displacement hexadecimal X'032' in program CGTD. It then issues SENDA (SENDC Dx,A) at X'1C8' in
CVIA, and so on.
Later, the online monitor SLC input routine creates a new entry. The macro trace block shows this as
CXFRC (create new entry) in SLCI (the online monitor SLC input routine). The monitor then passes control
to an application program to process the new entry. The macro trace block shows this as ENTDC in NUC
(the online monitor nucleus).
Note: The macro request type, not the macro name, appears in the dump. For most macros, the macro
request type and the macro name are the same. Only authorized monitor-request macros appear in the
system macro trace.
Monitor keypoint record
This dump shows the contents of the monitor keypoint record (CTKB). Figure 141 shows an example.
MONITOR KEYPOINT – CTKB
7F7313B BID C K 26 V F B
PRG
7F7313D
3B7 CLS
7F7313F
FPC
..
.
2 FFC4
4444 4
TMR A49461 A49461
...
...
...
Figure 141. Example of a monitor keypoint record (CTKB) dump
Tags identify fields in CTKB. They relate to labels that the CK9KC macro generates in the CK9KC DSECT.
For example, BID is the tag for the field CK9BID, and so on.
Resource hold table
This dump shows the contents of the resource hold table. Figure 142 shows an example.
RESOURCE HOLD TABLE
7E65 NBR 33 LKW
VVVVVVVV
7E85 FCH 7E87 TYP 288 8 ERR
VVVVVVVV
TRC ...
LCH 7E85 MSK 2 3D
...
...
Figure 142. Example of a resource hold table dump
Tags identify fields in the resource hold table. They relate to labels that the CHCH macro generates in the
CH0CH DSECT. For example, NBR is the tag for the field CH0NBR, and so on.
CRET table
This dump shows the contents of CRET table entries that are active (in use) at the time of the error.
When an application program issues CRETC, ALCS saves information in the CRET table. It uses this
information to create the new entry at the correct time. Figure 143 on page 229 shows an example.
228
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
ACTIVE CRET LIST ITEMS
7B98 CHN 7B8E 389 TIM
7B8E CHN 7B84 38B TIM
7B84 CHN E14 TIM
ACT X L M 4
ACT 2246 C B Q E
ACT X E R B
...
...
...
Figure 143. Example of a CRET table dump
Tags identify fields in the CRET table. They relate to labels that the CRET macro generates in the CR0ET
DSECT. For example, CHN is the tag for the field CR0CHN, and so on.
Macro trace control area
This dump shows the contents of the macro trace control area. This area contains control blocks that the
ALCS trace facility uses. The control area consists of:
5 Header
5 File mode trace entry
5 Conversational mode trace entries
Macro trace control areas that are all zeros do not appear in the dump.
Figure 144 shows an example.
MACRO TRACE CONTROL AREA HEADER
797 LKW 1
7972 CNV 79D48
..
.
NBR 1 A
28 7A38
...
...
MACRO TRACE CONTROL -- FILE MODE TRACE ENTRY
4E758 LKW 4E778 DSP 888 MDE ..
.
...
...
MACRO TRACE CONTROL -79A58 LKW 1
6BB88
VVVVVVVV
79AB8 GRP VVVVVVVV
79AF8
VVVVVVVV
79B38
79B58 ADP VVVVVVVV
:
CONVERSATIONAL MODE TRACE ENTRY
CA
STK 784A 2BD ...
...
NBM
...
NBP ...
ADD
...
ADP ...
Figure 144. Example of a macro trace control area dump
Tags identify fields in the resource macro trace control area. They relate to labels that the GTCA macro
generates in the GT0CA DSECT. For example, LKW in the header is the tag for the field GT0LKW, LKW
in the file mode trace entry is the tag for the field GT1LKW, and so on.
Chapter 11. Maintaining ALCS
229
Problem determination: System error dumps
Program control tables
This dump shows the contents of the tables that ALCS uses to control application programs. For
example, ALCS uses these tables to find the storage address of an application program. The tables are:
5 Module load table
5 Program hash table
5 Program control table
Figure 145 shows an example.
MODULE LOAD TABLE
7F6FD8 VVVVVVVV
7F6FD48 4 D X C A A 7F6FD68 6 ..
.
PROGRAM HASH TABLE
7F6F28 P Q M 2
VVVVVVVV
7F6F288 8 X M S 2
..
.
8 ...
48 68 287
...
...
8 7F657FC8 ...
88 7F5EB1AC ...
8 7F6E8 CFF8
...
88 7F6E5B
...
PROGRAM CONTROL TABLE
7F6E58 7F5D95D4 VVVVVVVV
7F6E588 8 ..
.
Figure 145. Example of a program control tables dump
Pool file control tables
This dump shows the contents of the tables that ALCS uses to control the dispensing and releasing of
pool file records. These tables are:
5 Pool file control tables
5 Pool file directory records
Figure 146 shows an example.
POOL FILE CONTROL TABLES
7E36D8 LKW 7F6BFE58 KPA LMS 161C8
7E36D28 KUC SKP SLI2 36 C8
..
.
...
...
POOL FILE DIRECTORY RECORD
7F4D428 BID F P D PRG
7F4D448 2 FFFFFF ..
.
...
...
1B5523F
28 1FFFF FFFFFFFF
Figure 146. Example of a pool file control tables dump
230
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
Tags identify fields in the pool file control tables. They relate to labels that the FCFC macro generates in
the FC0FC DSECT. For example, LKW is the tag for the field FC0LKW, and so on.
Tags identify fields in the pool file directory records. They relate to labels that the FPDR macro generates
in the FP0DR DSECT. For example, BID is the tag for the field FP0BID, and so on.
ALCS entry dispatcher work lists
This dump shows the contents of the ALCS entry dispatcher work list headers. Figure 147 shows an
example.
ENTRY DISPATCHER WORK LIST -- IOCB LIST
768 TOP CDS
BOT 768 ENTRY DISPATCHER WORK LIST -- READY LIST
7638 TOP CDS
BOT 7638 ENTRY DISPATCHER WORK LIST -- DELAY LIST
765 TOP CDS
BOT 765 ..
.
Figure 147. Example of an ALCS entry dispatcher work lists dump
Tags identify fields in the ALCS entry dispatcher work list headers as follows:
TOP
CDS
BOT
Address of first item on work list
Not used
Address of last item on work list
Block list descriptors
This dump shows the contents of the block list descriptors. ALCS uses the block list descriptors to control
the dispensing and release of I/O control blocks (IOCBs) and storage units.
Figure 148 shows an example.
BLOCK LIST DESCRIPTOR -- IOCBS
76B ADR 7F714 79 NBR
76B2 PBS 2 8 TOT
76B3 3 77B1 7F714
..
.
FLG 77B1
MSK FFFFFFE 4
38 8
...
...
...
BLOCK LIST DESCRIPTOR -- STORAGE UNITS
77B3 ADR 2E1 2D NBR FLG 787A
77B5 PBS 7 32 TOT MSK FFFFFFC 9
77B6 3 785E 2E1
38 3DCC2 4
..
.
...
...
...
Figure 148. Example of a block list descriptors dump
Tags identify fields in the block list descriptors. They relate to labels that the LSLS macro generates in
the LS0LS DSECT. For example, ADR is the tag for the field LS0ADR, and so on.
Chapter 11. Maintaining ALCS
231
Problem determination: System error dumps
I/O control blocks
This dump shows the contents of IOCBs. Figure 149 on page 232 shows an example.
DASD IOCB -- IN USE
7F721E CHN 59D5A EXT
7F721E2 ADR 7F567 318 BTY
VVVVVVVV
..
.
EVC 4 18
SAV ...
...
Figure 149. Example of an I/O control block dump
The heading shows the IOCB type, and whether the IOCB is in use or available.
Tags identify fields in the IOCB. They relate to labels that the IOCB macro generates in the IO0CB
DSECT. For example, CHN is the tag for the field IO0CHN, and so on.
Monitor interface area
This dump shows the contents of the online monitor interface area, with tags. Note especially that the
monitor CSECT base addresses are tagged. This is the first part of the ALCS online monitor nucleus
CSECT. Figure 150 shows an example.
MONITOR INTERFACE AREA
5D2C
D X C N
5D2E ASTI 5D3
5D3 STI 9D126
5D32 SAVS 9D
5D34
5D36 CDS2 5D38 INTC 4FFB8
5D3A INTE 52F38
5D3C
5D3E DMP 37DC8
5D4
5D42
5D44 SEQP 6AFC8
5D46 VFC 9545
5D48 DAV 34648
5D4A
5D4C PDU 618C8
5D4E
5D5 COMP 2BC
..
.
U C
5D34
9D634
C28
51F6
39CD
353E8
9789
338B8
47838
7862
2F2B
A Q 2 9 4 7 8
ACLS ANEB 5D38 CLS
NEB 9D1E8 9D1F8
SAVE SRBS C3 9D128
CDS 7F6BF 7F5212
INTD INTS 5482 53A7
93688
EMSG DMPC 38DB8 38FA
DCR
GTF 4A6D 4937
6B59
96EA8
VFP
VFH 95CB 95FB
DAT
DAS 32B2 3F94
GFS
GFC 428C 43DA
57BB
SND
OPZ 5F3A 1FCE8
COM3 COLF 14598 97F
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Figure 150. Example of a monitor interface area dump
Monitor work areas
This dump shows the contents of the online monitor work areas. Figure 151 on page 233 shows an
example.
232
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
MONITOR WORK AREA
1 -- NUC
688 PLI 688 HSA
6882 RGB 7668 RGC
..
.
LSA 72 83CBB2
RGD 3EE8 128F8
...
...
MONITOR WORK AREA
1 -- TIM
68C PLI 688 HSA
68C2 RGB 76488 RGC
..
.
LSA 698 2EF94A
RGD 8FE51E1 787E
...
...
Figure 151. Example of a monitor work areas dump
The heading shows the task that owns the work area and the function that uses the section of the work
area. Monitor work area 0 belongs to the main ALCS task, monitor work area 1 belongs to the first CPU
loop task, monitor work area 2 to the second CPU loop task, and so on. NUC indicates that the nucleus
CSECT (DXCNUC) uses the section of the work area, TIM that the timer routines (DXCTIM) use the
section, and so on.
Tags identify fields in the monitor work area. They relate to labels that the MNSV macro generates in the
MN0SV DSECT. For example, PLI is the tag for the field MN0PLI, and so on.
Application global area
This dump shows the contents of the application global area. The dump lists the various parts of the
application global area in the following order:
5
5
5
5
5
Directory
Directory
Directory
Directory
Directory
0,
0,
0,
1,
1,
area
area
area
area
area
1
2
3
1
2
and so on. Figure 152 shows an example.
APPLICATION GLOBAL AREA -- DIRECTORY -- AREA 1
7f7D
VVVVVVVV
7F7D4 GBLB 7F7D1C 41C4
GBLC 7F7D5E 51C4
..
.
APPLICATION GLOBAL AREA -- DIRECTORY -- AREA 2
7F75 A H 52 C B X N
8 ..
.
...
...
...
Figure 152. Example of an application global area dump
Tags identify fields in the application global area directories. The GLnBA macros generate these tags.
GLBA generates the tags for directory 0, and so on.
Entry storage
This dump shows the contents of all the ALCS storage units. If a storage unit contains an ECB, a
formatted ECB dump follows the storage unit dump. Figure 153 on page 234 shows an example.
Chapter 11. Maintaining ALCS
233
Problem determination: System error dumps
VVVVVVVV ENTRY STORAGE FOLLOWS
BLOCK LIST DESCRIPTOR -- PRIME SU -- TIME 12.29.57.
77B6 PCH 785E 2E1 PBA PPI 3DCC2 4
..
.
...
ENTRY CONTROL BLOCK DESCRIPTOR
2E BDA 77B6 ..
.
...
ENTRY CONTROL BLOCK PREFIX
2E1A PFX 77B6 ..
.
...
ENTRY MACRO TRACE DATA
PROG MACRO ADDR REPEAT
TIM
CXFRC DC8
..
.
PROG
NUC
MACRO
ENTDC
ADDR
1DF6
REPEAT
ENTRY CONTROL BLOCK -- CREATED BY ALCS MONITOR -- LAST
2E14A CHW 3DCC2 BAD
..
.
...
...
...
Figure 153. Example of an entry storage dump
Entry summary
A summary of all the ALCS storage units that contain ECBs. Each line of the summary gives information
about one entry. The information is in columns, and a heading line identifies the columns as follows:
DESC
CHAIN
Address of the ECB descriptor.
ECB descriptor chain. That is, the address of the next ECB descriptor in the chain. For
example, if an ECB is on the ready list, this chainword contains the address of the descriptor
of the next ECB on the ready list.
DEADLOCK
ECB deadlock-detector chain. If the ECB is waiting for record hold, resource hold, or
sequential file assign, this chainword contains the address of the descriptor of the ECB that
this ECB is waiting for.
ECB
ECB address.
CRI
Communication resource identifier (CRI) of the resource that originated the transaction that
this entry is processing.
REC HOLD Count of record addresses that this entry is holding.
RES HOLD Count of resources that this entry is holding.
SEQ FILE Count of sequential files assigned to this entry.
LAST MACRO
Information about the last monitor-request macro that this entry executed. That is, the
program name, macro name, and listing address of the macro within the program.
STATUS
Status of the entry. IN USE means that the storage unit is not available for use by other
entries. MSG WAIT means that ALCS is waiting for a VTAM RECEIVE to complete. When
the RECEIVE completes, the entry processes the message that arrives.
234
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: System error dumps
VFA control areas
This dump shows the contents of the tables that ALCS uses to control VFA buffers. These tables are:
5
5
5
5
Control area, common section
Control area, size-dependent data
Prime record locator table
Overflow record locator table
Figure 154 shows an example.
VFA CONTROL AREA -- COMMON SECTION
7F731618 RLPA 7F5CD 1CD RLPC RLOF 7F5CED3 FFFFFDCE
7F731638
L1 7F7316E 7F73176 L2
L3 7F7317E 7F73186
VVVVVVVV
...
...
VFA CONTROL AREA -- SIZE DEPENDENT DATA
7F73166 LOCK FF NBRB BLEN
7F73168 PRF PRL
S1
7F7316A HSN HST
7F7316C HSNR HSRP HSLG
VVVVVVVV
11
...
...
...
...
VFA FILE ADDRESS LOOKUP TABLE
7F5139A8
7F5BC28 7F1652
7F5139C8
7F5B9B8 7F1652
..
.
22414 21
4814 21
...
...
VFA RECORD LOCATOR TABLE – PRIME
7F7CD
7F7CD2
762D4 7F5C664
..
.
FF
FF
...
...
VFA RECORD LOCATOR TABLE -- OVERFLOW
7F5CECD
734 7F5C75C
7F5CECF
2734 7F5C79
..
.
7F5CE91
7F5CD58
...
...
Figure 154. Example of a VFA control areas dump
Tags identify fields in the VFA control area common section and size-dependent data. They relate to
labels that the VCCA macro generates in the VC0CA DSECT. For example, RLPA is the tag for the field
VC0RLPA, LOCK is the tag for the field VC0LOCK, and so on.
The VLRL macro generates the VL0RL DSECT. It describes the record locator table format.
VFA buffer headers
This dump shows the contents of the VFA buffer headers. Figure 155 on page 236 shows an example.
Chapter 11. Maintaining ALCS
235
Problem determination: Program driver
VFA BUFFER HEADERS
7F5C5
7F5C52
7F5B2
7F5C54
7F5CE56 7F5CE56
..
.
4 224 928
...
...
...
Figure 155. Example of a VFA buffer headers dump
The VHBH macro generates the VH0BH DSECT. It describes the buffer header format.
VFA buffers
This dump shows the contents of the VFA buffers.
SLC link and channel keypoints
This dump shows the contents of the SLC link and channel keypoints. Figure 156 shows an example.
SLC LINK KEYPOINT
7F45C HDR 7F45C2 SOF 322 FFF XMT
..
.
F4
KCH 182 31F
...
...
SLC CHANNEL KEYPOINT
7F45CBD8 HDR 7F45CBF8 NSR RRT
..
.
F5
EXC ...
...
Figure 156. Example of an SLC link and channel keypoint dump
Tags identify fields in the link and channel keypoints. They relate to labels that the LK4KC and LK5KC
macros generate in the LK4KC and LK5KC DSECTs. For example, HDR in the link keypoint is the tag for
the field LK4HDR, and so on.
User defined areas
This dump shows the contents of storage areas that the user-written dump exit routine requests. See
ALCS Installation and Customization for a description of this installation-wide exit routine.
11.2.5 Program driver
It is sometimes necessary to write an ALCS application program to perform a one-off function, for
example:
5 To test a user-written macro service routine
5 To rebuild a chain of pool file records that is damaged
To simplify writing these one-off programs, ALCS provides a program driver facility, the ZDRIV command,
which activates any specified program.
To use the program driver facility:
1. Assign a unique name to the application program.
2. Assemble the program and link-edit it into a load module.
236
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: SLC link trace
3. Use the ZPCTL command to load it into the system.
4. Use the ZDRIV command to activate the program. Optionally enter a character string to pass to the
program. This character string appears to the called program as an input message. That is, on entry
to the program, the character string is in a storage block attached on level 0, and in the IMSG input
message format described in ALCS Application Programming Reference – Assembler.
If no character string is given, an empty IMSG is attached on level 0.
See -- Heading 'ZDRIV' unknown --.
ZDRIV can also activate any existing application program, for example:
5 To activate a specially written staging program that sets up entry conditions and enters an existing
application program.
5 To activate an existing application program directly if no special entry conditions are required.
11.2.6 SLC link trace facility
The SLC link trace facility monitors activity on the SLC network. Use it during testing or production
operation. The SLC link trace facility records data each time a block is sent or received on an SLC
channel. Use the ZLKTR command to activate and deactivate the link trace facility, and to specify the
scope of the trace details). For example:
5 Trace selected SLC links; that is, all the channels on the links.
5 Trace all types of blocks, or one or more selected types of blocks only. For example:
–
–
–
–
Type B message blocks
Type A message blocks
Network control blocks
Link control blocks
SLC link trace can write the trace information to any or all of the following:
A printer terminal
The terminal must be either a CRAS printer or a printer associated with a terminal.
Note: Trace to a terminal imposes a higher load on ALCS than either trace to SLC trace block or
trace to the ALCS diagnostic file, so use it with caution.
SLC link trace block
Use the ZLKTR command to view the current contents of the SLC link trace block to a display terminal.
See -- Heading 'ZLKTR' unknown -- for more details of this command.
The ALCS diagnostic file
Run the ALCS diagnostic file processor to print the output. Use ALCS diagnostic file processor
options to select how to print SLC link trace information for example:
5 Do not print SLC link trace information.
5 Print all SLC link trace information.
5 Print SLC link trace information from selected time intervals.
For each LCB and message block the ALCS diagnostic file processor prints:
hh.mm.ss.t SLC type crn KCNn information
Chapter 11. Maintaining ALCS
237
Problem determination: SLC link trace
The ALCS diagnostic file processor can also print the following status messages for the SLC link trace
facility:
hh.mm.ss.t
hh.mm.ss.t
hh.mm.ss.t
hh.mm.ss.t
SLC
SLC
SLC
SLC
STARTING
ENDING
INVALID OP CODE – lcb_data
RESUMING AFTER SHUTDOWN – nnnn LOST ITEMS
Where:
hh.mm.ss.t
Time-of-day (TOD) clock time.
type
One of:
R
W
Block received on SLC channel.
Block sent on SLC channel.
crn
CRN of the link.
KCNn
Where n is the number of the channel within the link (from 1 to 7).
information
Information about the block. This information includes:
LCB=lcb_type
LCB type.
ATSN=atsn
The acknowledge transmission sequence number (ATSN).
TSN=tsn
The transmission sequence number (TSN).
LEN=size
Block size (number of bytes).
EIB=error_byte
Error index byte. For an explanation of the EIB, refer to IBM 3705 Emulation Program
Generation and Logic Manual for LICRA Line Control
DATA=data
First 4 to 63 bytes of the block in hexadecimal. Use the ZLKTR command to select the
number of bytes to be traced.
MBI=type_label – block_number
The message type (Type A or Type B) followed by the message label and the message block
number.
AMBI=type_label
The message type (Type A or Type B) followed by the acknowledge message label.
LCI=message_details
Four fields, as follows:
PD or ND
Message is (PD) or is not (ND) a possible duplicate message or possible duplicate
block.
238
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: TCP/IP trace facilities
HL or NH
Message is (HL) or is not (NH) for a high-level network.
BP or NP
Message is (BP) or is not (NP) protected.
LB or NL
Message is (LB) or is not (NL) the last block of the message.
HLN=hen/hex
Entry (hen) and exit (hex) addresses of the high-level network.
ACI=code
Message translate code.
lcb_data
First 12 bytes of the block, in hexadecimal.
nnnn
Number of trace entries lost because of link trace shutdown.
11.2.7 TCP/IP trace facility
The TCP/IP trace facility monitors activity on the TCP/IP network. Use it during testing or production
operation. The TCP/IP trace facility records data each time a data block is sent or received on a TCP/IP
communication connection. Use the ZACOM command to activate and deactivate the TCP/IP trace facility
for each TCP/IP communication resource. ALCS writes TCP/IP trace information to the ALCS diagnostic
file. Run the ALCS diagnostic file processor to print the output.
For each data block, the ALCS diagnostic file processor prints:
TCP/IP type hh.mm.ss CRN-crn LEN-size DATA-data
Where:
type
One of:
IN
Data block received on TCP/IP connection.
OUT
Data block sent on TCP/IP connection.
hh.mm.ss
Time-of-day (TOD) clock time.
crn
CRN of the TCP/IP communication resource.
size
Data block size (number of bytes).
data
First 32 bytes of the data block in hexadecimal.
Chapter 11. Maintaining ALCS
239
Problem determination: ALCS test facilities: STV
11.2.8 ALCS test facilities
ALCS provides:
5 The dynamic program load facility for testing individual programs or groups of programs.
5 The system test vehicle (STV) for testing the system; that is, testing all the applications together, using
a simulated network.
These are described in the following sections.
Dynamic program load facility
The ALCS dynamic program load facility is a tool for testing modified or new application programs from a
terminal, without affecting the rest of the system. ALCS program management can load single or multiple
copies of a program as a test program. Program management manages the association of test programs
with test terminals. ALCS communication support sets a flag in the communication tables to indicate that
a terminal is in test mode. When an entry is from a terminal in test mode, the communication routine flags
the ECB to indicate that it is a test entry. ALCS program management selects test copies of programs for
these entries.
Terminal in test mode: Use the ZPCTL command to load a test module for a terminal. A test module
belongs to a particular terminal (either the terminal specified on the ZPCTL command or, if no terminal is
specified, the ZPCTL input terminal). See -- Heading 'ZPCTL' unknown -- for details.
Test entries: ALCS treats all input from terminals in test mode as test input. ALCS communication
support flags the ECB to indicate that it is a test entry. Program management resolves program calls for
test entries by selecting test copies of programs where applicable.
System test vehicle
The ALCS system test vehicle (STV) is a tool for testing ALCS configurations and application programs
before starting production use. Use it also to test the system after changing the configuration or
application programs.
STV simulates a communication network that can consist of ALC, IBM 3270, and WTTY terminals.
STV reads input messages from a test unit data set. STV enters these messages into ALCS as if they
come from a real terminal. STV allows simulated input only from terminals that are specified as test
terminals in the ALCS generation.
STV intercepts data that is sent to a test terminal, and writes it to the ALCS diagnostic file. Use the ALCS
diagnostic file processor to process and format STV data.
Preparing for system test: To obtain the maximum benefit from system test using STV, prepare for the
test as follows:
1. Prepare the basic test plan.
Decide what major areas of the system to test.
Note: STV does not provide an appropriate environment for testing ALCS commands. If it is
necessary to test these functions, prepare a separate plan to test them “hands on”.
2. Design the test network configuration.
Decide what terminals are needed to enter test messages. Note that to test the system's capability to
handle many input messages simultaneously, it is necessary to include several of each type of
terminal.
240
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Problem determination: ALCS test facilities: STV
3. Generate the ALCS test system, including the test network.
4. Initialize the database as required for testing purposes.
5. Specify the test input messages together with their expected responses.
Where possible, avoid test input messages that depend on the initial contents of the database.
6. Use the ALCS system test compiler (STC) to prepare test unit data sets.
When preparing the input messages and expected responses, group the messages on separate test
unit data sets in such a way that, if there are errors, the correction can be tested by processing only
one data set rather than restarting from the first data set. See ALCS Installation and Customization
for a full explanation of STC.
Note: STC may display error responses from the PL/I high level language environment. See -Heading 'BIB' unknown -- for a list of associated documentation.
Running STV: Use the ZTEST command from a Prime CRAS authorized terminal to start and control
STV. See -- Heading 'ZTEST' unknown -- for more information about this command.
STV output listing: STV intercepts output messages to test terminals. It writes them, together with
copies of the input messages from the test unit data set, to the ALCS diagnostic file. Run the ALCS
diagnostic file processor to format and print this data.
The output listing can include:
5 Start and end of test indicators
5 Input and output messages
Start and end of test indicators: The following messages indicate the state of STV.
TEST
TEST
TEST
TEST
TEST
STARTED
PAUSED
RESTARTED
CANCELLED
STOPPED
In each case, the system test compiler RUNID control statement is also printed. See ALCS Installation
and Customization for a full explanation of the system test compiler RUNID control statement.
Input and output messages: Messages are printed as they appear at a terminal. Vertical bar (|)
characters indicate the display or paper margins as follows:
Display or printer
WTTY display
ALC
IBM 3270 display
IBM 3270 printer
Right margin position
70
64
80
No right margin
Where applicable, an underscore (_) character indicates the cursor position.
To the left of the first line of each message there is a heading that indicates:
5 Input message or output message.
5 WTTY or non-WTTY terminal.
5 Message sequence number. (STV maintains separate sequences of numbers for input and output
messages, and for WTTY and non-WTTY messages.)
5 Terminal CRI.
Chapter 11. Maintaining ALCS
241
Problem determination: ALCS test facilities: STV
For non-WTTY messages, the end-of-message character prints as:
#EOM
#EOI
#EOU
#EOP
End-of-message
End-of-message
End-of-message
End-of-message
complete (X'4E')
incomplete (X'6D')
unsolicited (X'5F')
push button (X'7E')
STV simulates hardware answerbacks (positive acknowledgments) from printer terminals.
Multi-block messages on display terminals are printed with the start of text in each block starting at the
beginning of a line. With real terminals this does not occur because there is no automatic new line at the
end of a block. Some printer terminals perform a new line at the end of each block, so the ALCS
diagnostic file processor correctly simulates this type of terminal.
Leading and trailing letter-shift (#LSC) characters on WTTY messages are indicated as follows:
VVV nn LEADING LSCS
VVV nn TRAILING LSCS
If the first character of a WTTY message line is a case shift character, the ALCS diagnostic file processor
does not print it. Instead, it prints the tag “LSC” or “FSC”, as appropriate, in the left-hand margin.
Sometimes the ALCS diagnostic file processor cannot print messages as they would appear at the
terminal. This is usually because of an error in the message. In such cases, ALCS diagnostic file
processor prints a hexadecimal dump of the message block, with the following heading:
UNABLE TO FORMAT MESSAGE – reason
where reason can be:
UNKNOWN LINE TYPE
The ALCS diagnostic file processor cannot determine the type of terminal.
LINE(S) TOO LONG
One or more lines of the message exceed 79 characters (non-WTTY message) or 69 characters
(WTTY message).
INVALID END OF MESSAGE
An ALC message does not end with a valid end-of-message character (#EOM, #EOI, #EOU, or
#EOP).
UNPRINTABLE CHARACTER(S)
There are one or more unprintable characters in the message text.
TOO MANY LSCS
There are more than 99 leading or trailing letter-shift characters on a WTTY message. This is
probably, but not necessarily, an error.
LF MISSING AFTER CR
A carriage return character (#CAR) is not immediately followed by a line feed character (#LFEED) in
a WTTY message. Note that the sequence #LFEED #CAR is not correct.
LSC/FSC NOT AFTER LF
A case shift character does not immediately follow a line feed character in a WTTY message.
Although this is not an error, the ALCS diagnostic file processor cannot indicate the position of a
case shift character unless it is the first character of a line. The message is printed in hexadecimal.
If STV cannot process an input message from a test unit data set, the message is printed in hexadecimal,
followed by:
STV UNABLE TO PROCESS MESSAGE – reason
242
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Performance monitoring: Data Collection
where reason can be:
INVALID CRI
This is issued for one of the following reasons:
5 The CRI does not exist.
5 The resource is a type that STV does not support.
5 The resource cannot logically input a message to ALCS (for example, a simplex out WTTY line).
RESOURCE IS NOT AN STV RESOURCE
The originating terminal is not a test terminal. See ALCS Installation and Customization for details of
how to define test terminals.
OUTPUT MESSAGE LOST – INSUFFICIENT STORAGE
STV cannot obtain storage to record the output message.
11.2.9 Information and error messages
ALCS writes some information and error messages to the ALCS diagnostic file. The ALCS diagnostic file
processor prints these messages as follows:
hh.mm.ss event_description
Where:
hh.mm.ss
Time-of-day (TOD) clock time of the event.
event_description
Type of event, described in the following section.
TCPIP messages
CRN-crn TCPIP MAXIMUM CONCURRENT SERVER CONNECTIONS
The maximum number of concurrent connections has been reached for the TCPIP communication
resource with CRN crn.
CRN-crn TCPIP IDLE CONNECTION TIMEOUT EXPIRED
No more data was received on the TCPIP communication resource with CRN crn during the idle
connection timeout interval.
CRN-crn TCPIP CONNECTION CLOSED BY INSTALLATION-WIDE EXIT
The installation-wide monitor exit USRTCP2 closed the connection for the TCPIP communication
resource with CRN crn.
11.3 Performance monitoring and control
Performance monitoring and control for real-time systems is an essential part of installation management.
Two functions in ALCS, data collection and the statistical reports generator (SRG), are designed to assist
programming and non-programming staff in such tasks as:
5
5
5
5
Capacity planning
Verifying response time criteria
Identifying the cause of performance problems
Monitoring the use and impact of a new application
Chapter 11. Maintaining ALCS
243
Performance monitoring: Data Collection
MVS and other subsystem facilities: In addition to data collection and SRG, you also have all the MVS
and other subsystem facilities for monitoring and controlling the performance of your system. These are
fully described in the appropriate MVS and subsystem manuals.
Use MVS Resource Measurement Facility (RMF) in conjunction with SRG. RMF reports on the overall
system performance. SRG reports on what is happening in the ALCS region.
Alternatively, you can use the IBM program Service Level Reporter (SLR) to analyze data collection
records on the ALCS diagnostic file, and produce reports tailored to your requirements. You can find the
format of the records in ALCS Application Programming Reference – Assembler.
11.3.1 Data collection
Data collection is an online ALCS function that can optionally collect the following classes of performance
data:
5
5
5
5
5
5
5
5
DASD I/O operations
VFA
ALCS waits
Input and output messages
SLC communication
X.25 communication
Application programs
Entries
ALCS writes the data collection output to the ALCS data collection file or, if not defined in the sequential
file generation, to the ALCS diagnostic file.
Use the ZDCLR command (see -- Heading 'ZDCLR' unknown --) to start and stop data collection and to
select the classes of performance data to collect. Alternatively, use the DCLOPTS parameter of the
SCTGEN generation macro to start data collection automatically as part of ALCS startup (see the ALCS
Installation and Customization for details.).
Data collection entries data
The minimum data that you can collect (without stopping data collection completely) is the entries data.
For each entry, ALCS (and optionally, the application) records data in a storage area associated with the
ECB. For example, the storage area contains counters for DASD I/O operations; ALCS maintains this
count. When each entry exits, data collection writes this information to the sequential file.
There are two types of entry data collection data, as follows:
System data: During the life of an entry, the ALCS monitor accumulates statistics in the entry system
data collection area.
Application data: During the life of an entry, application programs can store and update information in
the entry application data collection area. This is done using the DCLAC macro. This is described in ALCS
Application Programming Reference – Assembler.
Application programs can only use the entry application data collection area if you have defined it in the
system configuration table. See ALCS Installation and Customization for information on how to code the
DCLECBU parameter on the SCTGEN macro.
244
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Data collection performance overhead
Data collection increases the processing load on the system, particularly when collecting all classes of
performance data. If the processing load reduces the available storage units to below a preset level,
ALCS delays processing new messages; this invalidates the data collected. To check that this does not
happen, monitor the available storage units against the preset level (activity control variable). See -Heading 'ZAACV' unknown -- for a description of activity control variables (the ACV parameters). Use the
ZSTAT command to display available storage units and the ZDACV command to display the activity control
variables.
To produce reliable statistics, run data collection regularly at peak times, and for long enough to include a
representative message mix (say 30 minutes). Regular data collection over short periods is preferable to
occasional longer periods. The amount of data output to the ALCS data collection file can be a limiting
factor. The program collector produces the greatest output, and you may wish to consider running this
collector less frequently.
Use the ZDCLR command (described in -- Heading 'ZDCLR' unknown --) to start and stop data collection
and to select the classes of performance data to collect.
When data collection ends, ALCS continues to write other diagnostic data to the ALCS data collection file
data set, which will be closed automatically when it is full. If you want to process the ALCS data collection
file at once, use the ZSSEQ command to close it. Whether you close the data set or wait for it to close
automatically, SRG will extract the data collection material from any the other data that is on the file.
11.4 Improving application performance
Even small improvements to frequently used application programs can have a significant effect on system
performance. Two areas that can repay examination are:
5 Storage serialization. In a multiprocessor system, you should minimize storage serialization in order
to avoid degrading system performance. The BEGIN macro parameters, XCL= and SHR=, control the
serialization of the global area in ALCS. If the XCL= and SHR= parameters are omitted, all global
area access by application programs is serialized, as described in ALCS Installation and
Customization.
It can be a significant effort to examine every application program and code the BEGIN macro
parameters. A more productive method can be to use the report on “Program Usage Mix by Called
Program”. Starting with the most frequently called program, check to see whether it updates the
global area. If not, code XCL=NONE. Check also to see if it references the global area. If not, code
SHR=NONE.
5 Program calls. Reducing the number of program calls improves the performance of an application.
The report on “Program Usage Mix by Called Program” can show programs that only one program
calls. This is often because the called program is an overflow to the calling program. Where possible,
merge these programs to reduce the number of program calls. Programs that run under ALCS can be
up to 4KB in 24-bit mode and up to 32KB in 31-bit mode.
This report can also show other program call abnormalities. For example, a frequently called program
with a high percentage of the calls from an infrequently called program. You can often improve
performance by moving or copying a routine from one of the programs to the other.
Chapter 11. Maintaining ALCS
245
11.4.1 Message mix
The “Medium Speed Message Mix by Action Code” report shows how the end users use the system. It
can indicate the percentage of messages for a particular application (for example, to assess the use of a
new application).
The report shows only the first action code in a message. For example, an airline agent can enter the
following:
5
5
5
5
Name
Received from
Phone number
Ticketing details
as four separate messages or as one message. If the agent enters it as one message, the “end item” key
separates each part of the message. In this case the report shows the action code for the name message
only. The absence of action codes for the received from, phone number, and ticketing messages
indicates that airline agents are using the reservation system efficiently.
Note: The ECB processing summary (see -- Heading 'EPS' unknown --) shows all the FINDs, FILEs,
ENTERs, and MILLISECS LIFE for the four message parts against the first action code (in the above
example, the name action code).
11.4.2 Record access mix by record type
This report identifies the most frequently accessed record types. Consider changing the VFA option for
the record types frequently written to DASD to delayed file or time-initiated file to improve the VFA hit rate
for DASD writes.
11.4.3 Record access mix by record ID
This report can highlight abnormal conditions; for example, an unexpectedly high access level for a record
type may indicate bad application design.
You can also use this report to identify good candidates for short-term (rather than long-term) pool.
Record ID 0000 represents pool file records that ALCS reads to check that they are available before
dispensing them.
11.5 Applying corrective service
You will receive corrective service from IBM as the product is enhanced. We strongly recommend that all
corrective service is applied to your system as soon as possible. You may use the ISPF panels to assist
in the application of corrective service changes.
11.5.1 Using ISPF panels to apply corrective service to ALCS
246
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
k
File Options Help
-------------------------------------------------------------------------ALCS primary menu
Command ===> ______________________________________________________________
l
Choose one of the following actions, then press ENTER
Actions:
__ 1. Installation
2. Generation and database creation
3. Maintenance
4. Operations
5. Application development
ALCS system . . SMPE
IBM-supplied SMP/E system definitions
p
q
Figure 157. ISPF panel: ALCS Primary Menu
Select option 3 to display the Maintenance panel which is shown in Figure 158.
k
l
Maintenance
Command ===> ______________________________________________________________
Choose one of the following actions, then press ENTER
Actions:
__ 1. Receive corrective service (online)
2. Apply corrective service (batch)
3. Accept corrective service (batch)
4. Restore corrective service (batch)
5. Reject corrective service (online)
6. List details of corrective service (online)
7. Browse service log
p
q
Figure 158. ISPF panel: Maintenance
Select the appropriate option to take you to the panel that you wish to use.
The standard method of manually applying all SYSMODs that affect ALCS is the SMP/E
“RECEIVE/ACCEPT BYPASS (Apply Check)/System Generation/JCLIN” method. This applies to IBM
supplied corrective service (APAR fixes) and IBM supplied preventive service (PTFs), as well as
USERMODs. To apply one or more SYSMODs:
1. RECEIVE the SYSMOD.
2. APPLY the SYSMOD to a test ALCS system. It is advisable to test any modification to ALCS in a test
environment before implementing it on the production system. To set up a test environment, define a
Chapter 11. Maintaining ALCS
247
test ALCS system to SMP/E in a separate target zone, and maintain a separate complete set of target
libraries (and optionally distribution libraries).
3. Use the test system to test the modifications introduced by these SYSMODs. To resolve any
outstanding problems:
a. RESTORE, and if necessary REJECT the USERMOD, correct the changes and then RECEIVE
and APPLY again.
b. Construct, RECEIVE, and APPLY additional USERMODs. This can include replacement
USERMODs for those regressed by the application of IBM service.
USERMODs are change decks. If a USERMOD has been APPLYed to an IBM component, it
must be RESTORed and (and, if necessary) REJECTed before the IBM service can be APPLYed.
New USERMODs must now be built and APPLYed taking into account any changes made by the
IBM corrective service.
c. APPLY additional IBM corrective or preventive service.
4. When the changes are complete and error free, APPLY the SYSMOD to the production ALCS target
zone and target libraries.
For a complete description of SMP/E commands, and details of USERMOD construction and naming, see:
5 System Modification Program Extended (SMP/E) User’s Guide
5 System Modification Program Extended (SMP/E) Reference.
248
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Macros and callable services
|
Chapter 12. Macros and callable services
This chapter contains details of macros and callable services supplied as part of ALCS that you can use in
assembler language application programs. These include:
5
5
5
5
5
5
5
Monitor-request macros
System-error macros
Assembly macros
DSECT macros
Equate macros
Dummy macros
Callable services.
For an explanation of these groupings, see Chapter 13, “Summary of ALCS macros and callable services”
on page 322.
Notes:
1. The macros and callable services appear in alphabetical order.
2. The first form of the macro shown under the Format heading is the current form of the macro allowed
under ALCS Version 2 Release 2.1. Where possible, ALCS allows you to use forms of the macro that
were valid in previous versions of ALCS, and forms of the macro that are allowed under current and
previous versions of TPF. Forms that are allowed are shown as alternatives. All the TPF macro
formats might not be listed here.
TPF compatibility
If your programs must be compatible with TPF, consult the appropriate level of TPF documentation
for the format of TPF macros.
3. For completeness, some macros which are described in other books are listed in this chapter. For
example the DXCEMG macro is listed here but described in ALCS Installation and Customization. This
chapter also lists, but does not describe, some macros provided with the IPARS application, which is
not part of ALCS, but which is included in the ALCS shipment.
Chapter 12. Macros and callable services
249
ATTAC
12.1 ATTAC – Attach a previously detached storage block
12.1.1 Format
| [label] ATTAC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
|
[,TYPE=([STACK|type][,UNCOND|COND])]
or formats for TPF compatibility:
| [label] ATTAC [R+7|Dn|Rn|DECB={decb_addr|(reg2)}][,ACPDB]
[label] ATTAC ACPDB
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the storage block is attached, where:
|
Dn
(reg1)
Level symbol: D0, D1 and so on up to DF for level 15.
Register that contains the level value (use LA reg1,Dn). Use general register 14 (RDA) or
0 through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the storage block is attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
TYPE=([STACK|type][,UNCOND|COND])
Where:
type
|
|
|
|
|
|
|
|
|
|
|
|
One of the following:
STACK
FA
SA
ANY
ACPDB
Reattach the block from the most recent DETAC ...,TYPE=STACK at the specified
ECB level or for the specified DECB.
Reattach the block detached by a previous DETAC ...,TYPE=ADDRESS. The block
file address must match the file address at the specified ECB level or in the
specified DECB. Store the required file address in the ECB data level
(CE1FMn) or DECB data level (IDECFA) before issuing ATTAC.
Reattach the block detached by a previous DETAC ...,TYPE=ADDRESS. The block
storage address must match the storage address at the specified ECB level or
in the specified DECB. Store the required storage address in the ECB storage
level (CE1CRn) or DECB storage level (IDECDAD) before issuing ATTAC.
Reattach the block from the most recent DETAC ...,TYPE=ADDRESS at the
specified ECB level or for the specified DECB.
Synonym for FA.
UNCOND|COND
Where:
|
UNCOND If there is no detached block to reattach, dump and exit the entry. UNCOND is
the default. When type is not STACK, UNCOND is ignored (whether it is
specified or the default) and ATTAC behaves as for COND below.
250
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ATTAC
COND
|
|
If there is no detached block to reattach, return to application.
[R07|Dn|Rn]
ECB storage level, where:
Rn
Register containing the level value (use LA Rn,Dn). Use general register 14 (RDA) or 0
through 7 (RAC through RGF). The register symbol must start with the character R.
Level symbol. D0 for level 0, D1 for level 1, and so on up to DF for level 15.
Dn
ACPDB
Same as TYPE=(ACPDB,COND). This format uses general register 7 (RGF) as the register
|
containing the ECB storage level.
12.1.2 Description
| Use the ATTAC macro to reattach a storage block to an ECB or DECB storage level. The block must
| previously have been detached by a DETAC macro from the same level.
Each ATTAC macro call reattaches one block. You must specify the same level with ATTAC macro as was
specified in the DETAC macro for that block.
The value you supply with the TYPE= parameter must be compatible with the value of the TYPE=
parameter used with DETAC.
12.1.3 Register use
| When you use register notation, ATTAC uses general register 14 (RDA) to indicate the ECB level or DECB.
ATTAC does not corrupt any other registers.
12.1.4 Loss of control
ATTAC does not cause the entry to lose control.
12.1.5 Example
This example shows how you could use DETAC to detach the block at level 2, then later use ATTAC to
reattach the block with the matching file address.
MVC
DETAC
.
.
.
MVC
ATTAC
EBW(8),CE1FA2
SAVE FILE ADDRESS
LEVEL=D2,TYPE=ADDRESS DETACH BLOCK AT LEVEL 2
CE1FA2(8),EBW
LEVEL=D2,TYPE=FA
SET UP FILE ADDRESS
REATTACH BLOCK
12.1.6 Related information
12.4, “DETAC – Detach a storage block” on page 257
ALCS Application Programming Guide.
Chapter 12. Macros and callable services
251
CRUSA
12.2 CRUSA – Release storage blocks from specified levels
12.2.1 Format
| [label] CRUSA {level_list[,TEST=level,PARAM=label2]|DECB={decb_addr|(reg)}}
label
Any valid assembler label.
|
level_list
The ECB levels at which storage blocks are to be released, if attached. Specify up to 16 levels in the
format S0=level, S1=level . . . up to SF=level, where level is a level number: 0 for level D0, 1 for level
D1, and so on, up to F for level 15. All these keyword parameters are optional.
TEST=level,PARAM=label2
Either include or omit both parameters.
level
label2
A level number: 0 for level D0, 1 for level D1, and so on. CRUSA tests this level after it
releases any blocks specified in level_list.
The label to where CRUSA branches if level number level is not in use (there is no block
attached).
| DECB={decb_addr|(reg)}
|
Address of the DECB to test for an attached storage block, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
12.2.2 Description
| Use the CRUSA macro to release storage blocks from an entry if the specified ECB levels are in use. (CRUSA
| does not return an error if the levels are not in use). Alternatively use the CRUSA macro to release a
| storage block attached to a DECB.
Diagnostic, Modification, and Tuning Information
The CRUSA macro has a request type of RELCC. In traces and dumps, RELCC is shown as the macro name
instead of CRUSA. If you specify TEST= and PARAM= parameters, LEVTA follows RELCC in the macro trace.
End of Diagnostic, Modification, and Tuning Information
12.2.3 Register use
CRUSA does not corrupt any registers.
12.2.4 Loss of control
CRUSA does not cause the entry to lose control.
252
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
CRUSA
12.2.5 Example
| The following example shows how you could use CRUSA to release the storage blocks (if any) attached to
| ECB levels 0 (D0) and 3 (D3):
CRUSA S=,S1=3
FREE-UP LEVELS D AND D3
12.2.6 Related information
12.24, “LEVTA – Test a storage level” on page 305.
12.28, “RELCC – Release a storage block” on page 387.
Chapter 12. Macros and callable services
253
DECBC
|
12.3 DECBC – Manage data event control blocks
|
12.3.1 Format
| [label] DECBC FUNC=CREATE,DECB={decb_addr|(reg1)}[,NAME={decb_name|(reg2)}]
|
[,ERROR=error_label][,RC={R15|(reg5)}]
| or:
| [label] DECBC FUNC=LOCATE,DECB={decb_addr|(reg1)},NAME={decb_name|(reg2)}
|
[,ERROR=error_label][,RC={R15|(reg5)}]
| or:
| [label] DECBC FUNC=RELEASE,{DECB={decb_addr|(reg1)}|NAME={decb_name|(reg2)}}
|
[,ERROR=error_label][,RC={R15|(reg5)}]
| or:
| [label] DECBC FUNC=SWAPBLK,DECB={decb_addr|(reg1)},LEVEL={Dn|(reg4)}
|
[,ERROR=error_label][,RC={R15|(reg5)}]
| or:
| [label] DECBC FUNC=VALIDATE,DECB=(reg1)[,WKREG={R14|(reg3)}]
|
[,ERROR=error_label][,RC={R15|(reg5)}]
| label
|
Any valid assembler label.
| FUNC={CREATE|LOCATE|RELEASE|SWAPBLK|VALIDATE}
|
The action to be performed. Specify one of:
|
|
|
|
|
|
|
|
CREATE
LOCATE
Create a new DECB.
Locate a previously allocated DECB with a name matching the value specified by the
NAME= parameter.
RELEASE Release the DECB specified by the DECB= or NAME= parameter if the DECB is not
currently in-use.
SWAPBLK Exchange storage block and related information between the DECB specified by the
DECB= parameter and the ECB storage level specified by the LEVEL= parameter.
VALIDATE Determine whether the DECB specified by the DECB= parameter is a valid DECB.
| DECB={decb_addr|(reg1)}
|
For FUNC=CREATE and FUNC=LOCATE, specifies where the address of the DECB is to be
|
returned. For all other actions specifies the address of a valid DECB. Specify one of:
|
|
|
decb_addr
(reg1)
Assembler label of a 4-byte field containing the address of the DECB.
Register containing the address of the DECB. Use general register 14 (RDA) or 15
(RDB) or 0 through 7 (RAC through RGF).
| NAME={decb_name|(reg2)}
|
The name associated with a DECB. Specify one of:
254
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
DECBC
|
|
|
decb_name Assembler label of a 16-byte field containing the name.
(reg2)
Register containing the address of a 16-byte field containing the name. Use general
register 14 (RDA) or 15 (RDB) or 0 through 7 (RAC through RGF).
| LEVEL={Dn|(reg4)}
|
ECB storage level, where:
|
|
|
Dn
(reg4)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA) or
15 (RDB) or 0 through 7 (RAC through RGF).
| ERROR=error_label
|
The Assembler label of a routine to branch to if an error is encountered during processing of the
|
DECBC macro. If ERROR= is not specified and an error is encountered, control will return to the next
|
sequential instruction (NSI). You should then check the contents of the register specified on the RC=
|
parameter for the associated return code.
| RC={R15|(reg5)}
|
The register where the return code should be placed upon completion of the DECBC macro. Use
|
general register 14 (RDA) or 15 (RDB) or 0 through 7 (RAC through RGF). You can test the return
|
code that DECBC sets using symbols defined by the IDECB DSECT as follows:
|
DECBC_OK
The request completed successfully.
|
|
DECBC_DUPNAME
The NAME= parameter specified on FUNC=CREATE contains a DECB
name which already exists for this ECB.
|
|
DECBC_NOTFOUND
A DECB matching the input search criteria could not be found when
specifying FUNC=LOCATE.
|
|
DECBC_NOTVALID
The DECB specified on FUNC=VALIDATE did not reference a valid DECB
address, or else the DECB is no longer in-use.
| WKREG={R14|(reg3)}
|
This parameter is not used by ALCS but is included for compatability with TPF.
|
12.3.2 Description
| Use DECBC FUNC=CREATE to allocate storage for a single DECB, initialize it and attach it to the ECB.
| You may optionally associate a name with the created DECB. DECBC FUNC=CREATE returns the
| address of the DECB in the field or general register specified by the DECB= parameter.
| Use DECBC FUNC=RELEASE to detach a DECB from the ECB so that the storage is available for other
| DECBs.
| Use DECBC FUNC=LOCATE to determine the address of a DECB from its associated name.
| Use DECBC FUNC=VALIDATE to determine whether a storage address you provide is the address of a
| valid DECB.
| Use DECBC FUNC=SWAPBLK to move any storage block attached to the DECB to an ECB storage
| level, and any block attached to that ECB storage level to the DECB.
| Use the IDECB macro to reference individual fields in the DECB. 12.22, “IDECB – Data event control block
| DSECT” on page 303 describes the IDECB macro.
Chapter 12. Macros and callable services
255
DECBC
| Application programs that reference DECBs using ALCS macros such as FILUC or RELCC must use the
| address of the DECB not its name. If an application program has not maintained the DECB address it can
| obtain it using DECBC FUNC=LOCATE
|
12.3.3 Register use
|
|
|
|
DECBC allows you to pass both input and output parameters in a general register. You may also specify a
general register which DECBC will use to provide a return code. If you do not specify a return code DECBC
uses general register 15 (RDB). For compatability with TPF you may specify a work register with DECBC
FUNC=RELEASE but this is ignored by ALCS.
|
12.3.4 Loss of control
| DECBC does not cause the entry to lose control.
|
12.3.5 Example
| The following example shows how you use DECBC to get a DECB and attach to it a size L1 storage block.
|
|
|
|
|
|
|
|
|
DNAME
DECBC FUNC=CREATE,
NAME=DNAME,
DECB=(R3)
GETCC DECB=(R3),
SIZE=L1
.
.
.
DC
CL16'MODEL DECB'
CREATE A DECB
SPECIFY DECB NAME
RETURN ADDRESS IN R3
DECB ADDRESS
SIZE CODE
DECB NAME
| The following example shows how you use DECBC to release the storage block and the DECB.
|
|
|
|
|
|
|
|
DNAME
RELCC DECB=(R3)
DECBC FUNC=RELEASE,
NAME=DNAME
.
.
.
DC
CL16'MODEL DECB'
RELEASE THE BLOCK
RELEASE THE DECB
SPECIFY DECB NAME
DECB NAME
12.3.6 Related information
| 12.22, “IDECB – Data event control block DSECT” on page 303.
| -- Heading 'EB0EB' unknown --.
| ALCS Installation and Customization.
256
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
DETAC
12.4 DETAC – Detach a storage block
12.4.1 Format
| [label] DETAC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
|
[,TYPE={STACK|ADDRESS|ACPDB}][,CHECK={YES|NO}]
or formats for compatibility with TPF:
| [label] DETAC [R+7|Dn|Rn|DECB={decb_addr|(reg2)}][,ACPDB][,CHECK={YES|NO}]
or:
[label]
DETAC ACPDB
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level from which the storage block is detached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register that contains the level value (use LA reg1,Dn). Use general register 14 (RDA), or
0 through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB from which the storage block is detached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
TYPE={STACK|ADDRESS|ACPDB}
STACK
ADDRESS
ACPDB
The detached block can be reattached using ATTAC TYPE=STACK.
The detached block can be reattached using ATTAC TYPE=FA, ATTAC TYPE=SA, or ATTAC
TYPE=ANY.
Synonym for TYPE=ADDRESS.
CHECK={YES|NO}
This parameter is provided for compatibility with TPF. ALCS ignores it.
TPF compatibility
|
|
|
When you use CHECK=YES (or the default) in TPF, DETAC checks that a storage block is attached
and dumps with exit if not. In ALCS, DETAC ignores this parameter and does not check for an
attached block.
[R07|Dn|Rn]
ECB storage level, where:
Dn
Rn
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA Rn,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
Chapter 12. Macros and callable services
257
DETAC
|
|
ACPDB
Same as TYPE=ACPDB. This format uses general register 7 (RGF) as the register containing the
ECB storage level.
12.4.2 Description
| Use the DETAC macro to detach a storage block temporarily from an ECB or DECB storage level. DETAC
| does not release the block. You can later use ATTAC to reattach the block at the same level.
12.4.3 Register use
When you use register notation with the LEVEL= parameter, DETAC loads the level value into general
register 14 (RDA). DETAC does not corrupt any other registers.
12.4.4 Loss of control
This macro does not cause the entry to lose control.
12.4.5 Example
The following example shows how you could use DETAC to detach the block at level 2 and later use ATTAC
to reattach the block with the matching file address.
MVC
DETAC
.
.
.
MVC
ATTAC
EBW(8),CE1FA2
D2,ADDRESS
SAVE FILE ADDRESS
DETACH BLOCK AT LEVEL 2
CE1FA2(8),EBW
D2,FA
SET UP FILE ADDRESS
REATTACH BLOCK
12.4.6 Related information
12.1, “ATTAC – Attach a previously detached storage block” on page 250.
ALCS Application Programming Guide.
258
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FAC8C
|
12.5 FAC8C – Compute an online 8-byte file address
|
12.5.1 Format
| [label] FAC8C PARMS={label|(reg)}
| label
|
Any valid assembler label.
| PARMS={label|(reg)}
|
The address of a storage area containing a parameter block (DSECT IFAC8 describes the format of
|
the parameter block), where:
|
|
|
|
label
(reg)
Assembler label of the storage area.
Register containing the address of the storage area. Use general register 14 (RDA) or 15
(RDB) or 0 through 7 (RAC through RGF).
12.5.2 Description
| When you use a DECB for managing DASD I/O, you need to specify an 8-byte file address in the data level.
| You may use the FAC8C macro to compute an 8-byte file address in 4x4 format. FAC8C provides a similar
| function to the file address compute programs FACE or FACS which create 4-byte file addresses.
| You must set field IFACTYP in the parameter block to indicate whether a record type symbol (IFACFCS)
| or a record type value (IFACFCE) is provided before issuing FAC8C. You must also supply a record ordinal
| number (IFACORD) and a fixed-file record type value/symbol (IFACRNB/IFACREC).
| FAC8C returns information in the parameter block. The return code field (IFACRET) indicates whether the
| call is successful. If it is, the file address is returned in field IFACADR and the maximum valid ordinal
| number for the specified record type in field IFACMAX.
|
Diagnostic, Modification, and Tuning Information
| The FAC8C macro has a request type of RONIC. In traces and dumps, RONIC is shown as the macro name
| instead of FAC8C.
|
|
End of Diagnostic, Modification, and Tuning Information
12.5.3 Register use
| FAC8C uses general register 14 (RDA), to hold the base of the parameter block. It does not corrupt any
| other registers.
|
12.5.4 Loss of control
| FAC8C does not cause the entry to lose control.
Chapter 12. Macros and callable services
259
FAC8C
|
12.5.5 Example
| The following example shows how you could use FAC8C to calculate the file address of a fixed-file record.
| The fixed file record type is #XMPRI and the record ordinal number is 95. The example stores the
| successfully created file address in a DECB.
|
|
|
|
|
|
|
|
|
|
IFAC8
MVI
MVC
MVC
FAC8C
REG=R7
IFACTYP,IFACFCE
INDICATE RECORD TYPE VALUE
IFACRNB,=AL2(#XMPRI) SET RECORD TYPE VALUE
IFACORD,=FL8'95'
SET RECORD ORDINAL
PARMS=(R7)
CALCULATE FILE ADDRESS
CLI
BNE
IFACRET,IFACNRM
...
FILE ADDRESS OK
BRANCH IF NOT
MVC
IDECFA,IFACADR
MOVE FILE ADDRESS TO DECB
|
12.5.6 Related information
|
|
|
|
12.23, “IFAC8 – FAC8C parameter block DSECT” on page 304.
12.22, “IDECB – Data event control block DSECT” on page 303.
-- Heading 'FACEC' unknown --.
ALCS Installation and Customization.
260
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FA4X4C
|
12.6 FA4X4C – Convert a file address
|
12.6.1 Format
| [label] FA4X4C ACTION={4TO8|8TO4},FA4={label1|(reg1)},FA8={label2|(reg2)}[,ERROR=label3]
| label
|
Any valid assembler label.
| ACTION={4TO8|8TO4}
|
The type of file address conversion to perform. Specify one of:
|
|
|
|
|
|
4TO8
8TO4
The FA4= parameter contains a 4-byte file address which is used as input to the file
address conversion. The corresponding 8-byte file address in 4x4 format will be returned in
the location represented by the FA8= parameter.
The FA8= parameter contains an 8-byte file address in 4x4 format which is used as input
to the file address conversion. The corresponding 4-byte file address will be returned in the
location represented by the FA4= parameter.
| FA4={label1|(reg1)}
|
For ACTION=4TO8 specifies the location of a 4-byte file address.
|
For ACTION=8TO4 specifies the location where a 4-byte file address is to be returned. Specify one of:
|
|
|
label1
(reg1)
Assembler label of a 4-byte field.
Register containing the address of a 4-byte field. Use general register 14 (RDA) or 15
(RDB) or 0 through 7 (RAC through RGF).
| FA8={label2|(reg2)}
|
For ACTION=4TO8 specifies the location where an 8-byte file address is to be returned.
|
For ACTION=8TO4 specifies the location of an 8-byte file address. Specify one of:
|
|
|
label2
(reg2)
Assembler label of an 8-byte field.
Register containing the address of an 8-byte field. Use general register 14 (RDA) or 15
(RDB) or 0 through 7 (RAC through RGF).
| ERROR=label3
|
The Assembler label of a routine that is given control if an error is encountered during processing of
|
the FA4X4C macro. If ERROR= is not specified and an error is encountered, control will return to the
|
next sequential instruction (NSI).
|
12.6.2 Description
| Use the FA4X4C macro to convert a 4-byte file address to an 8-byte file address in 4x4 format or to convert
| an 8-byte file address in 4x4 format to a 4-byte file address.
|
12.6.3 Register use
| FA4X4C uses general registers 14 (RDA) and 15 (RDB) to manipulate the file addresses. It does not
| corrupt any other registers.
|
12.6.4 Loss of control
| FA4X4C does not cause the entry to lose control.
Chapter 12. Macros and callable services
261
FA4X4C
|
12.6.5 Example
| The following example shows how you could use FA4X4C to convert file address at ECB data level 3 to an
| 8-byte file address in 4x4 format and place it in the ECB work area.
|
|
|
|
|
LA
R4,CE1FM3
FA4X4C ACTION=4TO8,
FA4=(R4),
FA8=EBW
LOCATE 4-BYTE FILE ADDRESS
CONVERT TO 4X4 FORMAT
INPUT POINTER IN R4
OUTPUT TO ECB WORK AREA
12.6.6 Related information
| 12.3, “DECBC – Manage data event control blocks” on page 424.
| 12.22, “IDECB – Data event control block DSECT” on page 303.
| ALCS Installation and Customization.
262
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FILEC
12.7 FILEC – Write a DASD record
12.7.1 Format
| [label] FILEC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
or positional parameter format:
| [label] FILEC {Dn|(reg1)}
or format for TPF compatibility:
| [label] FILEC {Dn|DECB={decb_addr|(reg2)}[,TAG={Y|N}][,GDS={Y|N}]
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the storage block to be written is attached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the storage block to be written is attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
TAG={Y|N}
Request ALCS to:
Y
N
Move the program name into the storage block before writing it to DASD.
Do not move the program name into the storage block before writing it to DASD.
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.7.2 Description
Use the FILEC macro to write a DASD record.
| FILEC writes the contents of a storage block to a file address. The storage block must be attached at the
| ECB or DECB storage level specified, and must be the same size as the DASD record. You specify the
file address in the associated data level.
FILEC detaches the block immediately, so the storage level can be reused after the macro is executed.
The application program must not reference the released block.
| The ECB or DECB data level must also contain the record ID. Optionally, it can contain the record code
check (RCC). To avoid checking the RCC, set the RCC in the data level to binary zeros.
Chapter 12. Macros and callable services
263
FILEC
FILEC does not unhold the file address. If the file address is held, you should use either FILUC or a
separate UNFRC monitor-request macro to unhold it.
Note: The entry that issues this macro does not wait for the actual I/O operation to complete. This
allows it to initiate large numbers of I/O operations in a relatively short time (for example, by issuing GETCC
followed by FILEC in a loop). This can degrade the performance of all entries because:
5 Reads to a particular DASD can be delayed, waiting for the backlog of writes to complete.
5 ALCS must retain the data in its I/O buffers until the I/O completes. A backlog of writes for one entry
reduces the buffers available for I/O for other entries.
If your program needs to issue large numbers of DASD writes, you should try to slow down the entry and
avoid building up a backlog. To do this, you could include DEFRC or DLAYC macros. You could also use
FILNC, with an associated WAITC.
12.7.3 Register use
| When you use register notation, FILEC uses general register 14 (RDA) to indicate the ECB level or DECB.
FILEC does not corrupt any other registers.
12.7.4 Loss of control
This macro can cause the entry to lose control. The application program cannot check correct completion
| of this write. FILEC does not increment the I/O counter, so a wait macro does not wait for the completion
| of I/O initiated by FILEC.
12.7.5 Example
The following example shows how you could use FILEC to write a DASD record. The new record contents
are in the storage block attached at level 7. The example assumes that the data level already contains
the file address in EBCFA7:
L
MVC
MVI
FILEC
R1,CE1CR7
EBCID7(2),(R1)
EBCRC7,
D7
LOAD BLOCK ADDRESS
SET UP ID
CLEAR RCC (NO CHECK)
AND FILE THIS RECORD
12.7.6 Related information
-- Heading 'DEFRC' unknown --- Heading 'DLAYC' unknown -12.31, “UNFRC – Unhold a file address” on page 319
All other read and write macros (-- Heading 'FILKW' unknown -- through 12.15, “FIWHC – Read a DASD
record, hold the file address, and wait for I/O completion” on page 281).
ALCS Installation and Customization (ENTWRT option of the SCTGEN macro) and ALCS Application
Programming Guide.
264
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FILNC
12.8 FILNC – Write a DASD record and retain the attached storage
block
12.8.1 Format
| [label] FILNC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
{Dn|(reg)}
or positional parameter format:
| [label] FILNC {Dn|(reg1)}
or format for TPF compatibility:
| [label] FILNC {Dn|DECB={decb_addr|(reg2)}[,TAG={Y|N}][,GDS={Y|N}]
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the storage block to be written is attached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the storage block to be written is attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
TAG={Y|N}
Request ALCS to:
Y
N
Move the program name into the storage block before writing it to DASD.
Do not move the program name into the storage block before writing it to DASD.
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.8.2 Description
Use the FILNC macro to write a DASD record without releasing the associated storage block. FILNC also
allows the application to check that the write has completed successfully.
| FILNC writes the contents of the storage block to a file address. The storage block must be attached at
| the ECB or DECB storage level specified, and must be the same size as the DASD record. You specify
the file address in the associated data level.
| Unlike FILEC and FILUC, FILNC does not detach the storage block from the ECB or DECB storage level.
However, the block must not be referenced until data transfer has completed. For this reason, FILNC
Chapter 12. Macros and callable services
265
FILNC
increments the ECB I/O counter, so you can check the successful completion of the operation using an
implied wait macro.
| The ECB or DECB data level must also contain the record ID. Optionally, it can contain the record code
check (RCC). To avoid checking the RCC, set the RCC in the data level to binary zeros.
FILNC does not unhold the file address. If the file address is held, use a separate UNFRC macro to unhold
the file address.
12.8.3 Register use
| When you use register notation, FILNC uses general register 14 (RDA) to indicate the ECB level or DECB.
FILNC does not corrupt any other registers.
12.8.4 Loss of control
| This macro can cause the entry to lose control. Subsequently, the entry must issue a wait macro to test
| for completion of the I/O.
| If an I/O error occurs, FINDC sets indicators in the ECB I/O error indicator field CE1SUG and in field
| EBCSDn in the ECB data level or field IDECSUD in the DECB. These are described in ALCS Application
Programming Guide, together with a description of how your program should check these indicators.
12.8.5 Example
The following example shows how you could use FILNC to write a DASD record. The new record contents
are in the storage block attached at level 7. The example assumes that the data level already contains
the file address in EBCFA7 (the wait error routine checks whether the file address is invalid). If the I/O
completes successfully, the example releases the storage block:
ERRRTN
L
MVC
MVI
FILNC
WAITC
R1,CE1CR7
EBCID7(2),(R1)
EBCRC7,
D7
ERRRTN
LOAD BLOCK ADDRESS
SET UP ID
CLEAR RCC (NO CHECK)
FILE THE RECORD
AND WAIT FOR I/O
RELCC
...
EQU
TM
BO
D7
RELEASE BLOCK
V
EBCSD7,CXSGAE
...
FILE ADDRESS INVALID
BRANCH IF YES
12.8.6 Related information
12.31, “UNFRC – Unhold a file address” on page 319
Other read and write macros (12.7, “FILEC – Write a DASD record” on page 263 through 12.15, “FIWHC –
Read a DASD record, hold the file address, and wait for I/O completion” on page 281).
ALCS Application Programming Guide
266
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FILSC
12.9 FILSC – Write a single copy of a DASD record
Compatibility
ALCS supports this macro only for compatibility. It occurs in some existing application programs
originally developed for TPF. ALCS supports this macro to simplify porting these applications to ALCS.
IBM recommends that you do not use this macro in ALCS.
12.9.1 Format
| [label] FILSC {Dn|,DECB={decb_addr|(reg)}},{P|D}[,TAG={Y|N}][,GDS={Y|N}]
label
Any valid assembler label.
| Dn ECB storage level to which the storage block to be written is attached. Use D0 for level 0, D1 for level
|
1, and so on up to DF for level 15.
| DECB={decb_addr|(reg)}
|
DECB to which the storage block to be written is attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
{P|D}
Write the prime (P) or duplicate (D) copy of the record. ALCS ignores this parameter.
TAG={Y|N}
Request ALCS to:
Y
N
Move the program name into the storage block before writing it to DASD.
Not to move the program name into the storage block before writing it to DASD.
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.9.2 Description
In TPF, FILSC writes a specified copy of a record to a duplex database. Since ALCS requires both copies
of a record to be identical, the ALCS implementation of FILSC ignores the prime/duplicate specification and
writes both copies. The ALCS FILSC macro generates a FILEC macro instruction.
Diagnostic, Modification, and Tuning Information
IBM recommends that you do not use this macro in ALCS. However, if you do, note that the FILSC macro
has a request type of FILEC. In traces and dumps, FILEC is shown as the macro name instead of FILSC.
End of Diagnostic, Modification, and Tuning Information
Chapter 12. Macros and callable services
267
FILSC
12.9.3 Register use
| When you use register notation, FILSC uses general register 14 (RDA) to indicate the ECB level or DECB.
FILSC does not corrupt any other registers.
12.9.4 Loss of control
This macro can cause the entry to lose control. The application program cannot check correct completion
of this write. FILSC does not increment the I/O counter, so an implied wait macro does not wait for the
completion of I/O initiated by FILSC.
12.9.5 Example
No example provided. IBM recommends that you do not use this macro in ALCS.
12.9.6 Related information
Other read and write macros (12.7, “FILEC – Write a DASD record” on page 263 through 12.15, “FIWHC –
Read a DASD record, hold the file address, and wait for I/O completion” on page 281).
268
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FILUC
12.10 FILUC – Write a DASD record and unhold the file address
12.10.1 Format
| [label] FILUC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
or positional parameter format:
| [label] FILUC {Dn|(reg1)}
or format for TPF compatibility:
| [label] FILUC {Dn|DECB={decb_addr|(reg2)}[,TAG={Y|N}][,GDS={Y|N}]
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the storage block to be written is attached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the storage block to be written is attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
TAG={Y|N}
Request ALCS to:
Y
N
Move the program name into the storage block before writing it to DASD.
Do not move the program name into the storage block before writing it to DASD.
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.10.2 Description
Use the FILUC macro to write a DASD record and unhold the file address.
| FILUC writes the contents of a storage block to a file address. FILUC also unholds the file address. The
| storage block must be attached at the ECB or DECB storage level specified, and must be the same size
| as the DASD record.
The file address in the associated data level must have been held (by FIWHC or FINHC). FILUC detaches
the block immediately, so you can reuse the storage level after FILUC is executed. The application
program must not reference the released block.
| The ECB or DECB data level must also contain the record ID. Optionally, it can contain the record code
check (RCC). To avoid checking the RCC, set the RCC in the data level to binary zeros.
Chapter 12. Macros and callable services
269
FILUC
12.10.3 Register use
| When you use register notation, FILUC uses general register 14 (RDA) to indicate the ECB level or DECB.
FILUC does not corrupt any other registers.
12.10.4 Loss of control
This macro can cause the entry to lose control.
The application program cannot check that this operation has completed correctly. FILUC does not
increment the I/O counter, so an implied wait macro does not wait for the completion of I/O initiated by
FILUC.
12.10.5 Example
The following example shows how you could use FILUC to write a DASD record and unhold the file
address.
MVC
EBCID3(3),...
SET UP EXPECTED RECORD ID AND RCC
MVC
EBCFA3,...
SET UP FILE ADDRESS
FIWHC D3,...
FIND RECORD, HOLD, AND WAIT
.
.
(instructions that update the record)
.
FILUC D3
FILE AND UNHOLD
12.10.6 Related information
Other read and write macros (12.7, “FILEC – Write a DASD record” on page 263 through 12.15, “FIWHC –
Read a DASD record, hold the file address, and wait for I/O completion” on page 281).
12.31, “UNFRC – Unhold a file address” on page 319.
270
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FINDC
12.11 FINDC – Read a DASD record
12.11.1 Format
| [label] FINDC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
or positional parameter format:
| [label] FINDC {Dn|(reg1)}
or format for TPF compatibility:
| [label] FINDC {Dn|DECB={decb_addr|(reg2)}[,GDS={Y|N}]
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the DASD record to be read is to be attached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the DASD record to be read is to be attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.11.2 Description
Use the FINDC macro to read a DASD record.
| The FINDC macro reads a DASD record whose file address is in the ECB or DECB data level. FINDC gets
| an appropriately sized storage block for use as an input buffer, and attaches the block to the associated
| ECB or DECB storage level. There must not be a storage block already attached at the level.
| Before issuing FINDC, store the expected record ID and record code check (RCC) in the ECB or DECB
| data level. When the read completes, ALCS checks them against the actual ID and RCC. If they are not
| the same, ALCS sets indicators in the gross and detail error indicators (see the ALCS Application
Programming Guide.). To inhibit the RCC check, store binary zeros as the expected RCC in the data
level. To inhibit the ID check and the RCC check, store binary zeros in both fields of the data level.
| You must follow this macro with a wait macro to check for correct completion of the I/O operation, before
| your application makes any reference to the storage level. On return from the wait macro, you can load
| the block address from the appropriate storage level.
Chapter 12. Macros and callable services
271
FINDC
Use FINDC when you want to read more than one record before continuing processing. An application
program can issue a series of FINDC macros, followed by an implied wait macro (for example, FINWC or
WAITC).
12.11.3 Register use
| When you use register notation, FINDC uses general register 14 (RDA) to indicate the ECB level or DECB.
FINDC does not corrupt any other registers.
12.11.4 Loss of control
| This macro can cause the entry to lose control. Subsequently, the entry must issue a wait macro to test
| for completion of the I/O.
| If an I/O error occurs, FINDC sets indicators in the ECB I/O error indicator field CE1SUG and in field
| EBCSDn in the ECB data level or field IDECSUD in the DECB. These are described in the ALCS
Application Programming Guide, which also describes how your program should test these indicators.
12.11.5 Example
In the following example, an application program uses FINDC to read two DASD records. They are
| fixed-file records with type #XMPRI. The application program reads record ordinal 5 on ECB level 3 (D3)
| and record ordinal 6 on ECB level 4 (D4).
Before issuing each FINDC, it uses FACE to calculate the file address of the record. After issuing both
FINDCs, the application program issues WAITC to wait for I/O completion and test for I/O errors:
272
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FINDC
ERRRTN
LA
LA
LA
ENTRC
R,5
R6,#XMPRI
R7,CE1FA3
FACE
LOAD ORDINAL NUMBER
LOAD RECORD TYPE
ADDRESS DATA LEVEL
AND CALCULATE FILE ADDRESS
LTR
BZ
R,R
...
FILE ADDRESS OK
BRANCH IF NOT
MVC
EBCID3(3),...
FINDC D3
SET UP EXPECTED RECORD ID AND RCC
FIND THE RECORD ON D3
L
LA
LA
ENTRC
R,6
R6,#XMPRI
R7,CE1FA4
FACE
LOAD ORDINAL NUMBER
LOAD RECORD TYPE
ADDRESS DATA LEVEL
AND CALCULATE FILE ADDRESS
LTR
BZ
R,R
...
FILE ADDRESS OK
BRANCH IF NOT
MVC
EBCID4(3),...
FINDC D4
SET UP EXPECTED RECORD ID AND RCC
FIND THE RECORD ON D4
WAITC ERRRTN
WAIT FOR I/O ON D3 AND D4
.
.
.
EQU
TM
BO
V
EBCSD3,CXSGIE
...
ID ERROR ON D3
BRANCH IF YES
TM
BO
EBCSD4,CXSGIE
...
ID ERROR ON D4
BRANCH IF YES
12.11.6 Related information
-- Heading 'WAITC' unknown -Other read and write macros (12.7, “FILEC – Write a DASD record” on page 263 through 12.15, “FIWHC –
Read a DASD record, hold the file address, and wait for I/O completion” on page 281).
ALCS Application Programming Guide
Chapter 12. Macros and callable services
273
FINHC
12.12 FINHC – Read a DASD record and hold the file address
12.12.1 Format
| [label] FINHC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
or positional parameter format:
| [label] FINHC {Dn|(reg1)}
or format for TPF compatibility:
| [label] FINHC {Dn|DECB={decb_addr|(reg2)}[,GDS={Y|N}]
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the DASD record to be read is to be attached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the DASD record to be read is to be attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.12.2 Description
Use the FINHC macro to read a DASD record and hold the file address.
Note: Incautious use of record hold can cause severe performance degradation, deadlocks, and other
problems.
| The FINHC macro reads the DASD record whose address is in the ECB or DECB data level, and holds the
| file address. The ALCS Application Programming Guide describes record hold and when you might need
| to use it.
| FINHC gets an appropriately sized storage block for use as an input buffer, and attaches it to the ECB or
| DECB storage level. There must not be a storage block already attached at the level. Also, the file
| address must not already be held.
| Before issuing FINHC, store the expected record ID and record code check (RCC) in the ECB or DECB
| data level. When the read completes, ALCS checks them against the actual ID and RCC. If they are not
| the same, ALCS sets indicators in the gross and detail error indicators. To inhibit the RCC check, store
binary zeros as the expected RCC in the data level. To inhibit the ID check and the RCC check, store
binary zeros in both fields of the data level.
274
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FINHC
| You must follow this macro with a wait macro to check for correct completion of the I/O operation, before
| your application makes any reference to the storage level. On return from the wait macro, you can load
| the block address from the appropriate storage level.
Any file address held by FINHC must subsequently be unheld by a FILUC or UNFRC macro issued by the
same entry.
If the find does not complete successfully (if the wait error branch is taken), the file address may not be
held. If there is a storage block attached (use LEVTA macro to test this), the file address is held. If there is
no block attached, it is not held.
12.12.3 Register use
| When you use register notation, FINDC uses general register 14 (RDA) to indicate the ECB level or DECB.
FINHC does not corrupt any other registers.
12.12.4 Loss of control
| This macro can cause the entry to lose control. Subsequently, the entry must issue a wait macro to test
| for completion of the I/O.
| If an I/O error occurs, FINDC sets indicators in the ECB I/O error indicator field CE1SUG and in field
| EBCSDn in the ECB data level or field IDECSUD in the DECB. These are described in the ALCS
Application Programming Guide, which also describes how your program should test these indicators.
12.12.5 Example
The following example shows how you could read two DASD fixed-file records with a record type of
| #XMPRI. It uses FINHC to read record ordinal 5 on ECB level 3 (D3) and to hold the file address. It uses
| FINDC to read record ordinal 6 on ECB level 4 (D4). Before it issues each FIND macro, the example uses
FACE to calculate the file address of the record. After issuing both FINDCs , the application program issues
WAITC to wait for I/O completion and test for I/O errors.
Chapter 12. Macros and callable services
275
FINHC
ERRRTN
LA
LA
LA
ENTRC
R,5
R6,#XMPRI
R7,CE1FA3
FACE
LOAD ORDINAL NUMBER
LOAD RECORD TYPE
ADDRESS DATA LEVEL
AND CALCULATE FILE ADDRESS
LTR
BZ
R,R
...
FILE ADDRESS OK
BRANCH IF NOT
MVC
EBCID3(3),...
FINHC D3
SET UP EXPECTED RECORD ID AND RCC
FIND AND HOLD RECORD ON D3
L
LA
LA
ENTRC
R,6
R6,#XMPRI
R7,CE1FA4
FACE
LOAD ORDINAL NUMBER
LOAD RECORD TYPE
ADDRESS DATA LEVEL
AND CALCULATE FILE ADDRESS
LTR
BZ
R,R
...
FILE ADDRESS OK
BRANCH IF NOT
MVC
EBCID4(3),...
FINDC D4
SET UP EXPECTED RECORD ID AND RCC
FIND THE RECORD ON D4
WAITC ERRRTN
WAIT FOR I/O ON D3 AND D4
.
.
.
EQU
V
CRUSA S=4
LEVTA LEVEL=3,
NOTUSED=ERRRTN1
RELEASE BLOCK ON D4, IF ANY
ANY BLOCK ON LEVEL 3
BRANCH IF NOT
RCUNC D3
ERRRTN1
EQU
.
.
.
X
UNHOLD FILE ADDRESS AND RELEASE X
BLOCK
V
12.12.6 Related information
Other read and write macros (12.7, “FILEC – Write a DASD record” on page 263 through 12.15, “FIWHC –
Read a DASD record, hold the file address, and wait for I/O completion” on page 281).
12.31, “UNFRC – Unhold a file address” on page 319.
-- Heading 'WAITC' unknown --.
ALCS Application Programming Guide
276
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FINSC
12.13 FINSC – Read a single copy of a DASD record
Compatibility
ALCS supports this macro only for compatibility. It occurs in some existing application programs
originally developed for TPF. ALCS supports FINSC to simplify porting these applications to ALCS.
IBM recommends that you do not use this macro in ALCS.
12.13.1 Format
| [label] FINSC {Dn|,DECB={decb_addr|(reg)}},{P|D}[,GDS={Y|N}]
label
Any valid assembler label.
| Dn ECB storage level to which the DASD record to be read is to be attached. Use D0 for level 0, D1 for
|
level 1, and so on up to DF for level 15.
| DECB={decb_addr|(reg)}
|
DECB to which the DASD record to be read is to be attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
{P|D}
Read the prime (P) or duplicate (D) copy of the record. ALCS ignores this parameter.
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.13.2 Description
In TPF, FINSC reads a specified copy of a record from a duplex database.
ALCS ensures that both copies of a record are identical, so the ALCS implementation of FINSC ignores the
prime or duplicate specification. The ALCS FINSC macro generates a FINDC macroinstruction.
Diagnostic, Modification, and Tuning Information
The FINSC macro has a request type of FINDC. In traces and dumps, FINDC is shown as the macro name
instead of FINSC.
End of Diagnostic, Modification, and Tuning Information
12.13.3 Register use
| When you use register notation, FINSC uses general register 14 (RDA) to indicate the ECB level or DECB.
FINSC does not corrupt any other registers.
Chapter 12. Macros and callable services
277
FINSC
12.13.4 Loss of control
This macro can cause the entry to lose control. Because of this, after issuing FINSC, the entry must issue
an implied wait macro to test for completion of the I/O.
12.13.5 Example
No example provided. IBM recommends that you do not use this macro in ALCS.
12.13.6 Related information
Other read and write macros (12.7, “FILEC – Write a DASD record” on page 263 through 12.15, “FIWHC –
Read a DASD record, hold the file address, and wait for I/O completion” on page 281).
278
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FINWC
12.14 FINWC – Read a DASD record and wait for I/O completion
12.14.1 Format
| [label] FINWC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}},ERROR=error_routine
or positional parameter format:
| [label] FINWC {Dn|(reg1)},error_routine
or format for TPF compatibility:
| [label] FINWC {Dn|,DECB={decb_addr|(reg2)},error_routine[,GDS={Y|N}]
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the DASD record to be read is to be attached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the DASD record to be read is to be attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
ERROR=error_routine
Label which FINWC branches to if it detects an error.
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.14.2 Description
Use the FINWC macro to read a DASD record and wait until I/O completes.
| FINWC reads the record whose file address is in the ECB or DECB data level.
| FINWC gets an appropriately sized storage block for use as an input buffer, and attaches it to the ECB or
| DECB storage level. There must not be a storage block already attached at the level.
| You can load the address of the block from the storage level after this macro.
| Before issuing FINWC, store the expected record ID and record code check (RCC) in the ECB or DECB
| data level. When the read completes, ALCS checks them against the actual ID and RCC. If they are not
| the same, ALCS sets indicators in the gross and detail error indicators.
To inhibit the RCC check, store binary zeros as the expected RCC in the data level. To inhibit the record
ID check and the RCC check, store binary zeros in both fields of the data level.
Chapter 12. Macros and callable services
279
FINWC
FINWC is an implied wait macro. Control does not return to the entry until the I/O operation completes
| (whether or not there are errors). FINWC also waits for the I/O completion of any previous I/O macros for
| which a wait is required (such as FINDC). If FINWC detects an error, it branches to error_routine.
12.14.3 Register use
| When you use register notation, FINWC uses general register 14 (RDA) to indicate the ECB level or DECB.
FINWC does not corrupt any other registers.
12.14.4 Loss of control
| This macro waits for I/O to complete.
| If an I/O error occurs, FINWC sets indicators in the ECB I/O error indicator field CE1SUG and in field
| EBCSDn in the ECB data level or field IDECSUD in the DECB. These are described in the ALCS
Application Programming Guide, which also describes how your program should test these indicators.
12.14.5 Example
| The following example shows how you could use FINWC to read a DASD record on ECB level 3 (D3). It is
the fixed-file record with type #XMPRI and ordinal 5. Before it issues FINWC, the example uses FACE to
calculate the file address of the record.
ERRRTN
LA
LA
LA
ENTRC
R,5
R6,#XMPRI
R7,CE1FA3
FACE
LOAD ORDINAL NUMBER
LOAD RECORD TYPE
ADDRESS DATA LEVEL
AND CALCULATE FILE ADDRESS
LTR
BZ
R,R
...
FILE ADDRESS OK
BRANCH IF NOT
MVC
EBCID3(3),...
SET UP EXPECTED RECORD ID
AND RCC
FIND THE RECORD ON D3
FINWC D3,ERRRTN
.
.
.
EQU
V
CRUSA S=3
.
.
.
RELEASE BLOCK IF ANY
12.14.6 Related information
Other read and write macros (12.7, “FILEC – Write a DASD record” on page 263 through 12.15, “FIWHC –
Read a DASD record, hold the file address, and wait for I/O completion” on page 281).
ALCS Application Programming Guide
280
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FIWHC
12.15 FIWHC – Read a DASD record, hold the file address, and wait for
I/O completion
12.15.1 Format
| [label] FIWHC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}},ERROR=error_routine
or positional parameter format:
| [label] FIWHC {Dn|(reg1)},error_routine
or format for TPF compatibility:
| [label] FIWHC {Dn|,DECB={decb_addr|(reg2)},error_routine[,GDS={Y|N}]
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the DASD record to be read is to be attached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the DASD record to be read is to be attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
ERROR=error_routine
Label to which FIWHC branches if it detects an error.
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.15.2 Description
Use the FIWHC macro to read a DASD record, hold the file address, and wait until I/O completes.
| FIWHC reads the record whose address is in the specified ECB or DECB data level and holds the file
| address.
| FIWHC gets an appropriately sized storage block for use as an input buffer, and attaches it to the ECB or
| DECB storage level. There must not be a storage block already attached at the level.
| You can load the address of the block from the storage level after this macro.
| Before issuing FIWHC, store the expected record ID and record code check (RCC) in the ECB or DECB
| data level. When the read completes, ALCS checks them against the actual ID and RCC. If they are not
| the same, ALCS sets indicators in the gross and detail error indicators
Chapter 12. Macros and callable services
281
FIWHC
To inhibit the RCC check, store binary zeros as the expected RCC in the data level. To inhibit the record
ID check and the RCC check, store binary zeros in both fields of the data level.
FIWHC is an implied wait macro. Control does not return to the entry until the I/O operation completes
| (whether or not there are errors). FIWHC also waits for the I/O completion of any previous I/O macros for
which an implied wait is required (such as FINDC). If FIWHC detects an error, it branches to error_routine.
The same entry that issues a FIWHC to hold a file address must subsequently issue a FILUC or UNFRC to
unhold the file address.
If the find does not complete successfully (ALCS takes the wait error branch), the file address may not be
held. If there is a storage block attached (use LEVTA to test this), the file address is held. If there is no
block attached, it is not held.
12.15.3 Register use
| When you use register notation, FIWHC uses general register 14 (RDA) to indicate the ECB level or DECB.
FIWHC does not corrupt any other registers.
12.15.4 Loss of control
| This macro waits for I/O to complete.
| If an I/O error occurs, FIWHC sets indicators in the ECB I/O error indicator field CE1SUG and in field
| EBCSDn in the ECB data level or field IDECSUD in the DECB. These are described in the ALCS
Application Programming Guide, which also describes how your program should test these indicators.
12.15.5 Example
| The following example shows how you could use FIWHC to read a DASD record on ECB level 3 (D3) and
| to hold the file address. It is the fixed-file record with type #XMPRI and ordinal 5. Before it issues FIWHC,
the example uses FACE to calculate the file address of the record.
282
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FIWHC
ERRRTN
LA
LA
LA
ENTRC
R,5
R6,#XMPRI
R7,CE1FA3
FACE
LOAD ORDINAL NUMBER
LOAD RECORD TYPE
ADDRESS DATA LEVEL
AND CALCULATE FILE ADDRESS
LTR
BZ
R,R
...
FILE ADDRESS OK
BRANCH IF NOT
MVC
EBCID3(3),...
FIWHC D3,ERRRTN
SET UP EXPECTED RECORD ID
AND RCC
FIND THE RECORD ON D3
.
.
.
EQU
V
LEVTA LEVEL=3,
NOTUSED=ERRRTN1
ANY BLOCK ON LEVEL 3
BRANCH IF NOT
RCUNC D3
ERRRTN1
EQU
.
.
.
UNHOLD FILE ADDRESS AND
RELEASE BLOCK
X
X
V
12.15.6 Related information
Other read and write macros (12.7, “FILEC – Write a DASD record” on page 263 through 12.15, “FIWHC –
Read a DASD record, hold the file address, and wait for I/O completion” on page 281).
12.31, “UNFRC – Unhold a file address” on page 319.
ALCS Application Programming Guide
Chapter 12. Macros and callable services
283
FNDPC
12.16 FNDPC – Read a DASD record with control fields
Product-Sensitive Programming Interface
TPF compatibility
Do not use FNDPC in programs that must be compatible with TPF.
12.16.1 Format
| [label] FNDPC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
or positional parameter format:
| [label] FNDPC {Dn|(reg1)}
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the DASD record to be read is to be attached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the DASD record to be read is to be attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
12.16.2 Description
| Use the FNDPC macro to read a DASD record when you need to access the record control fields in the
| record. You can also use FNDPC to read a pool record without activating the ALCS pool integrity checks.
| The FNDPC macro reads a DASD record whose file address is in the ECB or DECB data level.
| FINPC gets an appropriately sized storage block for use as an input buffer, and attaches it to the ECB or
| DECB storage level. There must not be a storage block already attached at the level.
| Before issuing FNDPC, store the expected record ID and record code check (RCC) in the ECB or DECB
| data level. When the read completes, ALCS checks them against the actual ID and RCC. If they are not
| the same, ALCS sets indicators in the gross and detail error indicators (see ALCS Application
Programming Guide). To inhibit the RCC check, store binary zeros as the expected RCC in the data
level. To inhibit the ID check and the RCC check, store binary zeros in both fields of the data level.
284
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
FNDPC
You must follow FNDPC with an implied wait macro to check for correct completion of the I/O operation,
before your application makes any reference to the storage level. On return from the implied wait macro,
you can load the block address from the storage level.
12.16.3 Register use
| When you use register notation, FINWC uses general register 14 (RDA) to indicate the ECB level or DECB.
FNDPC does not corrupt any other registers.
12.16.4 Loss of control
| This macro can cause the entry to lose control. Subsequently, the entry must issue a wait macro to test
| for completion of the I/O.
| If an I/O error occurs, FINDC sets indicators in the ECB I/O error indicator field CE1SUG and in field
| EBCSDn in the ECB data level or field IDECSUD in the DECB. These are described in ALCS Application
Programming Guide, which also explains how your program should test these indicators.
12.16.5 Example
The following example shows how you could use FNDPC to read a fixed record with type #WAARI as part of
| an AAA policing routine. The application program reads record ordinal 5 on ECB level 3 (D3)
Before issuing the FNDPC, it uses FACE to calculate the file address of the record. After issuing the FNDPC,
the application program issues WAITC to wait for I/O completion and test for I/O errors:
ERRRTN
LA
LA
LA
ENTRC
R,5
R6,#WAARI
R7,CE1FA3
FACE
LOAD ORDINAL NUMBER
LOAD RECORD TYPE
ADDRESS DATA LEVEL
AND CALCULATE FILE ADDRESS
LTR
BZ
R,R
...
FILE ADDRESS OK
BRANCH IF NOT
MVC
EBCID3(3),...
FNDPC D3
SET UP EXPECTED RECORD ID AND RCC
FIND THE RECORD ON D3
WAITC ERRRTN
WAIT FOR I/O ON D3 TO COMPLETE
LH
BLKIC
LH
A
RSRS
CLC
BH
SPACE
DROP
R15,CE1CT3
LOAD RECORD SIZE
BLOCKINFO,SIZE=(R15) OBTAIN BLOCK INFORMATION
R14,BLKCSO(,R14) GET OFFSET TO RECORD CONTROL FIELDS
R14,CE1CR3
ADD BASE OF THE RECORD
REG=R14
RECORD CONTROL FIELD DSECT
RSPFST,...
IS THE TIME EXPIRED
...
BRANCH IF NOT
1
R14
DROP THE RECORD CONTROL FIELD DSECT
.
.
.
EQU
TM
BO
V
EBCSD3,CXSGIE
...
ID ERROR ON D3
BRANCH IF YES
Chapter 12. Macros and callable services
285
FNDPC
12.16.6 Related information
-- Heading 'BLKIC' unknown --.
-- Heading 'FACE' unknown --.
-- Heading 'RS0RS' unknown --.
-- Heading 'WAITC' unknown --.
ALCS Application Programming Guide
End of Product-Sensitive Programming Interface
286
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
GDSNC
12.17 GDSNC – Open or close a general data set
12.17.1 Format
| [label] GDSNC {Dn|(reg1)}|,DECB={decb_addr|(reg2)}},{O|C}
|
[,SIZE={S|L|4|U|Ln|(reg3)}]
[,RCT={A|N}]
[,WORK={NO|YES}]
Or format for compatibility with TPF
| [label] GDSNC {Dn|,DECB={decb_addr|(reg2)}},{O|C}
|
[,SIZE={S|L|4|U}]
[,RCT={A|N}]
[,WORK={NO|YES}]
label
Any valid assembler label.
|
{Dn|(reg1)}
ECB data level to contain the file address of a record in the general data set, where:
Dn
(reg1)
Level symbol: D0 for level 0, D1 for level 1, and so on up to DF for level 15.
Register containing the level value (use LA reg,Dn). Use general register 0 through 7
(RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to contain the file address of a record in the general data set, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
{O|C}
Open (O) or close (C) general data set. For Open (O), general register 14 (RDA) contains the
address of the data set name. The data set name can be up to 16 characters. If it is less than 16
characters, it must be padded to the right with spaces (blanks) to 16 characters.
| SIZE={S|L|4|U|Ln|(reg3)}
Size of records in the data set, where:
|
S
L
4
U
Ln
(reg3)
For record size L1
For record size L2
For record size L4
For any record size
Size symbol: L0, L1, and so on up to L8
Register containing the size value (use LA reg,Ln). Use general register 0 through 7 (RAC
through RGF).
TPF compatibility
|
5 Do not use the last two options (Ln and (reg3)) in programs that must be compatible with TPF.
5 In some versions of TPF, the default size is SIZE=4, not SIZE=L.
Chapter 12. Macros and callable services
287
GDSNC
RCT={A|N}
ALCS ignores this parameter – all ALCS general data sets are VSAM data sets.
TPF compatibility
TPF systems support two types of physical record address on general data sets. This parameter
specifies which type, as follows:
A
N
TPF-type physical record addresses.
Standard physical record addresses.
WORK={NO|YES}
When GDSNC is opening a general data set, WORK= specifies the location of a relative record number.
This is a fullword binary number. The relative record number of the first record in the data set is zero.
GDSNC returns the file address of the corresponding record. Specify one of:
|
|
NO
YES
Relative record number is in the first fullword of CE1FXn for the specified ECB data level,
or IDECFX0 in the specified DECB.
Relative record number is in the fullword immediately following the 16-character data set
name addressed by general register 14 (RDA).
When closing a general data set, GDSNC ignores this parameter.
12.17.2 Description
Use the GDSNC macro to open or close a general data set. The GDSNC open function also gets the file
address of a record in the general data set.
To access records in a general data set, the entry must first open the data set by issuing:
GDSNC Dn,O,....
This sets one of the following return codes in general register 14 (RDA):
0
4
8
Open completed and file address computed without error. The entry can read or write the
record.
Open completed without error, but the relative record number is invalid. The entry can use the
general data set, but must first get a valid file address using GDSRC.
Open failed. The entry cannot use the general data set.
If the return code is zero, the macro returns the file address of the record with the specified relative record
number. The application program can then use a FIND or FILE macro to read or write that general data
set record.
After opening the general data set and reading or writing one record, the entry can access other records in
| the data set. For each record, the entry issues GDSRC. GDSRC gets the file address, initializes the ID and
| RCC fields in the ECB or DECB data level as required, and issues a FIND or FILE macro to read or write
it.
When the entry has finished processing the general data set (and before the entry exits), it must close the
general data set by issuing:
GDSNC Dn,C,....
For more information about accessing general data sets, see ALCS Application Programming Guide.
288
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
GDSNC
TPF compatibility
|
|
The TPF GDSNC open function saves information in the ECB or DECB data level which subsequent
GDSRC macros and the GDSNC close function use.
|
To ensure compatibility with TPF, do not modify the contents of the ECB fields CE1FMn, CE1FCn,
CE1FHn, or CE1FRn between opening and closing a general data set.
If you use different data levels for accessing the general data set, be sure to transfer the contents of
these fields to the required data level before issuing GDSRC, or closing the data set, or both. (See -Heading 'FLIPC' unknown --).
Diagnostic, Modification, and Tuning Information
The GDSNC macro has a request type of RAISC. In traces and dumps, RAISC is shown as the macro name
instead of GDSNC.
End of Diagnostic, Modification, and Tuning Information
12.17.3 Register use
GDSNC sets a return code in general register 14 (RDA) (see the Description section above). It also corrupts
general register 15 (RDB). GDSNC does not corrupt any other registers.
12.17.4 Loss of control
This macro does not cause the entry to lose control.
12.17.5 Example
The following example shows how you could use GDSNC to open a general data set with the data set name
| “EXAMPLE.DATA.SET” using ECB data level 4 (D4). It then reads some records from the data set, and
finally closes it. The data set contains size L1 records.
VVVVVVVV OPEN THE GENERAL DATA SET
SPACE 1
LA
R14,DSNAME
LOAD DSNAME ADDRESS
SR
R,R
LOAD RRN OF FIRST RECORD
ST
R,CE1FX4
AND SAVE FOR GDSNC
GDSNC D4,O,
OPEN THE GENERAL DATA SET
SIZE=S,
RECORD SIZE IS L1
WORK=NO
RECORD NUMBER IS IN CE1FX4
CH
R14,=Y(4)
TEST RETURN CODE
BH
ERROR1
OPEN FAILED - ERROR
BE
ERROR2
BAD RRN - GO CLOSE THE DATA SET
SPACE 1
X
X
Figure 159 (Part 1 of 2). Opening a general data set
Chapter 12. Macros and callable services
289
GDSNC
VVVVVVVV OPEN WORKED OK - READ THE FIRST RECORD
SPACE 1
MVC
CE1FA4(3),IDRCC
SET UP RECORD ID AND RCC
FINWC D4,
AND READ THE RECORD
ERROR2
CLOSE DATA SET IF FIND ERROR
.
.
(process the record)
.
SPACE 1
VVVVVVVV READ THE NEXT RECORD
SPACE 1
LA
R14,DSNAME
LOAD DSNAME ADDRESS
LA
R,1
LOAD RRN OF NEXT RECORD
ST
R,CE1FX4
AND SAVE FOR GDSRC
GDSRC D4,O,
GET THE NEXT FILE ADDRESS
SIZE=S,
RECORD SIZE IS L1
WORK=NO
RECORD NUMBER IS IN CE1FX4
CH
R14,=Y(4)
TEST RETURN CODE
BH
ERROR1
OPEN FAILED - ERROR
BE
ERROR2
BAD RRN - GO CLOSE THE DATA SET
MVC
CE1FA4(3),IDRCC
SET UP RECORD ID AND RCC
FINWC D4,
AND READ THE RECORD
ERROR2
CLOSE DATA SET IF FIND ERROR
.
.
(process the record)
.
SPACE 1
VVVVVVVV ALL RECORDS PROCESSED - CLOSE THE DATA SET
SPACE 1
GDSNC D4,C,SIZE=S
CLOSE THE DATA SET
.
.
.
SPACE 1
VVVVVVVV ERROR ON GENERAL DATA SET - CLOSE IT
SPACE 1
ERROR2
EQU
V
GDSNC D4,C,SIZE=S
CLOSE THE DATA SET
.
.
.
DSNAME
DC
CL16'EXAMPLE.DATA.SET'
IDRCC
DC
C'XX',X''
X
X
X
X
Figure 159 (Part 2 of 2). Opening a general data set
12.17.6 Related information
12.18, “GDSRC – Compute a general data set record file address” on page 373.
ALCS Application Programming Guide
290
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
GDSRC
12.18 GDSRC – Compute a general data set record file address
12.18.1 Format
| [label] GDSRC {Dn|(reg1)}|DECB={decb_addr|(reg2)}
|
[,SIZE={S|L|4|U|Ln|(reg3)}]
|
[,WORK={NO|YES}]
| Or format for compatibility with TPF
| [label] GDSRC {Dn|DECB={decb_addr|(reg2)}
|
[,SIZE={S|L|4|U}]
[,WORK={NO|YES}]
label
Any valid assembler label.
{Dn|(reg1)}
|
ECB data level to contain the file address of the general data set, where:
Dn
(reg1)
Level symbol: D0 for level 0, D1 for level 1, and so on up to DF for level 15.
Register containing the level value (use LA reg,Dn). Use general registers 0 through 7
(RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to contain the file address of the general data set, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 0 through 7 (RAC
through RGF).
| SIZE={S|L|4|U|Ln|(reg3)}
Size of records in the data set, where:
|
S
L
4
U
Ln
(reg3)
For record size L1
For record size L2
For record size L4
For any record size
Size symbol: L0, L1, and so on up to L8
Register containing the size value (use LA reg,Ln). Use general registers 0 through 7
(RAC through RGF).
TPF compatibility
|
5 Do not use the last two options (Ln and (reg3)) in programs that must be compatible with TPF.
5 In some versions of TPF, the default size is SIZE=4, not SIZE=L.
WORK={NO|YES}
Specifies the location of a relative record number. The relative record number is a fullword binary
number. The relative record number of the first record in the data set is zero. GDSRC returns the file
address of the corresponding record. Specify one of:
|
|
NO
Relative record number is in the first fullword of CE1FXn for the specified ECB data level,
or IDECFX0 in the specified DECB
Chapter 12. Macros and callable services
291
GDSRC
YES
Relative record number is in the fullword immediately following the 16-character data set
name addressed by general register 14 (RDA).
12.18.2 Description
Use the GDSRC macro to get the file address of a record in the general data set.
On entry to GDSRC, general register 14 (RDA) contains the address of the data set name. The data set
| name can be up to 16 characters. If it is less than 16 characters, it must be left justified and padded with
| blanks.
For more information about accessing general data sets, see ALCS Application Programming Guide.
Diagnostic, Modification, and Tuning Information
The GDSRC macro has a request type of RAISC. In traces and dumps, RAISC is shown as the macro name
instead of GDSRC.
End of Diagnostic, Modification, and Tuning Information
12.18.3 Register use
GDSRC Dn,... sets one of the following return codes in general register 14 (RDA):
0
4
8
File address computed without error. The entry can read or write the record.
The relative record number is invalid. If you are processing the records in the general data set
sequentially, this return code indicates that there are no more records.
The general data set is no longer usable.
It also uses general register 15 (RDB). GDSRC does not corrupt any other registers.
12.18.4 Loss of control
This macro does not cause the entry to lose control.
12.18.5 Example
See the example for the GDSNC macro (see 12.17, “GDSNC – Open or close a general data set” on
page 370).
12.18.6 Related information
12.17, “GDSNC – Open or close a general data set” on page 370.
ALCS Application Programming Guide
292
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
GETCC
12.19 GETCC – Get a storage block
12.19.1 Format
| [label] GETCC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
|
,SIZE={Ln|bytes|(reg3)}
[,FILL={++|hh}]
or:
| [label] GETCC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
|
,{ID={record_id|(reg4)}|IDSYM=symbol}[,,{P|O|q|RTP={q|(reg5)}}]
[,FILL={++|hh}]
or positional parameter format:
| [label] GETCC {Dn|(reg1)},{Ln|(reg3)}
or formats for TPF compatibility:
| [label] GETCC {Dn|,DECB={decb_addr|(reg2)}},{Ln|(reg3)}
|
[,COMMON={NO|YES|PROTECTED}][,FILL={++|hh}]
or:
| [label] GETCC {Dn|DECB={decb_addr|(reg2)}}
|
,SIZE={bytes|(reg3)}
|
[,COMMON={NO|YES|PROTECTED}][,FILL={++|hh}]
| or:
| [label] GETCC {Dn|,DECB={decb_addr|(reg2)}}
|
,ID={record_id|(reg4)}[,{P|O|q|RTP={q|(reg5)}}]
|
[,COMMON={NO|YES|PROTECTED}][,FILL={++|hh}]
label
Any valid assembler label.
|
|
|
LEVEL={Dn|(reg1)}
ECB storage level to which the storage block is to be attached, where:
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA) or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the storage block is to be attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 14 (RDA) or 0 through
7 (RAC through RGF).
Chapter 12. Macros and callable services
293
GETCC
| SIZE={Ln|bytes|(reg3)}
Block size. Specify one of:
Ln
Size symbol: L0, L1, and so on up to L8, or LX. LX requests the largest block size that
your ALCS installation supports.
Attention
bytes
|
(reg3)
The block sizes that ALCS supports are an ALCS generation option. You must specify a
block size that is defined in your system.
Self-defining term, symbol, or expression that resolves to the required number of bytes.
You must request at least 146 bytes. GETCC gives you the smallest block that contains this
number of bytes.
Register that contains either a block size value (load the register using LA reg3,Ln) or the
required number of bytes. Use general register 15 (RDB), or 0 through 7 (RAC through
RGF).
| FILL={00|hh}
|
Initialization value for the new storage block. This defaults to binary zeros but you can specify any
|
hexadecimal value hh.
|
TPF compatibility
|
|
|
The default for this parameter in TPF varies by installation. On most TPF systems, the default is
binary zeros as for ALCS but for some TPF installations the default is to leave the block
uninitialized.
| ID={record_id|(reg4)}
One of:
record_id record ID in one of the following formats:
X'xxxx'
Where xxxx is 1 to 4 hexadecimal digits. If required, GETCC adds leading zeros
to make up two bytes.
C'cc'
Where cc is two characters. If required, GETCC adds a leading byte of binary
zeros to make up two bytes.
B'bbbb'
Where bbbb is 1 to 16 binary digits. If required, GETCC adds leading zeros to
make up two bytes.
|
(reg4)
Note that GETCC accepts some other formats for the record ID but they are not
recommended.
Register containing the record ID in bytes 2 and 3. Use general register 15 (RDB) or 0
through 7 (RAC through RGF).
IDSYM=symbol
Assembler language symbol that ALCS resolves to a 2-byte pool record ID.
| COMMON={NO|YES|PROTECTED}
This parameter is provided for compatibility with TPF. ALCS ignores it.
| P|O|q|RTP={q|(reg5)}
Record ID qualifier. Each record ID defined to ALCS can have one or more qualifiers associated with
it. A qualifier has a value from 0 to 9. You can use the ID qualifier to distinguish between different
record types that have the same record ID. Use one of the following:
|
|
P
O
q
(reg5)
294
Equivalent to record ID qualifier 0
Equivalent to record ID qualifier 1
A single decimal digit (0 through 9).
Register containing the record ID qualifier. Use general register 0 through 7 (RAC through
RGF).
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
GETCC
Record IDs and qualifiers are defined by the ALCS DASD generation (see ALCS Installation and
Customization).
12.19.2 Description
| Use the GETCC macro to get a storage block and attach it to an ECB or DECB storage level.
GETCC gets a storage block, clears it to binary zeros, or to the initialization value specified by the FILL=
parameter, and saves its address in the specified storage level. The storage level must not already
contain the address of a storage block (that is, no block may be already attached at that level).
| GETCC returns the address of the block in general register 14 (RDA) and in the ECB storage level (CE1CRn)
| or the DECB storage level (IDECDAD). GETCC returns the block size in the ECB storage level (CE1CCn) or the
| DECB storage level (IDECCT).
| Do not specify the size explicitly (Ln or reg3) if both of the following are true:
The storage block is for a particular record, and:
The record has a unique record ID (that is, only one record size has the record ID). The ALCS DASD
generation specifies record IDs. See ALCS Installation and Customization for a description.
Instead, use the ID= or IDSYM= parameter to specify the record ID. After issuing GETCC, get the block
size information from the storage level. This method ensures that the program does not need to change if
the record size changes.
12.19.3 Register use
GETCC loads the size value into general register 15 (RDB), if required. It returns the block address in
general register 14 (RDA). GETCC does not corrupt any other registers.
12.19.4 Loss of control
GETCC does not cause the entry to lose control.
12.19.5 Example
| The following example shows how you could use GETCC to get a size L1 storage block and attach it to ECB
| level 3 (D3):
GETCC D3,L1
LR
R6,R14
GET STORAGE BLOCK
SAVE BLOCK ADDRESS
| The following example gets a working storage block and attaches it to ECB level 14 (DE). The block size
is the size of DASD records that have the record ID AA:
GETCC DE,ID=C'AA'
LR
R6,R14
LH
R7,CE1CCE
GET STORAGE BLOCK
SAVE BLOCK ADDRESS
LOAD BLOCK LENGTH IN BYTES
12.19.6 Related information
12.2, “CRUSA – Release storage blocks from specified levels” on page 357.
Chapter 12. Macros and callable services
295
GETCC
12.24, “LEVTA – Test a storage level” on page 305.
12.28, “RELCC – Release a storage block” on page 387.
ALCS Installation and Customization.
296
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
GETFC
12.20 GETFC – Get a pool-file record address
12.20.1 Format
| [label] GETFC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
|
,{ID={record_id|(reg3)}|IDSYM=symbol}
|
[,RTP={+|n|(reg5)}]
|
[,TERM={Long|Short}]
|
[,SIZE={Ln|(reg4)}]
|
[,BLOCK=NO|,BLOCK=YES[,FILL={++|hh}]]
[,ERROR={NO|YES}]
or:
| [label] GETFC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
,TERM={Long|Short}
|
|
,SIZE={Ln|(reg4)}
[,BLOCK=NO|,BLOCK=YES[,FILL={++|hh}]]
[,ERROR={NO|YES}]
or format for TPF compatibility:
| [label] GETFC {Dn|,DECB={decb_addr|(reg2)}}
|
[,{P|O|RTP={+|n|(reg5)}}]
|
,ID={record_id|(reg3)}
|
[,ERROR={NO|YES}]
|
[,BLOCK=NO|,BLOCK=YES[,FILL={++|hh}]]
|
[,COMMON={NO|YES}]
label
Any valid assembler label.
|
LEVEL={Dn|(reg1)}
ECB storage level to contain the newly dispensed file address, where:
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to contain the newly dispensed file address, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 14 (RDA) or 0 through
7 (RAC through RGF).
| ID={record_id|(reg3)}
One of:
record_id record ID in one of the following formats:
X'xxxx'
Where xxxx is 1 to 4 hexadecimal digits. If required, GETFC adds leading zeros
to make up two bytes.
Chapter 12. Macros and callable services
297
GETFC
C'cc'
B'bbbb'
|
(reg3)
Where cc is two characters. If required, GETFC adds a leading byte of binary
zeros to make up two bytes.
Where bbbb is 1 to 16 binary digits. If required, GETFC adds leading zeros to
make up two bytes.
GETFC accepts some other formats for the record ID but they are not recommended.
Register containing the record ID in bytes 2 and 3. Use general register 15 (RDB), or 0
through 7 (RAC through RGF).
IDSYM=symbol
Assembler language symbol that resolves to a 2-byte pool record ID.
TERM={Long|Short}
Long-term (Long) or short-term (Short) pool.
| SIZE={Ln|(reg4)}
Block size. The sizes that ALCS supports are an ALCS generation option. Specify one of:
|
Ln
(reg4)
Size symbol: L1, L2, and so on up to L8.
Register containing the size value (use LA reg4,Ln). Use general register 0 through 7
(RAC through RGF).
BLOCK={NO|YES}
|
NO
YES
Do not get a storage block.
Get a storage block and attach it to the ECB or DECB storage level.
ERROR={NO|YES}
NO
YES
No return
Following
CC=0
CC=3
code is issued following GETFC.
GETFC, one of the following return codes is issued:
A pool-file record address has been returned.
No pool-file record address has been returned.
| RTP={0|n|(reg5)}
Record ID qualifier (a binary number in the range 0 through 9). Specify one of:
|
|
|
n
(reg5)
A single decimal digit.
Register containing the record ID qualifier. Use general register 0 (RAC) through 7 (RGF).
COMMON={NO|YES}
Allowed only with BLOCK=YES. Provided for compatibility with TPF. This parameter is ignored by
ALCS (unless you erroneously specify it with BLOCK=NO).
| FILL={00|hh}
|
Allowed only with BLOCK=YES, this parameter allows you to specify the initialization value for the
new storage block. The default is binary zeros but you can specify any hexadecimal value hh.
TPF compatibility
The default for this parameter in TPF varies by installation. On most TPF systems, the default is
binary zeros as for ALCS but for some TPF installations the default is to leave the block
uninitialized.
[P|O]
Parameter P is equivalent to RTP=0, parameter O is equivalent to RTP=1.
298
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
GETFC
12.20.2 Description
Use the GETFC macro to get the file address of an unused pool file record.
| GETFC decides which pool type to use. To do this it uses the GETFC parameters together with information
from the ALCS DASD generation. ALCS DASD generation is described in ALCS Installation and
Customization.
Ensure that the GETFC parameters:
5 Identify a pool type uniquely. For example, if the generation defines two pool record sizes that have
the same record ID, GETFC must specify the record identifier and the record size. Alternatively, you
can specify the record ID with a qualifier, using the RTP= or P|O parameter.
5 Identify a pool type that exists. For example, if the generation defines only one pool record type that
has a particular record ID, GETFC must not specify that record ID with a different record size.
If GETFC does not identify a pool type uniquely or if the pool type does not exist, the program can fail at
execution time.
If you are using ID= or IDSYM=, the GETFC TERM= and SIZE= parameters can conflict with the ALCS
DASD generation definition for the record type. GETFC resolves these conflicts as follows:
5 If GETFC TERM= conflicts with the ALCS DASD generation definition, and GETFC does not specify
SIZE=, the entry exits with a system error. (See ALCS Messages and Codes.)
5 If GETFC TERM= conflicts with the ALCS DASD generation definition, and GETFC specifies SIZE=, GETFC
uses TERM= and SIZE= to select the pool type (even if SIZE= also conflicts with the ALCS DASD
generation definition).
5 If GETFC SIZE= conflicts with the ALCS DASD generation definition, GETFC uses the SIZE= parameter
and gets a long-term pool record.
| If BLOCK=YES, GETCC follows GETFC in the macro trace.
12.20.3 Register use
When you use register notation, GETFC loads the block address into general register 14 (RDA), if required.
It loads the record ID into the low-order two bytes of general register 15 (RDB), if required.
| If you do not use the SIZE=(reg4) parameter, ALCS loads the block size code into the high-order byte of
general register 15 (RDB).
GETFC does not corrupt any other registers.
12.20.4 Loss of control
GETFC can cause the entry to lose control.
12.20.5 Example
| The following example shows how you could use GETFC to get a pool-file record address and store this file
| address in ECB data level 7 (D7). It also gets a suitably sized storage block (the same size as the record)
| and attaches it to ECB storage level 7. The GETFC macroinstruction identifies the pool by specifying the
record ID as X'2D2D'.
Chapter 12. Macros and callable services
299
GETFC
GETFC D7,ID=X'2D2D',
BLOCK=YES
L
R6,CE1CR7
LH
R7,CE1CC7
GET FILE ADDRESS
AND STORAGE BLOCK
LOAD BLOCK ADDRESS
LOAD BLOCK LENGTH IN BYTES
X
12.20.6 Related information
12.19, “GETCC – Get a storage block” on page 375.
12.29, “RELFC – Release a pool-file record address” on page 389.
ALCS Installation and Customization.
300
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
HLDTC
12.21 HLDTC – Test if file address is held
12.21.1 Format
| [label] HLDTC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}},
{INHOLD=address1[,NOHOLD=address2]|
NOHOLD=address2[,INHOLD=address1]}
or positional parameter format:
| [label] HLDTC {Dn|(reg1)},
{INHOLD=address1[,NOHOLD=address2]|
NOHOLD=address2[,INHOLD=address1]}
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level containing the file address, where:
|
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB containing the file address, where:
|
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 14 (RDA) or 0 through
7 (RAC through RGF).
address1
Label to which HLDTC branches if the file address is held by this ECB.
| address2
|
Label to which HLDTC branches if the file address is not held by this ECB.
12.21.2 Description
| Use this macro to check if the file address is held by this entry. If the file address is held by this entry,
| HLDTC branches to the address specified by INHOLD, if present.
| If the file address is not held by this entry, HLDTC branches to the address specified by NOHOLD, if
present.
You must specify at least one of INHOLD or NOHOLD.
| No error checking is performed. If the file address is invalid, the NOHOLD branch is taken (or the
INHOLD branch is not taken).
12.21.3 Register use
| When you use register notation, HLDTC uses general register 14 (RDA) to indicate the ECB level or DECB.
| HLDTC does not corrupt any other registers.
Chapter 12. Macros and callable services
301
HLDTC
12.21.4 Loss of control
This macro can cause the entry to lose control.
12.21.5 Example
The following program shows different uses of HLDTC
HLDT
REL
ERR1
ERR2
ERR3
ERR4
ERR5
ERR6
ERR7
BEGIN
PRINT
HLDTC
LA
LA
LA
ENTRC
LTR
BZ
HLDTC
FINWC
HLDTC
RELCC
FIWHC
HLDTC
EQU
UNFRC
EXITC
SERRC
SERRC
SERRC
SERRC
SERRC
SERRC
SERRC
FINIS
END
NAME=HLDT
GEN
D7,INHOLD=ERR1
SHOULD NOT BRANCH
R,28
LOAD ORDINAL NUMBER
R6,#CPRCR
LOAD RECORD TYPE
R7,CE1FA7
ADDRESS DATA LEVEL
FACE
AND CALCULATE FILE ADDRESS
R,R
FILE ADDRESS OK
ERR2
BRANCH IF NOT
D7,INHOLD=ERR3
SHOULD NOT BRANCH
D7,ERR4
GET THE RECORD
D7,INHOLD=ERR5
SHOULD NOT BRANCH
D7
RELEASE THE BLOCK
D7,ERR6
NOW HOLD IT
D7,NOHOLD=ERR7,INHOLD=REL
V
SHOULD COME HERE
D7
UNHOLD THE RECORD
,
E,EE1
F/A = E,EE2
FACE ERROR
E,EE3
F/A OK - RECORD NOT READ
E,EE4
FIND ERROR
E,EE5
RECORD READ WITHOUT HOLD
E,EE6
FIWHC ERROR
E,EE7
RECORD IS NOT HELD
,
,
12.21.6 Related information
12.12, “FINHC – Read a DASD record and hold the file address” on page 274.
12.15, “FIWHC – Read a DASD record, hold the file address, and wait for I/O completion” on page 281.
12.31, “UNFRC – Unhold a file address” on page 319.
302
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
IDECB
|
12.22 IDECB – Data event control block DSECT
|
12.22.1 Format
|
IDECB REG=reg
| REG=reg
|
Base register for DSECT addressability.
|
12.22.2 Description
| Use the IDECB DSECT macro to reference fields in the DECB. Application programs which reference
| DECBs must call this DSECT.
| The ALCS Application Programming Guide describes fields in the DECB.
|
12.22.3 Register use
| Not applicable. IDECB does not generate executable instructions.
|
12.22.4 Loss of control
| Not applicable. IDECB does not generate executable instructions.
|
12.22.5 Example
| No example provided. IDECB is a DSECT macro.
|
12.22.6 Related information
| -- Heading 'BEGIN' unknown --.
| ALCS Application Programming Guide.
Chapter 12. Macros and callable services
303
IFAC8
|
12.23 IFAC8 – FAC8C parameter block DSECT
|
12.23.1 Format
| [label] IFAC8 REG=reg
| REG=reg
|
Base register for DSECT addressability.
|
12.23.2 Description
| Use the IFAC8 DSECT macro when calling the FAC8C macro to reference input and output fields in the
| parameter block.
| The IFAC8 DSECT provides the following symbols:
|
|
|
|
|
|
|
IFACORD
IFACREC
IFACRNB
IFACTYP
IFACADR
IFACMAX
IFACRET
double word (8-byte) ordinal number requested.
8-byte symbolic record type.
halfword numeric record type.
1-byte call type indicator.
8-byte file address.
double word (8-byte) maximum ordinal number for this record type.
1-byte call return code.
| IFACTYP must be one of the following values:
| IFACFCS
| IFACFCE
record type provided is symbolic.
record type provided is a value.
| IFACRET is set to one of the following values:
| IFACNRM the file address was successfully created.
| IFACETYP the file type provided was in error.
| IFACEORD the file ordinal provided was in error.
|
12.23.3 Register use
| Not applicable. IFAC8 does not generate executable code.
|
12.23.4 Loss of control
| Not applicable. IFAC8 does not generate executable code.
|
12.23.5 Example
| No example provided. IFAC8 is a DSECT macro.
|
12.23.6 Related information
| 12.5, “FAC8C – Compute an online 8-byte file address” on page 259.
304
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
LEVTA
12.24 LEVTA – Test a storage level
12.24.1 Format
| [label] LEVTA {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}
|
,{INUSE=label1|NOTUSED=label2|INUSE=label1,NOTUSED=label2}
or format for TPF compatibility:
| [label] LEVTA {LEVEL=n|DECB={decb_addr|(reg2)}}
|
,{INUSE=label1|NOTUSED=label2|INUSE=label1,NOTUSED=label2}
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to be tested, where:
|
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register that contains the level value (use LA reg1,Dn). Use general register 14 (RDA), or
0 through 7 (RAC through RGF).
LEVEL=n
ECB level number: 0, 1, and so on up to F for level 15.
| DECB={decb_addr|(reg2)}
|
DECB to be tested, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 14 (RDA) or 0 through
7 (RAC through RGF).
| INUSE=label1
|
Label to which LEVTA branches if there is an attached block.
| NOTUSED=label2
|
Label to which LEVTA branches if there is no attached block.
|
12.24.2 Description
| Use the LEVTA macro to test whether an ECB or DECB storage level has an attached block. Do not code
| an assembler routine to do this.
|
12.24.3 Register use
| When you use register notation, LEVTA uses general register 14 (RDA) to indicate the ECB level or DECB.
LEVTA does not corrupt any other registers.
12.24.4 Loss of control
This macro does not cause the entry to lose control.
Chapter 12. Macros and callable services
305
LEVTA
12.24.5 Example
| The following example shows how you could use LEVTA to check whether there is a storage block attached
| at ECB level 3 (D3). If there is a storage block attached at ECB level 3, LEVTA branches to label NAME:
LEVTA LEVEL=3,
INUSE=NAME
NAME
.
.
.
EQU
TEST LEVEL 3
AND BRANCH IF BLOCK
ATTACHED
X
X
V
12.24.6 Related information
| 12.19, “GETCC – Get a storage block” on page 375.
| 12.28, “RELCC – Release a storage block” on page 387.
| ALCS Application Programming Guide.
306
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
LISTC
12.25 LISTC – Generate a storage list for SNAPC or SERRC
12.25.1 Format
[label]
LISTC NAME=area_name,TAG=area_address
[,LEN=area_length]
[,INDIR={NO|YES}]
or:
[label]
LISTC END
| or formats for TPF compatibility:
| [label] LISTC LEVEL=Dn
|
[,NAME=area_name]
| or:
| [label] LISTC DECB={decb_address|(reg)}
|
[,NAME=area_name]
label
Any valid assembler label.
NAME=area_name
Name of the area, 8 alphanumeric characters. You can omit trailing space (blank) characters. This
name appears in the dump listing identifying the contents of the dumped storage area.
TAG=area_address
Address of the area to be included in the SNAPC or SERRC dump, an S-type symbol or expression. If
INDIR=YES, then this is the address of a 4-byte field containing the address of the area.
LEN=area_length
Length (in bytes) of the area to be included in the SNAPC or SERRC dump. The total length must be less
than or equal to 32KB.
When you omit this parameter, LISTC uses the implied length of the TAG= parameter operand.
If you set the length to zero, ALCS processes this LISTC macroinstruction as a LISTC END.
INDIR={NO|YES}
TAG specifies the following, according to the value of INDIR= parameter:
|
NO
TAG specifies the address of the area
YES
TAG specifies the address of the 4-byte field containing the address of the area.
LEVEL=Dn
ECB storage level, where:
Dn
Level symbol: D0, D1, and so on up to DF for level 15.
Chapter 12. Macros and callable services
307
LISTC
Provided for compatibility with TPF. ALCS always includes any attached storage blocks in the SNAPC
or SERRC dump.
| DECB={decb_address|(reg)}
|
DECB storage level, where:
|
|
|
decb_address
reg
Assembler label of a 4-byte field containing the address of the DECB.
Register containing the address of the DECB. Use general register 14 (RDA) or 0
through 7 (RAC through RGF).
|
|
Provided for compatibility with TPF. ALCS always includes any attached storage blocks in the SNAPC
or SERRC dump.
END
This LISTC macroinstruction delimits (indicates the end) of the SNAPC or SERRC storage list.
12.25.2 Description
Use a sequence of consecutive LISTC macroinstructions to generate a list of user storage areas that you
can later dump using a SNAPC or SERRC macroinstruction. Any SNAPC or SERRC macroinstruction which
references this list will dump the specified areas.
You can code any number of LISTC NAME macroinstructions to define a number of areas. You must
terminate the list of areas using a LISTC END macroinstruction.
12.25.3 Register use
Not applicable. LISTC does not generate executable instructions.
12.25.4 Loss of control
Not applicable. LISTC does not generate executable instructions.
12.25.5 Example
The following example shows how you could use LISTC to dump specified data areas with SNAPC.
...
SNAPC R,FF6,MSG=MSGSN1L,LIST=MYINFO
...
V
MSGSNIL
MSGSN1
V
MYINFO
DC
DC
AL1(L'MSGSN1)
C'VVERROR DUMP FROM SNAPCVV'
LISTC NAME=MYDATA1,TAG=EBROUT
LISTC NAME=WORKAREA,TAG=EBW,LEN=1
LISTC END
12.25.6 Related information
-- Heading 'SERRC' unknown --.
-- Heading 'SNAPC' unknown --.
308
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
RCRFC
12.26 RCRFC – Release a pool-file record address and storage block
12.26.1 Format
| [label] RCRFC {Dn|DECB={decb_addr|(reg)}}
label
Any valid assembler label.
| Dn ECB storage level containing the pool-file record address and associated storage block address to be
|
released. Use D0, D1, and so on up to DF for level 15.
| DECB={decb_addr|(reg)}
|
DECB containing the pool-file record address and associated storage block address to be released,
|
where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg)
Register containing the address of the DECB. Use general register 14 (RDA) or 0 through
7 (RAC through RGF).
12.26.2 Description
Use the RCRFC macro to release a pool-file record address and the associated storage block.
| RCRFC Dn is the same as RELFC Dn,BLOCK=YES and RCRFC DECB= is the same as RELCC DECB=,BLOCK=YES.
| See the Description sections for RELFC and RELCC.
If you are releasing a whole chain of pool-file records, consider using the RLCHA macro instead of RCRFC.
Diagnostic, Modification, and Tuning Information
The RCRFC macro has a request type of RELFC and RELCC. In traces and dumps, RELFC and RELCC are
shown as the macro names instead of RCRFC.
End of Diagnostic, Modification, and Tuning Information
12.26.3 Register use
RCRFC does not corrupt any registers.
12.26.4 Loss of control
This macro can cause the entry to lose control.
12.26.5 Example
This example shows how you could use RCRFC in an ALCS application maintenance program to release a
pool-file record which is no longer needed. ECB level 2 (D2) is used here.
Chapter 12. Macros and callable services
309
RCRFC
LOOP
...
LA
SPACE
EQU
...
FINWC
...
RCRFC
BCT
...
R3,5
1
V
D2,ERROR
D2
R3,LOOP
5 RECORDS TO BE PROCESSED
SET UP RECORD ADDRESS
FIND THE OLD RECORD
PROCESS THE OLD RECORD
RELEASE FILE AND STORAGE
PROCESS THE NEXT RECORD IF ANY
12.26.6 Related information
12.28, “RELCC – Release a storage block” on page 387.
12.29, “RELFC – Release a pool-file record address” on page 389.
-- Heading 'RLCHA' unknown --.
310
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
RCUNC
12.27 RCUNC – Release a storage block and unhold a file address
12.27.1 Format
| [label] RCUNC {Dn|DECB={decb_addr|(reg)}}
label
Any valid assembler label.
| Dn ECB storage level containing the storage block to be released and the file addresses to be unheld.
|
Use D0, D1, and so on up to DF for level 15.
| DECB={decb_addr|(reg)}
|
DECB containing the storage block to be released and file addresses to be unheld, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg)
Register containing the address of the DECB. Use general register 14 (RDA) or 0 through
7 (RAC through RGF).
12.27.2 Description
Use the RCUNC macro to release a storage block and unhold a file address.
| RCUNC Dn is the same as RELCC Dn followed by UNFRC Dn and RCUNC DECB= is the same as RELCC DECB=
| followed by UNFRC DECB=. See the Description sections for RELCC and UNFRC.
Diagnostic, Modification, and Tuning Information
The RCUNC macro has a request type of RELCC and UNFRC. In traces and dumps, RELCC and UNFRC are
shown as the macro names instead of RCUNC.
End of Diagnostic, Modification, and Tuning Information
12.27.3 Register use
This macro does not corrupt any registers.
12.27.4 Loss of control
This macro can cause the entry to lose control.
12.27.5 Example
This example shows how an ALCS application program could release and unhold a storage block on
finding an error. ECB level 5 (D5) is used here.
Chapter 12. Macros and callable services
311
RCUNC
ERROR
ERROR2
...
FIWHC
SPACE
L
...
BNE
...
EQU
SERRC
...
EQU
SERRC
RCUNC
...
D5,ERROR
1
R3,CE1CR5
ERROR2
SET UP RECORD ADDRESS
FIND THE RECORD
LOAD BASE REGISTER
VALIDATE THE RECORD
GO IF INTERNAL ERROR FOUND
PROCESS THE RECORD
V
R,123
REPORT THE ERROR FOR PROBLEM SOLVING
V
R,1231
R5
REPORT THE ERROR FOR PROBLEM SOLVING
RELEASE AND UNHOLD THE RECORD
12.27.6 Related information
12.28, “RELCC – Release a storage block” on page 387.
12.31, “UNFRC – Unhold a file address” on page 319.
312
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
RELCC
12.28 RELCC – Release a storage block
12.28.1 Format
| [label] RELCC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}[,TYPE=COND]
or positional parameter format:
| [label] RELCC {Dn|(reg1)}
or format for TPF compatibility:
| [label] RELCC {Dn|DECB={decb_addr|(reg2)}}
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level to which the storage block to be released is attached, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB to which the storage block to be released is attached, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 14 (RDA) or 0 through
7 (RAC through RGF).
TYPE=COND
Specifies conditional release. ALCS does not terminate the entry if there is no storage block at the
specified level.
12.28.2 Description
| Use the RELCC macro to release a storage block from the DECB or ECB storage level.
| RELCC releases the block attached at the specified level, and makes the storage level available for reuse.
| A block must be attached at the specified level unless you specify the TYPE=COND parameter.
| After issuing RELCC, the application program must not reference the released block.
12.28.3 Register use
| When you use register notation, RELCC uses general register 14 (RDA), to indicate the ECB level or DECB
if required. RELCC does not corrupt any other registers.
12.28.4 Loss of control
RELCC does not cause the entry to lose control.
Chapter 12. Macros and callable services
313
RELCC
12.28.5 Example
| The following example shows how you could use RELCC to release the storage block attached to ECB
| storage level 12 (DC):
RELCC LEVEL=DC
RELEASE BLOCK
12.28.6 Related information
12.29, “RELFC – Release a pool-file record address” on page 389.
314
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
RELFC
12.29 RELFC – Release a pool-file record address
12.29.1 Format
| [label] RELFC {LEVEL={Dn|(reg1)}[|DECB={decb_addr|(reg2)}},BLOCK={NO|YES}]
or positional parameter format:
| [label] RELFC {Dn|(reg1)}
or format for TPF compatibility:
| [label] RELFC {Dn|DECB={decb_addr|(reg2)}}
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB storage level containing the file address of the pool-file record to be released, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB containing the file address of the pool-file record to be released, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 14 (RDA) or 0 through
7 (RAC through RGF).
BLOCK={NO|YES}
Release the storage block (YES), or do not release the storage block (NO).
12.29.2 Description
Use the RELFC macro to release a pool-file record address for use by other entries. Before issuing RELFC,
ensure that the data in the pool-file record is no longer required.
If the file address which you are releasing is stored in any other record (or records) or in the application
global area, be sure to clear these references before you release the file address.
Attention
After calling RELFC the record contents of the released pool-file address are unpredictable. Application
programs must not issue any DASD input or output macro that references the pool-file address that has
been released by a RELFC macro.
When you specify BLOCK=YES, RELFC issues RELCC to release the storage block. If you are releasing a
whole chain of pool-file records, consider using the RLCHA macro.
Chapter 12. Macros and callable services
315
RELFC
12.29.3 Register use
| When you use register notation, RELFC uses general register 14 (RDA) to indicate the ECB level or DECB.
RELFC does not corrupt any other registers.
12.29.4 Loss of control
RELFC can cause the entry to lose control.
12.29.5 Example
The following example shows how you could use RELFC to release a pool-file record address. The
| example assumes that there is only one reference to the file address in the real-time database. That
| reference is in the record at ECB level 7 (D7). The DSECT XX00XX describes the record at D7, and the
field XX00REF contains the file address released by this example.
L
R7,CE1CR7
XXXX REG=R7
MVC
EBCFA,XXREF
XC
XXREF,XXREF
FILEC D7
DROP R7
LOAD RECORD STORAGE ADDRESS
AND USE AS DSECT BASE
SAVE FILE ADDRESS FOR RELEASE
CLEAR REFERENCE
AND FILE THE RECORD
DROP RECORD BASE
RELFC D
RELEASE FILE ADDRESS
12.29.6 Related information
12.28, “RELCC – Release a storage block” on page 387.
-- Heading 'RLCHA' unknown --.
316
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
SONIC
12.30 SONIC – Get symbolic file address information
Compatibility
|
|
ALCS supports this macro for compatibility only. It occurs in some existing application programs
originally developed for TPF. It is supported to simplify running TPF applications on ALCS. IBM
recommends that you use this macro in ALCS only for 8-byte file addresses.
12.30.1 Format
| [label] SONIC {Dn|(reg1)}[,MCHR=N|Y|E]
| or
| [label] SONIC ADDR={label1|(reg2)}
label
Any valid assembler label.
| Dn|(reg1)
File address. Specify one of:
Dn
|
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15. Data level containing the file
address.
Register containing the file address. Use general register 0 through 7 (RAC through RGF).
MCHR=N|Y|E
TPF MCHR file address (MCHR=Y) or not. ALCS treats MCHR=Y and MCHR=E the same way as an
invalid file address.
| ADDR={label1|(reg2)}
|
Address of an 8-byte file address, where:
|
|
|
label1
(reg2)
Assembler label of an 8-byte field containing the file address.
Register containing the address of the file address. Use general register 0 through 7 (RAC
through RGF).
12.30.2 Description
In TPF, SONIC returns information about a symbolic file address. In ALCS, SONIC works as follows:
On return from SONIC, ALCS sets the condition code:
Condition code
0
1
Meaning
File address is valid
File address is not valid
| If the file address is valid, SONIC returns 4 bytes of information about the corresponding DASD record. If
| the file address is in an ECB data level or ADDR= is used, then SONIC returns the information in general
| register 15 (RDB). If the file address is in a register, then SONIC returns the information in the same
register.
Chapter 12. Macros and callable services
317
SONIC
Byte
Bit
Meaning
0
0
Record type indicator:
0 = Fixed
1 = Pool
0
1
Pool file type indicator:
0 = Long-term
1 = Short-term
0
2-6
Zero
0
7
File address validity indicator:
0 = Valid file address
1 = Invalid file address
1
0-7
Zero
2
0-7
Zero
3
0-3
Zero
3
4
Pool file address indicator:
0 = Fixed file address
1 = Pool file address
3
5
Zero
3
6
Always set to 1
3
7
Record size indicator:
0 = Small (less than 1055 bytes)
1 = Large (at least 1055 bytes)
IBM recommends that you do not use this macro in ALCS.
12.30.3 Register use
| SONIC loads the file address into general register 14 (RDA). If the file address is in an ECB data level or
| ADDR= is used, then SONIC returns the information in general register 15 (RDB). If the file address is in a
register, then SONIC returns the information in the same register.
SONIC does not corrupt any other registers.
12.30.4 Loss of control
This macro does not cause the entry to lose control.
12.30.5 Example
No example provided. IBM recommends that you do not use this macro in ALCS.
12.30.6 Related information
-- Heading 'RONIC' unknown --.
318
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
UNFRC
12.31 UNFRC – Unhold a file address
12.31.1 Format
| [label] UNFRC {LEVEL={Dn|(reg1)}|DECB={decb_addr|(reg2)}}[,TYPE=COND]
or positional parameter format:
| [label] UNFRC {Dn|(reg1)}
or format for TPF compatibility:
| [label] UNFRC {Dn|DECB={decb_addr|(reg2)}}[,GDS={Y|N}]
label
Any valid assembler label.
| LEVEL={Dn|(reg1)}
|
ECB data level containing the file address to be unheld, where:
|
Dn
(reg1)
Level symbol: D0, D1, and so on up to DF for level 15.
Register containing the level value (use LA reg1,Dn). Use general register 14 (RDA), or 0
through 7 (RAC through RGF).
| DECB={decb_addr|(reg2)}
|
DECB containing the file address to be unheld, where:
|
|
|
decb_addr Assembler label of a 4-byte field containing the address of the DECB.
(reg2)
Register containing the address of the DECB. Use general register 14 (RDA) or 0 through
7 (RAC through RGF).
TYPE=COND
The request is conditional. If the record is not held, UNFRC ignores the request. If TYPE=COND is
omitted, the file address must be held, otherwise, UNFRC causes a system error.
GDS={Y|N}
This parameter is provided for compatibility with TPF. ALCS ignores it.
12.31.2 Description
Use the UNFRC macro to unhold a previously held file address.
UNFRC unholds a file address that was previously held by a FINHC or FIWHC macro.
| UNFRC does not initiate any I/O. UNFRC does not check or modify the associated ECB or DECB storage
| level.
12.31.3 Register use
| When you use register notation, UNFRC uses general register 14 (RDA) to indicate the ECB level or DECB.
UNFRC does not corrupt any other registers.
Chapter 12. Macros and callable services
319
UNFRC
12.31.4 Loss of control
This macro does not cause the entry to lose control.
12.31.5 Example
| The following example shows how you could use UNFRC to unhold the file address in ECB data level 13
| (DD); that is, in EBCFAD. The example assumes that previous instructions hold the file address (FINHC or
FIWHC macro):
UNFRC DD
UNHOLD RECORD ON DD
12.31.6 Related information
12.12, “FINHC – Read a DASD record and hold the file address” on page 274
12.15, “FIWHC – Read a DASD record, hold the file address, and wait for I/O completion” on page 281.
320
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
UNFRC
SH19-6742 Airline Control System Version 2 Documentation Changes for Data Event Control Block
(DECB) Support APAR AQ54564 5695-068 Printed in Denmark by IBM Danmark A/S
Chapter 12. Macros and callable services
321
ALCS macros
Chapter 13. Summary of ALCS macros and callable services
Figure 160 on page 325 lists all ALCS macros and callable services that are part of the General-Use
programming interface. These include:
5
5
5
5
5
5
5
Monitor-request macros
System-error macros
Assembly macros
DSECT macros
Equate macros
Dummy macros
Callable services.
13.1 Explanatory notes
These notes refer to Figure 160 on page 325.
13.1.1 Macro types
The following macro types are identified in the table:
Monitor-request macros
Monitor-request macros generate linkage instructions to the ALCS monitor or to ALCS ECB-controlled
programs. These linkage instructions call ALCS services.
Some monitor-request macros also generate EQU instructions which define symbols for values related to
the requested function. Symbols which form part of the ALCS General-Use Programming Interface are
listed in this section, in the description of the appropriate macro.
System-error macros
System-error macros generate an invalid operation code which causes an operation exception. The ALCS
system-error handling routines intercept this operation exception.
Assembly macros
Assembly macros generate inline code (either executable instructions, DC instructions, or both). They do
not generate linkages to the ALCS monitor or to ALCS ECB-controlled programs.
Some assembly macros also generate dummy sections or EQU instructions (or both) which define
symbols for values related to the requested function. Symbols which form part of the ALCS General-Use
Programming Interface are listed in this section, in the description of the appropriate macro.
DSECT macros
DSECT macros generate dummy sections which describe the layout of ALCS control blocks, DASD
records, and so on. These dummy sections define symbols (field names) for use in ALCS application
programs. Some DSECT macros also generate EQU instructions which define symbols for values that
these fields contain. Symbols which form part of the ALCS General-Use Programming Interface are listed
in this section, in the description of the appropriate macro.
322
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
ALCS DSECT macros also optionally generate USING instructions which assign (but do not load) base
registers for the dummy sections.
-- Heading 'DSECT' unknown -- describes ALCS DSECT macros in more detail. -- Heading 'NEWDSEC'
unknown -- describes how you can define your own DSECT macros for use in ALCS application programs.
For further information on the use of DSECT macros, refer to the manual ESA/390 Principles of Operation.
Equate macros
Equate macros generate EQU instructions which define symbols for use in ALCS application programs.
Symbols which form part of the ALCS General-Use Programming Interface are listed in this section, in the
description of the appropriate macro.
-- Heading 'DSECT' unknown -- describes ALCS equate macros in more detail. -- Heading 'NEWDSEC'
unknown -- describes how you can define your own equate macros for use in ALCS application programs.
Dummy macros
ALCS supports dummy macros only for compatibility with TPF. They occur in some existing application
programs originally developed for TPF. ALCS supports them to simplify porting these applications to
ALCS.
Dummy macros are not part of the General-Use Programming Interface. You should not use them in new
programs. Under ALCS, dummy macros have no effect. They do not appear in macro traces.
Callable services (ENTER/BACK)
These are ECB-controlled programs that are available to perform functions required by application
programs. Application programs call a service by using an ENTRC (or, in one case, an ENTNC) macro call to
the program.
Callable services (MVS CALL)
These are the APPC/MVS and MQI wait services provided with ALCS. Application programs call a service
by using an MVS CALL macroinstruction.
13.1.2 Request types
In traces and dumps, most macros appear under their own names (for example, ALASC appears as ALASC).
However, some macros appear under different names (for example, CRASC appears as ENTRC). This
different name is called the request type.
In Figure 160 on page 325, request types are indicated in a separate column. Macros with no request
type shown appear under their own names in traces and dumps.
13.1.3 Loss of control
For information about loss of control, see ALCS Application Programming Guide.
13.1.4 Conditions of use
(blank)
Part of the ALCS general programming interface. Also supported by TPF. For general
use.
Chapter 13. Summary of ALCS macros and callable services
323
ALCS macros
TPF only
Provides functions needed by TPF, but not by ALCS. Can be used in new programs.
ALCS only
Not supported by TPF. Do not use in programs that must be compatible with TPF.
Compatibility
Supported only for compatibility with TPF or other existing programs. Use of this macro
can prevent exploitation of new functionality. You are not recommended to use this
macro.
13.1.5 Possible alternative
Some monitor-request macros have one or more alternatives which might be more suitable in certain
circumstances. Alternatives are listed in this column.
13.2 Using and defining macros
For information about using individual macros or callable services, see Chapter 12, “Macros and callable
services” on page 249.
You can define additional DSECT and equate macros for use in application programs. See -- Heading
'NEWDSEC' unknown --.
13.2.1 IPARS macros
In addition to the ALCS macros shown in Figure 160 on page 325, you can use IPARS macros in your
application programs. These macros are provided as part of the TPF program. The MIMI and WAAA
DSECT macros and the α and TYCVA assembly macros are examples.
IPARS macros are not provided as part of ALCS. However, you can find definitions for these macros, and
examples of their use, in the “IPARS – ALCS V2” libraries. These are included in the ALCS shipment.
324
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
13.3 List of macros and callable services intended for customer use
Figure 160 provides an outline of all ALCS macros and callable services that are part of the General-Use
programming interface. See 13.1, “Explanatory notes” on page 322 for more information about these
macros.
The macros and callable services identified in this table are provided as programming interfaces for
customers by ALCS.
When global area protection is specified, ALCS also supports KEYCC and GLMOD to change the PSW
protect key, and KEYRC and FILKW (option R) to restore the PSW protect key.
If global area protection is not specified, KEYCC, GLMOD, KEYRC, FILKW (option R) have no effect, but
show up in a macro trace.
Attention
Do not use as General-Use Programming Interfaces any ALCS macros or callable services other than
those identified in this table.
Figure 160 (Page 1 of 6). ALCS macros
Macro or callable
service name
Macro type
Request type
Causes
loss of
control
Conditions
of use
ALASC
monitor-request
never
AMSG
DSECT
n/a
ASCIC
monitor-request
never
ALCS only
ATAWAIT
callable service
sometimes
ALCS only
ATTAC
monitor-request
never
AUTHC
monitor-request
sometimes
BACKC
monitor-request
sometimes
BEGIN
assembly
n/a
BSAI
DSECT
n/a
CC
assembly
n/a
CCIDC
assembly
n/a
Compatibility
CCNV
callable service
never
ALCS only
CFMT
callable service
always
ALCS only
CINFC
monitor-request
never
Compatibility
CMND
assembly
n/a
ALCS only
CMPR
assembly
n/a
ALCS only
CM1CM
DSECT
n/a
ALCS only
COMCC
monitor-request
never
ALCS only
COMIC
monitor-request
never
ALCS only
CORHC
monitor-request
sometimes
CORUC
monitor-request
sometimes
Possible
alternative
ALCS only
ALCS only
STICC TIMEC
COMIC LODIC
Chapter 13. Summary of ALCS macros and callable services
325
ALCS macros
Figure 160 (Page 2 of 6). ALCS macros
|
Macro or callable
service name
Macro type
COIC
Causes
loss of
control
Conditions
of use
DSECT
n/a
ALCS only
CO3MP
DSECT
n/a
ALCS only
CPSEQ
equate
n/a
ALCS only
CRASC
monitor-request
CREDC
monitor-request
CREEC
monitor-request
CREMC
monitor-request
CRETC
monitor-request
CREXC
monitor-request
CRUSA
monitor-request
RELCC
never
CRUSA TEST=level
monitor-request
RELCC and LEVTA
never
CSMI
callable service
never
ALCS only
CSMO
callable service
never
ALCS only
CZ1CP
dummy, equate
n/a
TPF only
DCLAC
assembly
n/a
ALCS only
DCTMSG
DSECT
n/a
DECBC
monitor-request
never
DEFRC
monitor-request
always
DEQC
monitor-request
DETAC
monitor-request
DISPC ADD
assembly,
monitor-request
ENTRC (to CSC1)
sometimes
ALCS only
DISPC READ
assembly,
monitor-request
ENTRC (to CSC7)
sometimes
ALCS only
DISPC RELEASE
assembly,
monitor-request
ENTRC (to CSC8)
sometimes
ALCS only
DISPC SEND
assembly,
monitor-request
ENTRC (to CSC2)
sometimes
ALCS only
DLAYC
monitor-request
always
DPROC
assembly
n/a
EBEB
DSECT
n/a
ENQC
monitor-request
ENTDC
monitor-request
sometimes
ENTNC
monitor-request
sometimes
ENTRC
monitor-request
sometimes
EVINC
monitor-request
CORUC
sometimes
EVNQC
monitor-request
CORUC
sometimes
EVNTC
monitor-request
CORHC
sometimes
326
Request type
ENTRC (to CPQS)
Possible
alternative
sometimes
sometimes
CREDC or CREMC
sometimes
CREDC CREMC
sometimes
CRETS or CRETM
never
sometimes
CORUC
Compatibility
sometimes
never
CORHC
sometimes
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Compatibility
ALCS macros
Figure 160 (Page 3 of 6). ALCS macros
Macro or callable
service name
Macro type
Request type
Causes
loss of
control
Conditions
of use
EVNWC
monitor-request
CORUC
sometimes
EVBK
DSECT
n/a
EXITC
monitor-request
always
FACE
callable service
FACEC
never
FACS
callable service
FACEC
never
|
FAC8C
monitor-request
RONIC
never
|
FA4X4C
assembly
n/a
FILEC
monitor-request
sometimes
FILKW
monitor-request
FILNC
monitor-request
FILSC
monitor-request
FILEC
sometimes
Compatibility
FILTP
monitor-request
RONIC
never
Compatibility
FILUC
monitor-request
sometimes
FINDC
monitor-request
sometimes
FINHC
monitor-request
sometimes
FINIS
assembly
n/a
FINPC
monitor-request
never
ALCS only
FINSC
monitor-request
sometimes
Compatibility
FINWC
monitor-request
sometimes
FIPWC
monitor-request
sometimes
FIWHC
monitor-request
sometimes
FLIPC
monitor-request
never
GCFLC
monitor-request
GETFC and GETCC
GCFSC
monitor-request
GDSNC
Possible
alternative
KEYUC
sometimes
FINDC
RONIC
Compatibility
FINPC
sometimes
Compatibility
GETFC
GETFC and GETCC
sometimes
Compatibility
GETFC
monitor-request
RAISC
never
GDSRC
monitor-request
RAISC
never
GENMSG
assembly
n/a
GETCC
monitor-request
never
GETFC
monitor-request
sometimes
GETFC BLOCK=YES
monitor-request
GETFC and GETCC
sometimes
GETLC
monitor-request
GETFC
sometimes
Compatibility
GETFC
GETPC
dummy
n/a
Compatibility
GETPC LOCK=NO
monitor-request
FINPC
never
Compatibility
FINPC
GETSC
monitor-request
GETFC
sometimes
Compatibility
GETFC
GGFAC
monitor-request
never
Compatibility
GLMOD
monitor-request
never
Compatibility
GLOBZ
assembly, DSECT
KEYUC
n/a
Chapter 13. Summary of ALCS macros and callable services
327
ALCS macros
Figure 160 (Page 4 of 6). ALCS macros
Macro or callable
service name
Macro type
Request type
Causes
loss of
control
Conditions
of use
Possible
alternative
GLOUC
monitor-request
KEYUC
never
GTIMC
monitor-request
TIMEC
never
Compatibility
TIMEC
HASHC
monitor-request
never
HLDTC
monitor-request
sometimes
ICELOG
assembler
never
ICPLOG
assembler
never
|
IDECB
DSECT
n/a
|
IFAC8
DSECT
n/a
KEYCC
dummy,
monitor-request
never
TPF only
KEYRC
dummy,
monitor-request
never
TPF only
KEYUC
monitor-request
never
LEVTA
assembly
never
LISTC
assembly
n/a
LMONC
dummy,
monitor-request
n/a
LODIC
monitor-request
never
LODIC SUSPEND
monitor-request
sometimes
LONGC
monitor-request
MAP327
Compatibility
never
Compatibility
DSECT
n/a
ALCS only
MODEC
dummy,
monitor-request
never
Compatibility
MONTC
dummy,
monitor-request
never
Compatibility
MQAWAIT
callable service
sometimes
ALCS only
PNAMC
assembly
n/a
Compatibility
POSTC
monitor-request
CORUC
sometimes
RAISA
monitor-request
RAISC
never
RCRFC
monitor-request
RELFC and RELCC
sometimes
RCUNC
monitor-request
RELCC and UNFRC
sometimes
RCPL
DSECT
n/a
REGEQ
equate
n/a
REHKA
monitor-request
never
RELCC
monitor-request
never
RELFC
monitor-request
sometimes
RELPC
dummy
n/a
Compatibility
RIDIC
monitor-request
never
ALCS only
RLCHA
monitor-request
328
SLIMC
RLCHC
sometimes
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
SLIMC
Compatibility
RLCHA
ALCS macros
Figure 160 (Page 5 of 6). ALCS macros
Macro or callable
service name
Macro type
Request type
RONIC
monitor-request
ROUTC
monitor-request
RSECT
assembly
n/a
ALCS only
SAVEC
monitor-request
never
ALCS only
SENDC
monitor-request
SENDA, SENDD,
SENDK, SENDT
sometimes
SENDC K, TYPE=QUEUE
monitor-request
ENTRC (to CPQS)
sometimes
SENDC L
monitor-request
ENTRC (to CPQS)
sometimes
SENDC M
monitor-request
SENDM
sometimes
SERRC
system-error
always
SLIMC
monitor-request
never
SLMTC
monitor-request
SNAPC
system-error
always
SONIC
monitor-request
never
STDHD
DSECT
n/a
STICC
monitor-request
never
ALCS only
SWISC
monitor-request
sometimes
Compatibility
SXIPC
monitor-request
never
ALCS only
SYNCC
monitor-request
sometimes
SYSCC
monitor-request
never
SYSRA
assembly,
monitor-request
TASBC
monitor-request
never
TASNC
monitor-request
sometimes
TASTC
monitor-request
never
TCLSC
monitor-request
always
TDSPC
monitor-request
never
TDTAC
monitor-request
sometimes
TIMEC
monitor-request
never
TOPNC
monitor-request
sometimes
TOURC
monitor-request
sometimes
TOUTC
monitor-request
sometimes
TPPCC
monitor-request
TPPCE
equate
ROUTC
ENTRC (to CPQS)
ENTRC (to CLQS)
ENTRC (to CPQS)
CREMC, CREDC,
ENTDC
ENTRC (to CEA1)
or SERRC
ENTRC (to CLU6)
Causes
loss of
control
Conditions
of use
never
ALCS only
Possible
alternative
sometimes
ALCS only
ALCS only
ALCS only
sometimes
Compatibility
ALCS only
sometimes
sometimes
RONIC
SERRC
Compatibility
Compatibility
TPF only
CPI-C or
APPC/MVS
calls
n/a
Chapter 13. Summary of ALCS macros and callable services
329
ALCS macros
Figure 160 (Page 6 of 6). ALCS macros
Macro or callable
service name
Macro type
TPRDC
monitor-request
sometimes
TRANV
assembly
n/a
ALCS only
TRMEQ
equate
n/a
Compatibility
TRSVC
monitor-request
never
TSYNC
dummy
n/a
TWRTC
monitor-request
sometimes
UNFRC
monitor-request
never
UNHKA
monitor-request
sometimes
WAITC
monitor-request
sometimes
WHOCC
monitor-request
never
ALCS only
WILDC
monitor-request
never
ALCS only
WTOPC
monitor-request
sometimes
YEARA
monitor-request
330
Request type
TIMEC
Causes
loss of
control
never
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Conditions
of use
Possible
alternative
Compatibility
Compatibility
DEFRC,
DLAYC
Compatibility
ALCS macros
13.4 Macro group names
Figure 161 lists macro group names as used in the ALCS trace facility. It groups macros according to
their type and lists possible synonyms.
Figure 161. Macro group names
Group name
Macros in group
Synonyms
PROGRAM
Enter/back macros and EXITC
ENTER
ENTs
GRP1
GRP1
CREate
Create-type macros
GRP2
GRP2
DEFER
Defer/delay macros
DELAY
DFR
DLY
GRP3
GRP3
FILe
File-type macros and UNFRC
GRP4
GRP4
FINd
Find-type macros
GRP5
GRP5
STORE
Storage block management macros
STG
CORe
GRP6
GRP6
POOL
Pool file macros
GFS
RFS
GRP7
GRP7
SEND
Send-type macros
COMMS
COMS
GRP8
GRP8
GRP9
None
GRP9
SEQF
Sequential file macros
TAPE
GRP1
KEY
PSW key change macros
GRP11
GRP12
Enter/back macros
EXITC
Create-type macros
Defer/delay macros
FINDFILE
Find-type macros
File-type macros
Storage management macros
FINFIL
GRP13
SLC
SLC macros
GRP14
ALL
All macros
GRP15
Chapter 13. Summary of ALCS macros and callable services
331
ALCS macros
Chapter 14. ALCS C programming conventions and facilities
When you write C programs intended to run under ALCS, you must follow some conventions that are
different from those that apply in other C programs. This chapter describes facilities that are available,
and conventions that you should use, when programming ALCS applications in C. It also describes the
header files supplied with ALCS.
14.1 C language compatibility
ALCS supports both the ISO-C language and TPF-C. Applications can be ported between ALCS and
TPF, or between ALCS and other C platforms. For more details of compatibility see Chapter 16, “C
library functions available under ISO-C, ALCS, and TPF” on page 412.
To use ALCS application programs written in C, you must compile them with the IBM OS/390 C/C++
| compiler. To use DECBs in ALCS application programs written in C, you must compile them with the IBM
| OS/390 C++ compiler. The ALCS Application Programming Guide describes how to compile and link-edit
C programs.
14.2 Structure of C programs
This section describes the structure of C programs written for ALCS.
14.2.1 Source module
Each C language source module written for ALCS contains one or more of the following:
5 #include statements; the C compiler treats the included files as part of the source program
5 Functions defined in this module
5 Calls to C functions in this source module
5 Calls to C functions in other modules
5 Calls to assembler modules
5 Calls to other programs using the using entdc and entrc functions.
14.2.2 Load modules
Before you can use your C programs under ALCS, your system programmer must build one or more load
modules which contain the programs. The ALCS Application Programming Guide describes how to create
load modules from C source programs.
When the system programmer has built the load module or modules, they must be loaded onto the ALCS
system. See the ALCS Operation and Maintenance for details.
332
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
14.3 Function names
You can use any names for functions that are allowed by the C compiler. When you call a function from
the same source module, the C compiler uses the whole of the function name to identify which function
you mean.
You can also call a C function defined in another program, provided the function you are calling is in a
program in the same load module. See Figure 162 on page 333.
entrc(PRG2,&regs) ──────┐
│
─ ── ── ── ── ── ── ── ── ─── ─ │ ─ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ─
LOAD MODULE
│
│
│
PROGRAM1 (C)
│
PROGRAM2 (C)
PROGRAM3 (assembler)
┌───────────────────────────┐
│
┌─────────────────────────┐
┌───────────────────────┐
│ find_target(char a)
│
│
│ void PROGRAM3(void);
│
┌──;│
│
│ {
│
└──;│ void program2(void)
│
│
│
│
│ }
│
│ {
│
│
│
│
│
│
│ PROGRAM3(); ─────────── │ ──┘
│
│
│ find_end(char a)
│
│
<── ── ── ── │ ─── ──│
│
│ {
│
│
│
│
│
│ }
│
│
│
│
│
│
┌───────────────── │ ───── │ ext_fun(x,y);
│
│
│
│
D
│
┌ ─>│
│
└───────────────────────┘
│ ext_fun(int a,int b)
│
│
│
│
│ {
│
│
│ }
│
│
│
│
│
│
│ }─ ── ── ── ── ── ── ── ─ ┼ ─ ┘
└─────────────────────────┘
│
│
│ void program_1(void)
│
│ {
│
│ find_target(x);
│
│ find_end(z);
│
│ }
│
└───────────────────────────┘
END OF LOAD MODULE
─ ── ── ── ── ── ── ── ── ─── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ─
Figure 162. Calls between programs in the same load module
In Figure 162, 3 functions are shown defined in PROGRAM1.
find_target, find_end
These two functions are only used internally in PROGRAM1.
ext_fun
This is a function that is intended to be used by other C programs.
The C program called PROGRAM2 uses ext_fun and also makes a call to the assembler program
PROGRAM3. The calls are shown by solid lines, the return paths from the called programs are shown in
broken lines.
Note: Figure 162 also shows an entrc call into PROGRAM2 from a program outside this load module.
This is the standard ALCS program linkage explained in the ALCS Application Programming Guide. (The
4-character name PRG2 has been associated with an entry point in program PROGRAM2 during the load
module build process.)
Chapter 14. ALCS C programming conventions and facilities
333
ALCS macros
14.3.1 Length of function names
The C language allows function names longer than the eight-character external names that the MVS
linkage editor supports.
| To resolve this, the OS/390 Language Environment Prelinker (and the MVS linkage editor) or the binder
allow you to map long names into short names for object modules produced by the compiler. You can
also use the compiler directive #pragma map.
When referencing programs written in assembler, you can either use the short name of the program (8
characters or less) or map a suitable long name, using the #pragma map directive. For example, to call
program PROGRAM3 by the name calculate_top, you could code the following:
#pragma map(calculate_top, "PROGRAM3")
14.4 Requirements for reentrant programs
All application programs intended to run under the control of ALCS must be reentrant. You must code
each application program so that it can be used simultaneously by more than one entry.
It is possible (though difficult) to write self-modifying code in C. This is not allowed in ALCS C programs.
TPF compatibility
1. ALCS (but not TPF) supports data objects of storage class extern. If your programs must be
compatible with TPF do not declare data objects with storage class extern static, or with the
keyword extern. Only use storage classes automatic, register, const, and volatile, and within
the scope of a file or block, the storage class static.
2. The enter/back services of TPF may cause some program segments to be relocated in storage
during the processing of an ECB. For compatibility with TPF, do not take the addresses of
functions and do not use pointers to functions.
3. Application programs intended to run under TPF must not exceed 4KB in size. Application
programs that are intended to run under ALCS can be any size.
There are currently two implementations of the C language for the TPF Version 4 Release 1 product.
One implementation is called TARGET(TPF) and is specific to the TPF product because the IBM
OS/390 C/C++ compiler produces TPF-specific code. The second implementation is called ISO-C and
supports the standard object code produced by the IBM OS/390 C/C++ compiler. The ISO-C
implementation supports all C language constructs. Both implementations require TPF header files
and runtime libraries.
Note: These restrictions apply to TARGET(TPF) but not to ISO-C support in TPF.
14.4.1 Strings
The OS/390 C/C++ compiler makes text strings writeable by default. This means that at runtime a copy of
each string is placed in writeable storage.
You can use the #pragma strings(readonly) directive to place the strings into read-only storage. This is
recommended for compatibility with TPF-C and to avoid the overheads of initializing the writeable strings.
Note: You must code the #pragma strings(readonly) directive before the #include <tpfeq.h> directive.
334
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
14.4.2 Header files
The ALCS header file <tpfeq.h> includes the system function prototypes and constants needed in all
ALCS C programs. Include <tpfeq.h> as the first header file in every ALCS C program.
You might need to include additional header files, depending on what functions your program uses (see
14.9, “ALCS header files” on page 338). You might also need to include header files written specifically
for your installation.
You can create your own header file which contains all these header files, together with #pragmas,
#defines, and so on that are required in your application. For example, your header file might contain the
following:
#pragma strings(readonly)
#include <tpfeq.h>
#include <tpfio.h>
#include <tpfapi.h>
#include <stdio.h>
#include <strings.h>
If this source file is named MYAPPHDR, you can include it in all your application programs by coding:
#include "myapphdr.h"
Recommendations
When creating header files, you are advised to follow the following rules:
5 Always use the same structure to reference the same record. Put these structures in common header
files that programmers can include when needed. In addition, all records should use standard
headers.
5 Do not use names starting with dxc or tpf for header files or programs. These file names are used by
ALCS.
5 Do not define preprocessor or C language variables starting with the characters: DXC, dxc, TPF, or
tpf. Your names might conflict with names used by ALCS.
5 ALCS uses file names starting with the characters c$ for header files that have been created from
assembler DSECT macro definitions. Do not use such names for other files.
Note: ALCS supplies an offline program DXCBGSTR which converts assembler DSECT macro
definitions into C structures. This program is described in the ALCS Application Programming Guide.
You might find this program useful for creating structures for existing records in your installation.
If your installation uses the IBM High Level Assembler, you can use the DSECT utility provided with
the IBM OS/390 C/C++ compiler instead of DXCBGSTR.
5 Avoid expanding the same header file more than once. One method that helps avoid this is to
precede each #define in a header file with a #ifndef. For example:
#ifndef xxxxxx
#define xxxxxx
..
.
(text of the header file)
..
.
#endif
In this case, if xxxxxx has been defined previously (possibly because this header file has already been
included), the preprocessor does not include the header file text a second or subsequent time.
Chapter 14. ALCS C programming conventions and facilities
335
ALCS macros
14.5 Defining structures
When you define structures in ALCS C programs (for example, to describe the layout of data in a record)
you must consider boundary alignment.
By default, the OS/390 C/C++ compiler aligns field boundaries according to the type of each field defined
in the structure (Figure 163).
Figure 163. Default alignments of fields in structures
Data Type
Storage occupied
Alignment
char
1 byte
byte
int
4 bytes
fullword
short int
2 bytes
halfword
long int
4 bytes
fullword
float
4 bytes
fullword
double
8 bytes
doubleword
| When you define int, short int, and long int fields within a structure, the C compiler normally forces
boundary alignments so that each new field starts at a fullword or halfword boundary.
Sometimes, you might need to override these default boundary alignments. For example, suppose you
have to define the following fields in a structure:
field_1
│ field_2
│
│
field_3
│
│
│
D
D
D
┌───┬───┬───┬───┬───┬───┬───┬─────────────
│ X │
│
│
└───┴───┴───┴───┴───┴───┴───┴─────────────
Assume field_2 is of type short and field_3 is of type long. Both fields must follow field_1 without any
gaps caused by forced alignment.
You can do this by defining the structure as a _Packed struct as follows:
_Packed
{
char
short
long
struct example
field_1;
field_2;
field_3;
..
.
};
You must also use the _Packed keyword any time that you define an instance of this structure. For
example:
struct _Packed example ex1, Vptr_ex2;
336
/V define an instance of the structure V/
/V define a pointer to the structure
V/
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
14.6 Time and date functions
All the C time and date functions are available. They use the current C locale and the MVS system clocks.
The timec function is provided to access the ALCS time and date services directly. (Remember that the
ALCS system time and date may be different from the MVS time and date.)
TPF compatibility
Applications written for TPF that use the time function to get the TPF system time may need to be
modified for use with ALCS. IBM recommends that you use the timec function to get the ALCS
system time.
The tpf_STCK function is provided to access the S/390 time-of-day (TOD) clock value for situations
requiring greater accuracy than to the nearest second.
14.7 Input message formats
In C programs you normally use the stdin functions to read messages from the originating terminal. This
is the recommended method. However, you can directly examine an input message in AMSG or IMSG
format. (You must know which format the message is in.) 14.10.1, “AMSG contents for an input
message” on page 338 describes how ALCS formats an AMSG input message and 14.11.1, “IMSG
contents for an input message” on page 339 describes how ALCS formats an IMSG input message.
To examine an input message in AMSG format you must include the header file <c$amsg.h>. To
examine an input message in IMSG format you must include the header file <c$cm1cm.h>.
14.8 Routing of messages
In C programs you normally use the stdout functions to send messages back to the originating terminal.
However, you can also use the routc function to do this. In addition, routc allows you to send a message
to another terminal or to an application. When you call routc you must supply it with the address of a
routing control parameter list (RCPL).
14.8.1 The RCPL
When ALCS receives a message it creates an ECB and attaches the message on storage level 0. It also
puts information relating to the origin of the message in an area in the ECB identified by the label ce1rcpl
(see the ALCS Application Programming Guide). This area contains an RCPL with the format described in
14.16.1, “RCPL supplied with an input message” on page 343.
You can modify (or copy and modify) this RCPL to create a different RCPL which you can then use with a
routc function (see 14.16.2, “RCPL required for an output message” on page 344). Alternatively, you can
create an RCPL for an output message from scratch.
The header file <c$rcpl.h> defines the contents of a RCPL. You must include this header file when you
use routc in a program. (See 14.16, “<c$rcpl.h>” on page 342.) When the output message is in
AMSG format, you must also include the header file <c$amsg.h>. When the output message is in OMSG
format, you must also include the header file <c$cm1cm.h>. You must also set bit RCPL2REC in rcplctl2
to 0 when the message is in AMSG format and to 1 when the message is in OMSG format. (See 14.16.2,
“RCPL required for an output message” on page 344.)
Chapter 14. ALCS C programming conventions and facilities
337
ALCS macros
14.9 ALCS header files
ALCS provides header files, some of which you must include in all ALCS application programs written in
C, and some of which you only need to include when you are using certain functions. (See Chapter 15,
“ALCS API functions — reference”.)
The header files perform the following functions:
5 Map the ECB and other ALCS data structures
5 Provide C function prototypes
5 Define constants for the function parameters and return codes
5 Define macros for the functions implemented as macros
5 Define the TPF_regs structure (TPF_regs is a C structure used to pass parameter values in registers).
All ALCS programs require you to include the file <tpfeq.h>, which contains the definitions required by all
ALCS C functions, as the first header file. Some functions require additional header files, for example,
attac requires <tpfapi.h>. These header file requirements are shown in the function descriptions in
Chapter 15, “ALCS API functions — reference”
14.10 <c$amsg.h>
This header file defines the application message format (AMSG) structure. In ALCS, input and output
messages in AMSG format are contained in one storage block.
You do not need to include <c$amsg.h> when you are using the standard C input/output functions (for
example, gets, puts, and printf). However, you must include this header file when you are examining an
input message in AMSG format or using the routc function to output a message in AMSG format.
14.10.1 AMSG contents for an input message
ALCS sets up the following fields in the storage block when it passes a message in AMSG format to a
program.
amrid
This 2-byte char array contains the characters 'MI'.
amcct
This short int field contains the number of bytes in the message text, plus 5.
amtxt
This char array contains input text. Each line is terminated by the new-line character (_CAR). The
message is terminated by an end-of-message character (_EOM or _EOU). The terminating character
is included in the message length.
14.10.2 AMSG contents for an output message
Your application must set up the following fields in the storage block when it passes a message in AMSG
format to ALCS:
amrid
Insert the characters 'OM' in this 2-byte char array.
338
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
amcct
Set this short int field to contain the number of bytes in the message text, including the
end-of-message character, plus 5.
amnp1
Set this char field to contain a _NOP character.
amnp2
Set this char field to contain a _NOP character.
amtxt
Put the message text into this char array. For details of the layout, see ALCS Application
Programming Guide.
Example
The following example shows how to create an output message in AMSG format.
short int cct;
struct amsg Vam;
/V build an amsg format message for use with routc
am = getcc(D7,GETCC_TYPE,L1); /V get storage block for message
cct = strlen(msg);
/V get length of message text
memcpy(am->amtxt,msg,cct);
/V move the text into the omsg
am->amtxt[cct++] = _EOM;
/V add _EOM and increment count
cct += 5;
/V add length of fixed fields
am->amcct=cct;
/V insert count into omsg
am->amnp1 = _NOP;
am->amnp2 = _NOP;
V/
V/
V/
V/
V/
V/
V/
14.11 <c$cm1cm.h>
TPF compatibility
Do not use this header file in programs that must be compatible with TPF.
This header file defines the IMSG and OMSG structure. In ALCS, input messages in IMSG format and
output messages in OMSGS format are contained in one storage block.
You do not need to include <c$cm1cm.h> when you are using the standard C input/output functions (for
example, gets, puts, and printf). However, you must include this header file when you are examining an
input message in IMSG format or using the routc function to output a message in OMSG format.
14.11.1 IMSG contents for an input message
ALCS sets up the following fields in a storage block when it passes a message in IMSG format to a
program:
cm1bid
This 2-byte unsigned char array contains the characters 'IM'.
cm1cct
This short int field contains the number of bytes in the message text, including the end-of-message
character, plus 3.
Chapter 14. ALCS C programming conventions and facilities
339
ALCS macros
cm1cri
This 3-byte unsigned char array contains the communication resource identifier (CRI) of the originating
terminal.
cm1txi
This char array contains input text. Each line, except the last, is terminated by the new-line character
(_CAR). The message is terminated by an end-of-message character (_EOM or _EOU).
14.11.2 OMSG contents for an output message
Your application must set up the following fields in 1 or more storage blocks when it passes a message in
OMSG format to ALCS:
cm1bid
Insert the characters 'OM' in this 2 char array.
cm1cct
Set this short int field to contain the number of bytes in the message text, plus 5.
cm1cmw
Set this char field to contain a _NOP character.
cm1lna
This unsigned char field optionally contains a display line number (ALCS outputs the message starting
at this line on the display). When the destination is a display, set this field to a _NOP or _CAR
character, or to an actual display line number plus hexadecimal 80 (0x80). (Line numbers start at
zero.) When the destination is a printer, set this field to a _CAR character.
cm1txt
Put the message text into this char array. Terminate each line, except the last, with a new-line
character (_CAR). For messages to terminals, terminate the message with the 3 character sequence:
_CAR, _SOM, _EOM. For messages to printers, terminate the message with the 2 characters _CAR,
_EOM.
Example
The following example shows how to create an output message in OMSG format.
char Vmsg = "message text 1\nmessage text 2";
short int cct;
struct cm1cm Vcm;
/V build an omsg format message for use with routc
cm = getcc(D7,GETCC_TYPE,L1); /V get storage block for message
cct = strlen(msg);
/V get length of message text
memcpy(cm->cm1txt,msg,cct);
/V move the text into the omsg
cm->cm1txt[cct++] = _EOM;
/V add _EOM and increment count
cct += 5;
/V add length of fixed fields
cm->cm1cc1=cct;
/V insert count into omsg
cm->cm1lna = ;
/V set line number cm->cm1cmw = _NOP;
V/
V/
V/
V/
V/
V/
V/
V/
14.12 <c$coic.h>
TPF compatibility
Do not use fields defined in this header file in programs that must be compatible with TPF.
340
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
This header file defines the coic structure used with the function comic. You do not need to include this
header file in programs, it is included by <tpfapi.h>. The comic function returns values in the following
fields:
icecrn
This 8-byte char array contains the communication resource name (CRN) of the resource.
icecri
This unsigned int field contains the CRI of the resource.
icearc
This unsigned int field contains the CRI of the associated resource (if any).
iceorn
This unsigned int field contains the communication resource ordinal number (a unique number
associated with the communication resource).
iceusl
This long int field contains the length of user data area (if any) in the communication tables.
icesze
This 8-bit unsigned int field contains the number of display lines (rows) when the resource is a
display terminal.
icearn
This 8-byte char array contains the application name when the resource is a terminal, and when it is
routed to an application. The application name is left justified and the array is padded with spaces.
This name is not necessarily the same as the application program name of the input message editor
program for the application.
iceprg
This 4-byte char array contains the application program name. When the resource is an application,
this array contains the application program name of the input message editor program for the
application.
This header file also defines the following bit fields that you can test. The meaning when each of these
fields is set is shown below:
ices3ex
Resource is a terminal that supports the IBM 3270 extended data stream.
icesaaa
Terminal hold (also called AAA hold) is set.
icesapn
Resource is an alternate CRAS printer.
icesatn
Resource is a terminal with alternate CRAS authority.
icescmd
Resource is an application that can process ALCS commands (the application processes
input messages with primary action code Z).
icescst
Resource is in session with ALCS (active).
icesdbc
Resource is a terminal that supports the IBM 3270 double-byte character set.
iceslog
Resource is a terminal and is routed to an application.
icesnef
Resource is an ALC terminal, attached through an ALCI link, or an ALC terminal attached
through NEF2.
icesprc
Resource is a terminal with Prime CRAS authority.
icesroc
Resource is the read only (RO) CRAS terminal.
icesslc
Resource is an ALC terminal attached through an SLC link.
Chapter 14. ALCS C programming conventions and facilities
341
ALCS macros
icestcp
Resource is controlled by this ALCS.
icestpp
Resource is a printer.
icestps
Resource is a display.
icesuns
Resource is unusable.
icesx25
Resource is an ALC terminal attached through an AX.25 link.
Example
The following example shows how you could test one of these bit fields:
struct coic Vp;
if (p->icescst)
printf("Resource is in session with ALCS\n");
|
14.13 <c$decb.h>
| This header file defines (as type TPF_DECB) the structure of the ALCS data event control block (DECB).
| The DECB is described in the ALCS Application Programming Guide.
| You must include this header file when using any of the DECB management functions tpf_decb_create,
| tpf_decb_locate, tpf_decb_release, tpf_decb_swapblk and tpf_decb_validate.
14.14 <c$ebeb.h>
This header file defines the structure of the ALCS entry control block (ECB). The ECB is described in the
ALCS Application Programming Guide.
You do not need to include this header file in programs. It is included by <tpfeq.h>.
14.15 <c$globz.h>
This header file defines the global tag definitions and is required if you are using the global area. It is
created by the system programmer in your installation and is not part of ALCS. See ALCS Installation and
Customization for details of how to create this file.
This file is included by <tpfglbl.h>.
14.16 <c$rcpl.h>
This header file defines the routing control parameter list (RCPL) structure (see 14.8, “Routing of
messages” on page 337). The fields in the RCPL have different meanings for input and output messages.
You do not need to include <c$rcpl.h> when you are using the standard C input/output functions (for
example, gets, puts, and printf). However, you must include this header file when you are using the
routc function.
342
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
14.16.1 RCPL supplied with an input message
ALCS sets up the fields in an RCPL in the ECB (in the array ce1rcpl) when it receives a message:
rcpldes
When the message is to an application program, this 4-byte char array contains an application name.
When the message is to a terminal, the first 3 bytes of the field contain the CRI of the destination
terminal.
rcplorg
When ALCS received the message from a program, this 4-byte char array contains an application
name. When ALCS received the message from a terminal, it contains the CRI of the originating
terminal in the first 3 bytes of the field.
rcplctl
This char field contains two non-exclusive bit settings which you can test using the following defined
symbols:
RCPL0OTY
If set, rcplorg contains the origin application name, if unset, rcplorg contains the origin CRI.
RCPL0FMT
If set, the RCPL is expanded format (16 bytes), if unset, the RCPL is basic format (12 bytes).
Example
The following example shows how you could test one of these values:
#include <tpfeq.h>
#include <c$rcpl.h>
..
.
struct rcpl Vptr_rcpl;
..
.
/V set the pointer to the rcpl area in the ECB V/
ptr_rcpl = (struct rcpl V) ecbptr()->ce1rcpl;
/V display the contents of the rcplorg field in the ECB V/
printf("The rcplorg field contains the");
if (ptr_rcpl->rcplctl & RCPLOTY)
{
printf("origin application name: %4.4s\n",ptr_rcpl->rcplorg);
}
else
{
printf("origin CRI: %2X%2X%2X\n",
ptr_rcpl->rcplorgl,
ptr_rcpl->rcplorgi,
ptr_rcpl->rcplorgt);
}
rcplctl2
This char field contains three non-exclusive bit settings which you can test using the following defined
symbols:
RCPL2REC
If set, the message is recoverable; if unset, the message is not recoverable.
Chapter 14. ALCS C programming conventions and facilities
343
ALCS macros
RCPL2POS
If set, the message is possibly a duplicate; if unset, the message is not a duplicate.
RCPL2FMH
If set, the message text includes a function management header (FMH), otherwise it is unset.
Expanded RCPLs contain extra fields, as follows:
rcplgdd
This unsigned char field contains bit switches. The first 4 high-order bits (bits 0, 1, 2, and 3) are
reserved for ALCS use; you can use the other bits in accordance with your installation standards.
rcplctr
This unsigned char field contains the length of the general data area that follows.
rcplgda
General data area. This field is provided for compatibility with TPF.
14.16.2 RCPL required for an output message
Set up an RCPL as described below before calling the routc function to send a message. Set all unused
bytes in the RCPL to binary zeros, using memset as shown in the “Example” which follows.
rcpldes
When you send a message to an application program, set this 4-byte char array to contain an
application name. When you send a message to a terminal, set the first 3 bytes of the field to the CRI
of the destination terminal.
Note: You can “broadcast” the same message to a number of terminals by calling routc several
times, resetting the CRI value before each call.
rcplorg
Set this 4-byte char array to the name of an application or store a CRI in the first 3 bytes.
rcplctl
Set this char field to contain four non-exclusive bit settings. Use the following defined symbols:
RCPL0DTY
Set this to 1 when rcpldes contains the destination application name; set to 0 when rcpldes
contains the destination CRI.
RCPL0MTY
Set this to 1 when the message is unsolicited (not a response); set to 0 when the message is a
response.
RCPL0RET
Set this to 1 when the message is being returned as a reply to the originator, otherwise set to 0.
RCPL0FMT
Set this to 1 when the RCPL is expanded format (16 bytes); set to 0 when the RCPL is basic
format (12 bytes).
Example
The following example shows how you could set two of these bits:
344
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
struct rcpl rcpl;
/V define an RCPL
..
.
memset(&rcpl, , sizeof(rcpl));
/V clear RCPL to zeros
..
.
/V set the rcpl to indicate:
/V rcpldes contains the destination application name
/V the message is unsolicited
rcpl.rcplctl = RCPLDTY | RCPLMTY;
V/
V/
V/
V/
V/
memcpy(rcpl.rcpldes,"APPL",4); /V set the application to "APPL" V/
..
.
rcplctl2
Set this char field to contain 3 non-exclusive bit settings. Use the following defined symbols:
RCPL2REL
Set this to 1 when you want routc to release the storage block that contains the message;
otherwise set to 0.
RCPL2MFT
Set this to 1 when the message is in OMSG format. Set it to 0. when the message is in AMSG
format.
RCPL2FMH
Set this to 1 when the message text includes a function management header (FMH), otherwise set
to 0.
Expanded RCPLs contain extra fields, as follows:
rcplgdd
This unsigned char field contains bit switches. The first 4 high-order bits (bits 0, 1, 2, and 3) are
reserved for ALCS use. You can use any of the other bits in accordance with your installation
standards.
rcplctr
Set this unsigned char field to the length of the general data area that follows.
rcplgda
General data area. This field is provided for compatibility with TPF.
14.17 <c$stdhd.h>
This header file defines the structure of the standard ALCS record header. The standard header contains
the following fields:
stdbid
Record identifier (2 bytes)
stdchk
Record code check (1 byte)
stdctl
Record control byte (1 byte)
stdpgm
Last update program name (4 bytes)
stdfch
Forward chain record address (4 bytes)
stdbch
Backward chain record address (4 bytes).
The ALCS Application Programming Guide explains the use of these fields in more detail.
Chapter 14. ALCS C programming conventions and facilities
345
ALCS macros
14.18 <tpfapi.h>
This header file defines ALCS API function prototypes (except for I/O functions) and constants, described
in Chapter 15, “ALCS API functions — reference” on page 351.
| <tpfapi.h> also defines the stdhdr structure which contains the following fields which ALCS requires for
| the rlcha function:
stdbid
This 2-byte char array contains the record ID.
stdrec
This unsigned char field contains the record code check (RCC).
stdfad
This unsigned int field contains the file address.
It also contains the the ronic_info_area structure which contains the following information which ALCS
returns on a ronic call:
roncls
This unsigned short field contains the record class.
ronnbr
This unsigned long field contains the number of records allocated.
ronbty
This unsigned short field contains the block type code (L1, L2,...).
ronbln
This unsigned short field contains the logical block length (in bytes).
rontyp
This unsigned short field contains the fixed-file record type number, or pool interval number, or
general file number.
ronic sets the following bit fields when the record is:
ronvfod
In delayed-file mode
ronvfop
Permanently resident
ronvfot
In time-initiated file mode
ronvfof
In force-read mode
ronvfou
In update (read before write) mode
ronvfol
Using long-term pool stamp processing
ronvfoh
Using hyperspace backing
346
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
ronindc
In a configuration data set
ronindlt
A long-term pool record
ronindst
A short-term pool record
ronindp
A pool record
ronindg
In a general file or general dataset
ronindr
A database record.
For an example of the use of this area, see -- Heading 'RONIC' unknown --.
14.19 <tpfeq.h>
Include <tpfeq.h> as the first header file in every ALCS C program.
This header file defines the ALCS general system function prototypes and the following constants:
_CRI_PRC
_CRI_ROC
_EUA
_FF
_FID
_FS
_FSC
_GE
_HT
_IC
_IFS
_IGS
_INP
_IR
_IRS
_IT
_IUS
_LF
_LFEED
_LSC
_NAK
_NBS
_NGBLS
_NL
_NOP
_NSP
_POC
_PP
_PT
_RFF
Prime CRAS CRI
RO CRAS CRI
3270 erase unprotected to address
Form feed
ALCS field identifier
Field separator
ALCS figure shift
Graphic escape
Horizontal tab
3270 insert cursor
Interchange file seperator
Interchange group seperator
Inhibit presentation
Index return
Interchange record seperator
Indent tab
Interchange unit seperator
Line feed
ALCS line feed
ALCS letter shift
Negative acknowledge
Numeric backspace
Number of global areas
New line
ALCS no operation
Numeric space
Programmed operator command
Presentation position
3270 program tab
Required form feed
Chapter 14. ALCS C programming conventions and facilities
347
ALCS macros
_RNL
_RPT
_RSP
_SA
_SBA
_SBS
_SEG
_SEL
_SHY
_SI
_SO
_SOH
_SOM
_SOS
_SP
_SPS
_STX
_SUB
_SW
_SYN
_TRN
_UBS
_UME
_VCS
_VT
_WCW
_WEW
_WLA
_WUN
Required new line
Repeat
Required space
Set attribute
3270 set buffer address
Subscript
ALCS segment ID
Select
Syllable hyphen
Shift in
Shift out
Start of header
ALCS start of message
Start of significance
Space
Superscript
Start of text
Substitute
Switch
Synchronous idle
Transparent
Unit backspace
UMSG end of message
SCS vertical channel select
Vertical tab
ALCS write continue at cursor
ALCS write and erase
ALCS write on specified line
ALCS write unsolicited
This header file also defines the TPF_regs structure and the enumeration type t_regs.
The TPF_regs structure is as follows:
/V
VV
VV
V/
Struct TPF_regs: used to pass parameters to assembler
programs in registers.
struct
{
long
long
long
long
long
long
long
long
};
TPF_regs
int
int
int
int
int
int
int
int
r;
r1;
r2;
r3;
r4;
r5;
r6;
r7;
The enumeration type t_regs is as follows:
enum t_regs {R, R1, R2, R3, R4, R5, R6, R7};
348
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
14.20 <tpfglbl.h>
This header file defines global interface function prototypes and constants. You must include <tpfglbl.h>
in programs that use either of the global functions (glob or global).
|
14.21 <tpfio.h>
This header file defines the ALCS I/O function prototypes and constants. It includes the function
prototypes and parameter definitions for all the I/O functions (except the sequential file functions). You
must include <tpfio.h> in programs that use any of the I/O functions (find and file functions).
| <tpfio.h> also contains the structure defined as type TPF_FAC8 which describes the parameter block
| used by the tpf_fac8c function.
|
The following input fields must be set before calling the tpf_fac8c function:
| ifacord
|
This unsigned long long field must be set to the record ordinal number.
| ifacrec
|
This 8-byte char array must be set to the fixed-file record type symbol when ifactyp contains
|
IFAC8FCS.
| ifacrnb
|
This unsigned long field must be set to the fixed-file record type value when ifactyp contains
|
IFAC8FCE.
| ifactyp
|
This unsigned char field must be set to indicate whether the record type specified is a symbol
|
(IFAC8FCS) or a value (IFAC8FCE).
|
The following fields are returned by the tpf_fac8c function:
| ifacadr
|
This field (defined type TPF_FA8) is set to the 8-byte file address.
| ifacmax
|
This unsigned long long field is set to the maximum ordinal number for the requested record type.
| ifacret
|
This unsigned char field is set to the return code, which is one of the following defined values:
|
|
TPF_FAC8_NRM
Normal return.
|
|
TPF_FAC8_TYP
Call type invalid or record type invalid.
|
|
TPF_FAC8_ORD
Record ordinal invalid.
Chapter 14. ALCS C programming conventions and facilities
349
ALCS macros
14.22 <tpftape.h>
This header file provides the function prototypes and parameter definitions for the functions that access
sequential files. You must include <tpftape.h> in programs which use functions that access sequential
files.
<tpftape.h> also contains the tpstat structure, which contains the following fields. (The tdspc function
returns information in these fields.)
tpname
A 3-byte char array containing the symbolic name of the sequential file
devtypr
An 8-byte char array containing the sequential file name
volser
A 6-byte char array containing the volume serial number
dsname
A 44-byte char array containing the data set name.
<tpftape.h> also defines the following bit fields. When these are set they indicate the following:
|
standby
Sequential file is standby
reserved
Sequential file is reserved
closed
Sequential file is closed
realtime
Sequential file is realtime
log
Sequential file is a log file
diagnostic
Sequential file is a diagnostic file
general
Sequential file is a general file
input
Sequential file is an input file.
350
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS macros
Chapter 15. ALCS API functions — reference
This chapter contains an alphabetical listing of all ALCS API functions. The following information is shown
for each function:
Format
The function prototype, and a description of any parameters.
Description
What service the function provides.
Normal return
What is returned when the requested service has been performed.
Error return
What is returned when the requested service could not be performed.
Note: Specifying invalid function parameters results in a system error (dump) with exit. Invalid
parameters do not give an error return.
Loss of control
Some functions cause ALCS to remove control from the entry. This section describes the
circumstances under which this happens. (System error with exit is not included as “Loss of control”.)
Example
One or more code segments, showing example function calls.
Related information
Where to find additional information relevant to this function.
Note: You must include <tpfeq.h> as the first header file in any ALCS C application program.
15.1.1 Significant blanks
Where you must code significant space characters, for example in fixed-file record type names, these
space characters are denoted in this chapter by the character “␣”. For example:
#define VD1RI "#VD1RI␣␣"
This is simply to make the space characters visible. The actual C code would look like this:
#define VD1RI "#VD1RI
"
15.2 Common parameters
Some parameters are common to several functions. These are described in detail here.
level
One of 16 possible values representing a valid data level or storage level. Use one of the defined
values Dx, where x represents the hexadecimal number of the level (0-F). The action that the function
takes with the level parameter is described with the function description.
program_name
Pointer to a program, or transfer vector, name in an ECB-controlled program. A program name
conventionally consists of one alphabetic character followed by 3 alphanumeric characters. All
alphabetic characters must be in uppercase (CAPITALS).
Chapter 15. ALCS API functions — reference
351
ALCS macros
GDS
ALCS ignores this parameter (provided for compatibility with TPF).
NOTAG
When ALCS writes the record it does not insert the program name into the record header.
Compatibility
In TPF Version 3.0, all the file functions (filec, ...) allowed optional GDS and NOTAG parameter. All
the find functions (findc,...) allowed an optional GDS parameter.
In later versions of TPF, the basic file and find functions (for example filec) do not allow the optional
parameters GDS and NOTAG. Instead there is an extended version of each function (for example,
filec_ext) which has a mandatory parameter ext_file. The programmer sets bit settings (defined
values) in ext_file to indicate if the GDS and NOTAG option is required.
ext_file
With extended file functions (filec_ext, ...), set this parameter to one or more of the following values.
(Use the + operator to specify more than one value.)
FILE_GDS
ALCS ignores this parameter value.
FILE_NOTAG
When ALCS writes the record it does not insert the program name into the record header.
FILE_DEFEXT
ALCS ignores this parameter value. Do not use with either FILE_NOTAG or FILE_GDS.
ext_find
With extended versions of find functions (findc_ext, ...), set this parameter to one of the following
values:
FIND_GDS
ALCS ignores this parameter value.
FIND_DEFEXT
ALCS ignores this parameter value.
352
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
attac_ext
|
15.3 attac_ext — Attach a previously detached storage block
|
Format
| #include <tpfeq.h>
| #include <tpfapi.h>
| void Vattac_ext(enum t_lvl level, int ext);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| void Vattac_ext(TPF_DECB Vdecb, int ext);
| level
|
An ECB storage level (D0, D1,...DF.), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
| ext
|
Indicate which block is to be attached. Use one of the following terms:
|
|
|
ATTAC_USER_DEFAULT
Reattach the block from the most recent detac_ext at the specified ECB level or for the specified
DECB.
|
|
|
|
ATTAC_USER_ACPDB
Reattach the block detached by a previous detac_ext. The block file address must match the file
address at the specified ECB level or in the specified DECB. Store the required file address in the
ECB data level (ce1fmn) or DECB (idecfa) before issuing attac_ext.
|
Description
| Use the attac_ext function to reattach a block detached by a previous detac_ext. Specify the appropriate
| value for the ext parameter to indicate which block is to be attached.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
|
Normal return
| Pointer of type void representing the address of the start of the newly attached block.
|
Error return
| Not applicable.
|
Loss of control
| This function does not cause the entry to lose control.
Chapter 15. ALCS API functions — reference
353
attac_ext
|
Examples
|
|
|
|
This example detaches a storage block from ECB level 4 (D4) using detac_ext. Another block is obtained
on ECB level 4 and also detached using detac_ext. Then the first block is attached using attac_ext.
Note that the file address is saved and then re-stored on the appropriate level before issuing the
attac_ext.
| #include <tpfeq.h>
| #include <tpfapi.h>
| double
| double
farw_save1;
farw_save2;
| getfc(D4,GETFC_PRIME,"OM",GETFC_BLOCK,GETFC_NOSERRC);
| memcpy(&farw_save1,&ecbptr()->ebcfw4,sizeof(double));
| detac_ext(D4, DETAC_USER_ACPDB);
| getfc(D4,GETFC_PRIME,"ZJ",GETFC_BLOCK,GETFC_SERRC);
| memcpy(&farw_save2,&ecbptr()->ebcfw4,sizeof(double));
| detac_ext(D4, DETAC_USER_DEFAULT);
| memcpy(&ecbptr()->ebcfw4,&farw_save1,sizeof(double));
| attac_ext(D4, ATTAC_USER_ACPDB);
| This example reattaches a previously detached storage block to a DECB.
| #include <tpfeq.h>
| #include <tpfapi.h>
| struct cm1cm Vcm;
| TPF_DECB
Vdecb;
||
..
|
.
| cm = (struct cm1cm V)attac_ext(decb, ATTAC_USER_ACPDB);
|
|
|
|
|
|
|
|
Related information
12.1, “ATTAC – Attach a previously detached storage block” on page 250.
15.4, “attac_id — Attach a previously detached storage block” on page 355.
12.4, “DETAC – Detach a storage block” on page 257.
15.6, “detac_ext — Detach a storage block” on page 359.
15.7, “detac_id — Detach a storage block” on page 361.
12.19, “GETCC – Get a storage block” on page 375.
12.28, “RELCC – Release a storage block” on page 387.
354
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
attac_id
|
15.4 attac_id — Attach a previously detached storage block
Format
#include <tpfeq.h>
#include <tpfapi.h>
void Vattac_id(enum t_lvl level);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| void Vattac_id(TPF_DECB decb);
|
level
An ECB storage level (D0, D1,...DF.), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
Description
Use the attac_id function to reattach a block detached by a previous detac_id. The block file address
| must match the file address at the specified ECB level or in the specified DECB. Store the required file
| address in the ECB data level (ce1fmn) or DECB (idecfa) before issuing attac_id.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
Pointer to the start of the storage address of the newly attached block.
Error return
Not applicable.
Loss of control
This function does not cause the entry to lose control.
|
Examples
| This example detaches a storage block from ECB level 4 (D4) using detac_id. Another block is obtained
on level 4 and also detached using detac_id. Then the first block is attached using attac_id. Note that
the file address is saved and then re-stored on the appropriate level before issuing the attac_id.
Chapter 15. ALCS API functions — reference
355
attac_id
#include <tpfeq.h>
#include <tpfapi.h>
double
double
farw_save1;
farw_save2;
getfc(D4,GETFC_PRIME,"OM",GETFC_BLOCK,GETFC_NOSERRC);
memcpy(&farw_save1,&ecbptr()->ebcfw4,sizeof(double));
detac_id(D4);
getfc(D4,GETFC_PRIME,"ZJ",GETFC_BLOCK,GETFC_SERRC);
memcpy(&farw_save2,&ecbptr()->ebcfw4,sizeof(double));
detac_id(D4);
memcpy(&ecbptr()->ebcfw4,&farw_save1,sizeof(double));
attac_id(D4);
| This example reattaches a previously detached storage block to a DECB.
| #include <tpfeq.h>
| #include <tpfapi.h>
| struct cm1cm Vcm;
| TPF_DECB
Vdecb;
||
..
|
.
| cm = (struct cm1cm V)attac_id(decb);
Related information
15.7, “detac_id — Detach a storage block” on page 361.
12.1, “ATTAC – Attach a previously detached storage block” on page 250.
12.19, “GETCC – Get a storage block” on page 375.
12.28, “RELCC – Release a storage block” on page 387.
356
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
crusa
15.5 crusa — Release storage blocks from specified levels
Format
#include <tpfeq.h>
#include <tpfapi.h>
void crusa(int count, enum t_lvl level, ...);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| void crusa(int count, TPF_DECB Vdecb, ...);
|
count
The number of level or decb parameters included in the argument list (minimum 1, maximum 16).
|
level
An ECB storage level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
Description
Use the crusa function to release storage blocks from an entry.
| crusa releases a storage block attached at any, or all, the ECB levels specified in the level parameter or
| the DECBs specified in the decb parameter. crusa does not return an error if one or more of the levels or
| DECBs you specify does not have an attached storage block.
| Note: Applications that call this function using DECBs instead of ECB levels must be compiled with the
| C++ compiler because this function has been overloaded.
Normal return
Void.
Error return
Not applicable.
Loss of control
This function does not cause the entry to lose control.
Example
| This example tests ECB storage levels 0, 4, and 10 (D0, D4, and DA) and any specified DECBs for
| storage blocks. It releases the blocks if present.
Chapter 15. ALCS API functions — reference
357
crusa
#include <tpfeq.h>
#include <tpfapi.h>
| TPF_DECB Vdecb1, Vdecb2;
||
..
|
.
| crusa(3,DA,D,D4);
/V Clear levels D, D4, DA V/
|||
...
| crusa(2,decb1,decb2); /V Clear DECBs decb1, decb2 V/
Related information
15.15, “levtest — Test a storage level” on page 383.
12.28, “RELCC – Release a storage block” on page 387.
358
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
detac_ext
|
15.6 detac_ext — Detach a storage block
|
Format
| #include <tpfeq.h>
| #include <tpfapi.h>
| void detac_ext(enum t_lvl level, int ext);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| void detac_ext(TPF_DECB Vdecb, int ext);
| level
|
An ECB storage level (D0, D1,...DF.), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
| ext
|
Indicate which block is to be detached. If you code more than one term for ext, you must separate the
|
terms with a plus sign (+). Use any of the following terms:
|
|
|
DETAC_USER_DEFAULT
The blocks detached from the specified ECB level or DECB will be reattached in a last-in-first-out
(LIFO) order using attac_ext(...,ATTAC_USER_DEFAULT).
|
|
|
DETAC_USER_ACPDB
The detached block will be reattached using attac_ext(...,ATTAC_USER_ACPDB) if the block file
address matches the file address for the specified ECB level or DECB.
|
|
|
DETAC_CHECK
This term is provided for compatibility with TPF. ALCS ignores it.
|
|
|
TPF compatibility
When you use DETAC_CHECK (or DETAC_DEFAULT) in TPF, detac_ext checks that a
storage block is attached at the specified ECB level or DECB and dumps with exit if not. In
ALCS detac_ext ignores this option and does not check for an attached block.
|
|
DETAC_NOCHECK
Indicates that no check will be made to determine if there is a block to be detached.
|
|
DETAC_DEFAULT
Indicates that the defaults are DETAC_USER_DEFAULT and DETAC_CHECK.
|
Description
| Use the detac_ext function to detach a storage block from an entry temporarily. You can later reattach
| the block by calling the attac_ext function.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Chapter 15. ALCS API functions — reference
359
detac_ext
|
Normal return
| Void. The specified ECB storage level or DECB is now available for use.
|
Error return
| Not applicable.
|
Loss of control
| This function does not cause the entry to lose control.
|
Examples
| This example detaches a storage block from ECB level 6 (D6).
| #include <tpfeq.h>
| #include <tpfapi.h>
||
..
|
.
| detac_ext(D6, DETAC_USER_DEFAULT);
| This example detaches a storage block from a DECB.
| #include <tpfeq.h>
| #include <tpfapi.h>
| TPF_DECB Vdecb;
|||
...
| detac_ext(decb, DETAC_USER_ACPDB);
|
|
|
|
|
|
|
|
Related information
12.1, “ATTAC – Attach a previously detached storage block” on page 250.
15.3, “attac_ext — Attach a previously detached storage block” on page 353.
15.4, “attac_id — Attach a previously detached storage block” on page 355.
12.4, “DETAC – Detach a storage block” on page 257.
15.7, “detac_id — Detach a storage block” on page 361.
12.19, “GETCC – Get a storage block” on page 375.
12.28, “RELCC – Release a storage block” on page 387.
360
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
detac_id
|
15.7 detac_id — Detach a storage block
Format
#include <tpfeq.h>
#include <tpfapi.h>
void detac_id(enum t_lvl level);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| void detac_id(TPF_DECB decb);
|
level
An ECB storage level (D0, D1,...DF.), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
Description
Use the detac_id function to detach a storage block from an entry temporarily. You can later reattach the
block by calling the attac_id function.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
Void. The storage level is now available for use.
Error return
Not applicable.
Loss of control
This function does not cause the entry to lose control.
|
Examples
| This example detaches a storage block from ECB level 6 (D6).
#include <tpfeq.h>
#include <tpfapi.h>
..
.
detac_id(D6);
| This example detaches a storage block from a DECB.
Chapter 15. ALCS API functions — reference
361
detac_id
| #include <tpfeq.h>
| #include <tpfapi.h>
| TPF_DECB Vdecb;
||
..
|
.
| detac_id(decb);
Related information
12.1, “ATTAC – Attach a previously detached storage block” on page 250.
15.4, “attac_id — Attach a previously detached storage block” on page 355.
12.4, “DETAC – Detach a storage block” on page 257.
12.19, “GETCC – Get a storage block” on page 375.
12.28, “RELCC – Release a storage block” on page 387.
362
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
file_record_ext
15.8 file_record_ext — Write a DASD record, with extended options
Format
#include <tpfeq.h>
#include <tpfio.h>
void file_record_ext(enum t_lvl level, unsigned int Vaddress, char Vrecord_id,
unsigned char rcc, enum t_act type, unsigned int ext_file);
| or
| #include <tpfeq.h>
| #include <tpfio.h>
| void file_record_ext(TPF_DECB Vdecb, TPF_FA8 Vfa8, char Vrecord_id,
|
unsigned char rcc, enum t_act type, unsigned int ext_file);
level
An ECB level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
address
|
Pointer to the 4-byte file address that you want the record to be written to, or NULL.
| fa8
|
Pointer to the 8-byte file address in 4x4 format that you want the record to be written to, or NULL.
record_id
Pointer to the 2-character record ID of the record to be written to DASD, or RECID_RESET.
rcc
The record code check (RCC) of the record to be written to DASD, or '\0'.
type
An indicator that tells ALCS whether after the write, it must:
5 Release the storage block
5 Unhold the record.
Use one of the following values:
NOHOLD
ALCS releases the storage block and does not change the hold status of the file address.
UNHOLD
ALCS releases the storage block and unholds the file address.
NOREL
ALCS does not release the storage block and does not change the hold status of the file address.
ext_file
If you code the value FILE_NOTAG, when ALCS writes the record it does not insert the program
name into the record header. ALCS ignores any other values (provided for compatibility with TPF).
See 15.2, “Common parameters” on page 351.
Chapter 15. ALCS API functions — reference
363
file_record_ext
Description
| When the level parameter is specified, the file_record_ext function writes the contents of the storage
| block, attached at that ECB data level, to the file address specified in the address parameter. When the
address parameter is NULL, file_record_ext writes the storage block to the file address stored in the
| ECB data level specified in the level parameter. (The storage block must be the same size as the record.)
|
|
|
|
|
When the decb parameter is specified, the file_record_ext function writes the contents of the storage
block, attached at the data level of that DECB, to the file address specified in the fa8 parameter. When the
fa8 parameter is NULL, file_record_ext writes the storage block to the file address stored in the data
level of the DECB specified in the decb parameter. (The storage block must be the same size as the
record.)
After the call, the data level contains the file address, record ID, and record code check (RCC) for the
| record that has been written. However, if you code the file address (address or fa8), or the record_id as
NULL, ALCS does not change the file address or record ID (whichever is NULL).
When you specify type as UNHOLD, the entry must be holding the file address. ALCS unholds it. When
you specify NOREL or NOHOLD, ALCS does not change the hold status of the file address.
The record ID in the record_id parameter must match the record ID in the record image. You can supress
this this check by coding RECID_RESET in the record_id parameter.
The record code check (RCC) in the rcc parameter must match the RCC in the record image. You can
supress this check by setting rcc to '\0'.
When the type parameter contains the value NOREL, you can test for these errors by examining the
return value of the subsequent waitc function (which is required, see “Loss of control” below). When the
type parameter does not contain NOREL, errors cause a system error (dump) with exit.
Notes:
1. Unless you use a value of NOREL in the type parameter, ALCS releases the storage block.
|
|
2. Applications that call this function using a DECB address instead of an ECB level must be compiled
with the C++ compiler because this function has been overloaded.
Normal return
Void.
Error return
Not applicable.
Loss of control
This function can cause the entry to lose control.
When you use the NOHOLD and UNHOLD values for the type parameter, ALCS does not return the
status of the operation to the application program. You cannot test the success of the write.
When you code the value NOREL in the type parameter, you must follow this function call (at some stage)
with a waitc call, or with a call to a function that has an implied waitc. The return from the waitc, or the
function containing the implied waitc, lets you check whether the preceding I/O operations, including this
write, were successful.
364
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
file_record_ext
|
Examples
| This example writes the data in the storage block attached at ECB level 7 (D7) to a general data set,
bypasses the record header update, and releases the block. The record ID is 'CD', the RCC is '\0', and
the file address is taken from the forward chain field of another record.
#include <tpfeq.h>
#include <tpfio.h>
..
.
file_record_ext(D7,(unsigned int V)&(inm->imfch),"CD",'\',
UNHOLD,FILE_NOTAG+FILE_GDS);
| This example writes the data in the storage block attached at the data level of a DECB and unholds the
| record. The file address and record ID are specified in the DECB.
| #include <tpfeq.h>
| #include <tpfio.h>
| TPF_DECB Vdecb;
||
..
|
.
| file_record_ext(decb,NULL,NULL,'\',UNHOLD,FILE_NOTAG)
Related information
|
|
|
|
-- Heading 'FILEREC' unknown --.
-- Heading 'FINDREC' unknown --.
-- Heading 'RAISA' unknown --.
15.25, “tpf_fac8c — Compute an online 8-byte file address” on page 404.
15.26, “tpf_fa4x4c — Convert a file address” on page 406.
12.31, “UNFRC – Unhold a file address” on page 319.
15.28, “unfrc_ext — Unhold a file address, with extended options” on page 410.
Chapter 15. ALCS API functions — reference
365
find_record_ext
15.9 find_record_ext — Read a DASD record, with extended options
Format
#include <tpfeq.h>
#include <tpfio.h>
void Vfind_record_ext(enum t_lvl level, unsigned int Vaddress,
char Vrecord_id, unsigned char rcc,
enum t_act type, unsigned int ext_find);
| or
| #include <tpfeq.h>
| #include <tpfio.h>
| void Vfind_record_ext(TPF_DECB Vdecb, TPF_FA8 Vfa8,
|
char Vrecord_id, unsigned char rcc,
|
enum t_find_decb find_type, unsigned int ext_find);
level
An ECB level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
|
address
Pointer to the 4-byte file address from where you want the record to be read.
| fa8
|
Pointer to the 8-byte file address in 4x4 format from where you want the record to be read.
record_id
Pointer to the 2-character record ID of the record to be read, or RECID_RESET.
rcc
The record code check (RCC) of the record to be read, or '\0'.
type
An indicator that tells ALCS whether or not you want ALCS to hold the file address of the record. Use
one of the defined values:
NOHOLD
Do not hold the file address of the record.
HOLD
Hold the file address of the record. The entry must unhold the file address before it exits.
| find_type
|
An indicator that tells ALCS whether or not you want ALCS to hold the file address of the record, and
|
whether or not you want ALCS to wait for the I/O operation to complete. Use one of the defined
|
values:
|
|
|
NOHOLD_NOWAIT
Do not hold the file address of the record and do not wait for the I/O operation to complete before
returning to the calling program.
|
|
|
HOLD_NOWAIT
Hold the file address of the record and do not wait for the I/O operation to complete before
returning to the calling program. The entry must unhold the file address before it exits.
366
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
find_record_ext
|
|
|
NOHOLD_WAIT
Do not hold the file address of the record and wait for the I/O operation to complete before
returning to the calling program.
|
|
|
HOLD_WAIT
Hold the file address of the record and wait for the I/O operation to complete before returning to
the calling program. The entry must unhold the file address before it exits.
ext_find
ALCS ignores any values you code in this parameter (provided for compatibility with TPF). See 15.2,
“Common parameters” on page 351.
Description
| When the level parameter is specified, the find_record_ext function reads the record from the file address
specified in the address parameter into a storage block. find_record_ext attaches this storage block on
| the ECB storage level specified in the level parameter.
| find_record_ext updates the ECB data level specified in the level parameter with the file address, record
ID, and record code check (RCC) supplied in the function parameters. It then initiates a read of the record
and suspends the entry until the read is complete.
| When the decb parameter is specified, the find_record_ext function reads the record from the file
| address specified in the fa8 parameter into a storage block. find_record_ext attaches this storage block
| on the storage level of the DECB specified in the decb parameter.
|
|
|
|
|
|
|
find_record_ext updates the data level of the DECB specified in the decb parameter with the file address,
record ID, and record code check (RCC) supplied in the function parameters and then initiates a read of
the record. When the find_type parameter is NOHOLD_WAIT or HOLD_WAIT find_record_ext suspends
the entry until the read is complete. When the find_type parameter is NOHOLD_NOWAIT or
HOLD_NOWAIT, find_record_ext does not wait until the read is complete before returning to the calling
program. You must not make any reference to the storage level in the DECB until you have requested the
waitc function (see “Loss of control” below).
The record ID that you specify in the record_id parameter must match the record ID in the record at the
specified file address. You can supress this check by setting record_id to RECID_RESET.
The record code check (RCC) that you specify in the rcc parameter must match the RCC in the record at
the the specified file address. You can supress this check by setting rcc to '\0'.
| When you specify the type parameter or you specify the find_type parameter as NOHOLD_WAIT or
| HOLD_WAIT, you can test for both these errors by checking that the return value of the function is NULL
(see “Error return” below).
| When you specify the find_type parameter as NOHOLD_NOWAIT or HOLD_NOWAIT, you can test for
| these errors by examining the return value of the subsequent waitc function (which is required, see “Loss
| of control” below).
| If the entry has already initialized the specified data level (for example, by a previous call of the face,
| facs, tpf_fac8c, raisa, gdsnc or gdsrc functions) you can bypass ALCS’s initialization of the data level. To
| do so, code the record_id and address or fa8 parameters as NULL.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Chapter 15. ALCS API functions — reference
367
find_record_ext
Normal return
| When you specify the type parameter or you specify the find_type parameter as NOHOLD_WAIT or
| HOLD_WAIT, normal return is a pointer to the storage block containing the DASD record.
| When you specify the find_type parameter as NOHOLD_NOWAIT or HOLD_NOWAIT, normal return is
| NULL.
Error return
| When you specify the type parameter or you specify the find_type parameter as NOHOLD_WAIT or
| HOLD_WAIT, error return is NULL if this or any outstanding I/O operation was unsuccessful.
| Detailed error information is in the detail error byte for ECB data level n (ecbptr()->ce1sud[n]), or the
| DECB (idecsud). See ALCS Application Programming Guide.
| When you specify the find_type parameter as NOHOLD_NOWAIT or HOLD_NOWAIT, error return is not
| applicable.
Loss of control
| The function can cause the entry to lose control.
| When you specify the type parameter or you specify the find_type parameter as NOHOLD_WAIT or
| HOLD_WAIT, the return value of the function tells the application whether the read was successful.
|
|
|
|
When you specify the find_type parameter as NOHOLD_NOWAIT or HOLD_NOWAIT, you must follow the
function call (at some stage) with a waitc call, or with a call to a function that has an implied waitc. The
return from the waitc, or the function containing the implied waitc, lets you check whether the preceding
I/O operations, including this find, were successful.
|
Examples
This example reads a record from a general data set. It checks that the record ID is 'CD' but does not
| check the RCC. The storage block will be attached to ECB level D7.
#include <tpfeq.h>
#include <tpfio.h>
unsigned file_ptr;
..
.
ecbptr()->ecbfa7 = xd2f5;
/V general file address to read V/
find_record_ext(D7,&ecbptr()->ecbfa7,"CD",'\',NOHOLD,FIND_GDS);
| This example uses the tpf_fac8c function to obtain the file address of the fixed-file record with type
| #XMPRI and record ordinal 8. It then reads and holds the record. It does not check the record id or RCC.
| The storage block will be attached to the specified DECB.
368
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
find_record_ext
| #include <tpfeq.h>
| #include <tpfio.h>
|
|
|
||
|
|
|
|
TPF_DECB Vdecb;
TPF_FAC8 fac8parms;
unsigned int fileptr;
..
.
fac8parms.ifacord = 8;
memcpy(fac8parms.ifacrec, "#XMPRI␣␣", sizeof(fac8parms.ifacrec));
fac8parms.ifactyp = IFAC8FCS;
|
|
|
|
|
|
|
|
|
|
if ( tpf_fac8c(&fac8parms) == TPF_FAC8_NRM )
{
/V normal return V/
fileptr = (unsigned int)find_record_ext(decb,
&fac8parms.ifacadr, RECID_RESET, '\', HOLD_WAIT);
}
else
{
/V error return V/
}
Related information
|
|
|
|
|
|
|
|
|
|
12.7, “FILEC – Write a DASD record” on page 263.
15.9, “find_record_ext — Read a DASD record, with extended options” on page 366.
12.17, “GDSNC – Open or close a general data set” on page 370.
12.18, “GDSRC – Compute a general data set record file address” on page 373.
-- Heading 'RAISA' unknown --.
15.25, “tpf_fac8c — Compute an online 8-byte file address” on page 404.
15.26, “tpf_fa4x4c — Convert a file address” on page 406.
12.31, “UNFRC – Unhold a file address” on page 319.
15.28, “unfrc_ext — Unhold a file address, with extended options” on page 410.
-- Heading 'WAITC' unknown --.
Chapter 15. ALCS API functions — reference
369
gdsnc
15.10 gdsnc — Open or close a general data set
Format
#include <tpfeq.h>
#include <tpfapi.h>
int gdsnc(enum t_lvl level, unsigned char op, enum t_blktype size,
int rrn_fmt, char Vdsn);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| int gdsnc(TPF_DECB Vdecb, unsigned char op, enum t_blktype size,
|
int rrn_fmt, char Vdsn);
level
One of the ECB levels (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
op Specifies whether the data set is to be opened or closed. Use one of the values: GDSNC_OPEN, or
GDSNC_CLOSE.
size
The size of the record. Use one of the defined block sizes: L1, L2, ...., L8.
rrn_fmt
This parameter is for compatibility with TPF and has no effect in ALCS. (In ALCS all general data
sets are VSAM data sets.) Use one of the defined values: GDSNC_TPF_FMT or
GDSNC_NOT_TPF_FMT.
dsn
A pointer to a 16-byte char array containing the data set name. The data set name must be
left-justified and the array padded with blanks.
Description
Use the gdsnc function to open or close a general data set. (The action depends on the value of the op
parameter.) When you use gdsnc to open a general data set, it returns the file address of a record in the
general data set.
| Before calling gdsnc, you must set up a value in the first fullword of the data extension field in the ECB
| level specified in the level parameter (ce1fxn), or in the DECB specified in the decb parameter (idecfx).
ALCS interprets this integer as the relative record number of the record you want to access. (The first
record in a general data set has relative record number 0, the second 1, and so on.)
After calling gdsnc to open a general data set, an application program can read the record at the supplied
file address (for example, by calling a findc function) or write a record to it (for example, by calling a
filec function). However, the read or write function might require the application program to set up the
record ID (and optionally the RCC) in the data level before calling the function. The gdsnc function does
not set up these values.
370
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
gdsnc
When an application has read or written one record from the general data set, it can get the file address of
subsequent records in the general data set by calling the gdsrc function.
When an entry has finished processing, it must close the general data set, using gdsnc with the
GDSNC_CLOSE value of op, before exiting.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
Zero.
Error return
ALCS sets this as follows:
| 4
|
|
| 16
Open completed without error but the relative record number is invalid (defined value
BAD_DSN_RRN). The entry can use the general data set, but must first get a valid file address using
gdsrc.
Open failed (defined value DSN_NOT_MNT). The entry cannot use the general data set.
Loss of control
This function does not cause the entry to lose control.
|
Examples
| This example opens a general data set on ECB level 9 (D9). The data set name is VM1.KMV.FILE and it
contains size L2 records.
#include <tpfeq.h>
#include <tpfapi.h>
int zero=;
| memcpy(&ecbptr->ce1fx9[],&zero,4);
| switch (gdsnc(D9,GDSNC_OPEN,L2,GDSNC_TPF_FMT,"VM1.KMV.FILE␣␣␣␣"))
| {
|
case : break;
|
case 4: errno = x123;
|
perror("Relative record number is invalid");
|
abort();
|
case 16: errno = x234;
|
perror("Cannot open the requested general data set");
|
abort();
}
| This example opens a general data set and sets a relative record number to access the sixth record in
| that data set using the specified DECB. The data set name name is VM1.KSC.FILE and it contains size
| L3 records.
Chapter 15. ALCS API functions — reference
371
gdsnc
| #include <tpfeq.h>
| #include <tpfapi.h>
| TPF_DECB Vdecb;
| int
rrn = 5;
| memcpy(&decb->idecfx,&rrn,4);
| switch (gdsnc(decb,GDSNC_OPEN,L3,GDSNC_TPF_FMT,"VM1.KSC.FILE␣␣␣␣"))
| {
|
case : break;
|
case 4: errno = x123;
|
perror("Relative record number is invalid");
|
abort();
|
case 16: errno = x234;
|
perror("Cannot open the requested general data set");
|
abort();
| }
Related information
12.18, “GDSRC – Compute a general data set record file address” on page 373.
-- Heading 'RAISA' unknown --.
372
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
gdsrc
15.11 gdsrc — Compute the file address of a general data set record
Format
#include <tpfeq.h>
#include <tpfapi.h>
int gdsrc(enum t_lvl level, enum t_blktype size, char Vdsn);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| int gdsrc(TPF_DECB Vdecb, enum t_blktype size, char Vdsn);
level
One of the ECB levels (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
size
The size of the record. Use one of the defined block sizes: L1, L2, ...., L8.
dsn
A pointer to a 16-byte char array containing the data set name. The data set name must be
left-justified and the array padded with blanks.
Description
Use the gdsrc function to compute the file address of a record in a general data set. The general data set
must be open (opened using the gdsnc function.)
| Before calling gdsrc, you must set up a value in the first fullword of the data extension field in the ECB
| level specified in the level parameter (ce1fxn), or in the DECB specified in the decb parameter (idecfx).
ALCS interprets this integer as the relative record number of the record you want to access. (The first
record in a general data set has relative record number 0, the second relative record number 1, and so
on.)
After calling gdsrc to calculate a general data set file address, an application program can read the record
at this file address (for example, by calling a findc function) or write a record to it (for example, by calling
a filec function). However, the read or write function might require the application program to set up the
record ID (and optionally the RCC) in the data level before calling the function. The gdsrc function does
not set up these values before calling the read or write function.
When the entry has finished processing, it must close the general data set, using gdsnc, before exiting.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
Zero.
Error return
Chapter 15. ALCS API functions — reference
373
gdsrc
| 4 The general data set is open but the relative record number is invalid (defined value
|
BAD_DSN_RRN).
| 16 The general data set is not open, so gdsrc cannot be used (defined value DSN_NOT_MNT). (Use
the gdsnc function instead.)
Loss of control
This function does not cause the entry to lose control.
|
Example
| This example sets a relative record number to access the third record in a general data set using ECB
data level 3 (D3). The data set name is MAR.PNJ.FILE.
#include <tpfeq.h>
#include <tpfapi.h>
int rrn=2;
| memcpy(&ecbptr->ce1fx3[],&rrn,4);
| switch (gdsrc(D9,L4,"MAR.PNJ.FILE␣␣␣␣"))
| {
|
case : break;
|
case 4: errno = x123;
|
perror("Relative record number is invalid");
|
abort();
|
case 16: errno = x234;
|
perror("General data set is not open");
|
abort();
}
| This example sets a relative record number to access the second record in a general data set using the
| specified DECB. The data set name is JUN.PNJ.FILE.
| #include <tpfeq.h>
| #include <tpfapi.h>
| TPF_DECB Vdecb;
| int
rrn=1;
| memcpy(&decb->idecfx,&rrn,4);
| switch (gdsrc(decb,L4,"JUN.PNJ.FILE␣␣␣␣"))
| {
|
case : break;
|
case 4: errno = x123;
|
perror("Relative record number is invalid");
|
abort();
|
case 16: errno = x234;
|
perror("General data set is not open");
|
abort();
| }
Related information
12.17, “GDSNC – Open or close a general data set” on page 370.
-- Heading 'RAISA' unknown --.
374
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
getcc
15.12 getcc — Get a storage block
Format
#include <tpfeq.h>
#include <tpfapi.h>
void
Vgetcc(enum t_lvl level, enum t_getfmt format, third_parameter
[,int fill_char]);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| void Vgetcc(TPF_DECB Vdecb, enum t_getfmt format, third_parameter
|
[,int fill_char]);
|
|
level
An ECB storage level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351. This is the
ECB storage level on which you want the new block to be attached.
| decb
|
A pointer to a data event control block (DECB). This is the DECB containing the storage level on
|
which you want the new block to be attached.
format
This parameter specifies what the third_parameter in the function represents. Use one of the values:
GETCC_TYPE
The third_parameter is a block size code, L0, L1, ....L8, as defined by your installation.
GETCC_SIZE
The third_parameter is the size of the block, in bytes. ALCS allocates the smallest available block
size that satisfies the request. Specify a number between 146 and the maximum block sizes
defined in your installation.
GETCC_ATTRn or GETCC_PRIME or GETCC_OVERFLOW
The third_parameter is a pointer to a 2-character record ID. ALCS uses the block size defined for
this record ID in the ALCS system generation.
When you specify GETCC_ATTRn, where n is a number 0 to 9, getcc uses this number n as the
record ID qualifier. You can specify GETCC_PRIME as an alternative to GETCC_ATTR0 and
GETCC_OVERFLOW as an alternative to GETCC_ATTR1.
You can additionally specify in the format parameter one or both of the following:
GETCC_FILL
Request getcc to fill the block with the character specified in the fill_char parameter. (By default,
getcc fills the block with 0x00.)
TPF compatibility
The default storage block fill character in TPF varies by installation. On most TPF systems,
the default is for TPF to fill the storage block with binary zeros as for ALCS. However, in
some TPF installations the default is to leave the storage block uninitialized.
Chapter 15. ALCS API functions — reference
375
getcc
GETCC_COMMON
This value is provided for compatibility with TPF. It has no effect in ALCS.
third_parameter
The meaning of this parameter depends on the value you have specified in the format parameter, as
described above.
fill_char
Specify the character you want getcc to use to fill the storage block. Only use this parameter when
you have specified GETCC_FILL in the format parameter.
Description
| Use the getcc function to get and attach a storage block, of the requested size, to the ECB storage level
| you specify in the level parameter, or the storage level in the DECB you specify in the decb parameter.
(There must be no storage block already attached at this level.)
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
Pointer to the newly obtained storage block.
Error return
Not applicable.
Loss of control
This function does not cause the entry to lose control.
Example
|
|
|
|
This example gets storage blocks on ECB levels 2, 7, 9 and 15 (D2, D7, D9, and DF) and on a DECB.
The first getcc call specifies the block size by coding the record ID, the second and third by specifying the
block size code, and the fourth and fifth by specifying the size in bytes. The last 3 getcc calls fill the block
with space characters. The last getcc call requests a storage block for a DECB.
| Note: The first 4 getcc calls show examples of syntax accepted by the C compiler; the last getcc call
| shows an example of syntax accepted by the C++ compiler.
#include <tpfeq.h>
#include <tpfapi.h>
#include <c$amsg.h>
#define BLANK (' ')
struct amsg Vamsg1;
/V pointers to message blocks V/
Vwork1, Vwork2, Vwork3, Vwork4;
Vdecb1;
..
.
amsg1 = getcc(D2, GETCC_ATTR, "OM");
work1 = getcc(D7, GETCC_TYPE, L2);
/V gets a size L2 block V/
work2 = getcc(D9, GETCC_TYPE+GETCC_FILL, L2, BLANK);
work3 = getcc(DF, GETCC_SIZE+GETCC_FILL, 11, BLANK);
work4 = (char V)getcc(decb1, (enum t_getfmt)(GETCC_SIZE+GETCC_FILL), 2, BLANK);
| char
| TPF_DECB
|
|
376
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
getcc
Related information
15.15, “levtest — Test a storage level” on page 383.
| 12.27, “RCUNC – Release a storage block and unhold a file address” on page 385.
| 12.28, “RELCC – Release a storage block” on page 387.
| 15.27, “tpf_rcrfc — Release a pool-file address and storage block” on page 408.
Chapter 15. ALCS API functions — reference
377
getfc
15.13 getfc — Get a pool-file record address
Format
#include <tpfeq.h>
#include <tpfio.h>
unsigned int getfc(enum t_lvl level, int type, char Vrecord_id, int block,
int error [,int fill_char]);
| or
| #include <tpfeq.h>
| #include <tpfio.h>
| TPF_FA8 getfc(TPF_DECB Vdecb, int type, char Vrecord_id, int block,
|
int error [,int fill_char]);
|
level
An ECB data level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
type
Specify GETFC_TYPEn, where n is a number 0 to 9. getfc uses this number n as the record ID
qualifier. You can specify GETFC_PRIME as an alternative to GETFC_TYPE0 and
GETFC_OVERFLOW as an alternative to GETFC_TYPE1.
record_id
Pointer to a 2-character string which contains the record ID of the pool-file record that you want.
block
Specifies whether or not you want to get a storage block at the same time as a pool-file record. (The
storage block has the same size as the pool-file record.) Code GETFC_BLOCK to get a block and a
file address, or GETFC_NOBLOCK to get only a file address. (When you code GETFC_BLOCK in the
|
block parameter, the specified ECB storage level or DECB must not have an attached storage block.)
By default, ALCS sets the contents of a new storage block to binary zeros. However, you can
optionally also code GETFC_FILL in addition to GETFC_BLOCK. (Separate the two values with a
bitwise or (|) symbol.) If you do so, ALCS fills the storage block with the symbol you supply in the
fill_char character.
TPF compatibility
The default storage block fill character in TPF varies by installation. On most TPF systems, the
default is for TPF to fill the storage block with binary zeros as for ALCS. However, in some TPF
installations the default is to leave the storage block uninitialized.
Note: When you code GETFC_BLOCK, you can additionally code GETFC_COMM or
GETFC_NOCOMM in the block parameter. This is for compatibility with TPF. ALCS ignores either
value.
error
Specifies whether you want ALCS to return control to the program when an error occurs. Code
GETFC_SERRC to transfer control to the system error routine (with exit) when the ALCS cannot get a
file address or storage block. Code GETFC_NOSERRC if you want control returned to the program.
378
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
getfc
fill_char
Specify the character you want getfc to use to fill the storage block. Only use this parameter when
you have specified GETFC_BLOCK and GETFC_FILL in the block parameter.
Description
Use the getfc function to get a pool file address (and optionally, a working storage block) for use by the
program.
The record_id and type parameters determine the type of pool-file record (long-term or short-term pool)
and its block size (L1, L2, L3, ... L8).
In the ALCS generation, the system programmer allocates record IDs so that ALCS can determine the
type and size of a requested pool-file record from the record ID and qualifier.
| Type TPF_FA8 is defined in <c$decb.h> (#included by <tpfio.h>).
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
| Unsigned integer value representing a file address, or an 8-byte file address in 4x4 format (defined type
| TPF_FA8).
Error return
| Integer value of zero or type TPF_FA8 with a value of zero, when GETFC_NOSERRC is coded, otherwise
not applicable.
Loss of control
This function can cause the entry to lose control.
Examples
|
1. This example gets a file address for a message block on ECB level 2 (D2), and a storage block of the
appropriate size on the same level. The record ID is 'OM' with a qualifier of 0.
#include <tpfeq.h>
#include <tpfio.h>
#include <c$amsg.h>
struct amsg Vamsg
/V pointers to message blocks
V/
..
.
amsg = ecbptr()->ce1cr1;
/V Base prime message block
V/
if (!(amsg->amfch = getfc(D2,GETFC_PRIME,"OM",GETFC_BLOCK,GETFC_NOSERRC)))
exit(x331);
/V Dump with exit if getfc() failed V/
|
2. This example gets a file address on ECB level 15 (DF) together with a storage block of the
appropriate size on the same level. The record ID is 'XI' with a qualifier of 1. It fills the storage
block with the character 'F' and prints the file address.
Chapter 15. ALCS API functions — reference
379
getfc
#include <tpfeq.h>
#include <tpfio.h>
unsigned int fa;
fa = getfc(DF,GETFC_TYPE1,"XI",GETFC_BLOCK|GETFC_NOCOMM|
GETFC_FILL,GETFC_NOSERRC,'F');
printf("file address obtained = %8X",fa);
|
|
3. This example gets a file address for a message block on a DECB together with a storage block of the
appropriate size on the same DECB. The record ID is 'OM' with a qualifier of 0.
|
|
|
|
|
#include
#include
#include
TPF_FA8
TPF_DECB
|
|
|
if (!(fa = getfc(decb,GETFC_TYPE1,"OM",
(int)(GETFC_BLOCK|GETFC_FILL),GETFC_NOSERRC,' ')))
exit(x331);
/V Dump with exit if getfc failed V/
<tpfeq.h>
<tpfio.h>
<c$amsg.h>
fa;
Vdecb;
Related information
| 15.14, “getfc_alt — Get a pool-file record address” on page 381.
| 12.29, “RELFC – Release a pool-file record address” on page 389.
| 15.27, “tpf_rcrfc — Release a pool-file address and storage block” on page 408.
380
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
getfc_alt
15.14 getfc_alt — Get a pool-file record address
Format
#include <tpfeq.h>
#include <tpfio.h>
unsigned int getfc_alt(enum t_lvl level, int term, enum t_blktype size, int block, int error);
| or
| #include <tpfeq.h>
| #include <tpfio.h>
| TPF_FA8 getfc_alt(TPF_DECB Vdecb, int term, enum t_blktype size, int block, int error);
|
level
An ECB data level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
term
Specify GETFC_LONG for long-term pool or GETFC_SHORT for short-term pool.
size
A block size code (L0, L1 ..., L8) as defined by your installation.
block
Specifies whether or not you want to get a storage block at the same time as a pool-file record. (The
storage block has the same size as the pool-file record.) Code GETFC_BLOCK to get a block and a
file address, or GETFC_NOBLOCK to get only a file address. (When you code GETFC_BLOCK in the
|
block parameter, the specified ECB storage level or DECB must not have an attached storage block.)
error
Specifies whether you want ALCS to return control to the program when an error occurs. Code
GETFC_SERRC to transfer control to the system error routine (with exit) when ALCS cannot get a file
address or storage block. Code GETFC_NOSERRC if you want control returned to the program.
Description
Use the getfc_alt function to get a pool file address (and optionally, a working storage block) for use by
the program without specifying a record_id. The type of pool-file record (long-term or short-term) and its
block size (L1, L2, L3, ... L8) are explicitly coded.
| Type TPF_FA8 is defined in <c$decb.h> (#included by <tpfio.h>).
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
| Unsigned integer value representing a file address, or an 8-byte file address in 4x4 format (defined type
| TPF_FA8).
Chapter 15. ALCS API functions — reference
381
getfc_alt
Error return
| Integer value of zero or type TPF_FA8 with a value of zero, when GETFC_NOSERRC is coded, otherwise
not applicable.
Loss of control
This function can cause the entry to lose control.
|
Examples
| This example gets an L3 long-term pool file address on ECB level 15 (DF) together with a storage block of
the same size on the same level.
#include <tpfeq.h>
#include <tpfio.h>
unsigned int fa;
fa = getfc_alt(DF,GETFC_LONG,L3,GETFC_BLOCK,GETFC_NOSERRC);
| This example gets an L2 short-term pool file address on the level of a DECB together with a storage block
| of the same size on the same DECB level.
|
|
|
|
#include
#include
TPF_FA8
TPF_DECB
<tpfeq.h>
<tpfio.h>
fa;
Vdecb;
| fa = getfc_alt(decb,GETFC_SHORT,L2,GETFC_BLOCK,GETFC_NOSERRC);
Related information
12.20, “GETFC – Get a pool-file record address” on page 378.
12.29, “RELFC – Release a pool-file record address” on page 389.
| 15.27, “tpf_rcrfc — Release a pool-file address and storage block” on page 408.
382
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
levtest
15.15 levtest — Test a storage level
Format
#include <tpfeq.h>
#include <tpfapi.h>
int levtest(enum t_lvl level);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| int levtest(TPF_DECB Vdecb);
|
level
An ECB storage level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351.
| decb
|
A pointer to a data event control block (DECB).
Description
| Use the levtest function to test whether a storage block is attached at the specified ECB storage level or
| DECB.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
| When the ECB level or DECB has an attached storage block, this is an integer value representing the size
| of the storage block in bytes. When the ECB level or DECB does not have an attached storage block,
ALCS returns a zero value.
Error return
Not applicable.
Loss of control
This function does not cause the entry to lose control.
|
Examples
| This example gets and addresses a storage block on ECB level 12 (DC) if it does not already have an
| attached storage block. (If level 12 (DC) has an attached block, the example addresses this existing
block.)
Chapter 15. ALCS API functions — reference
383
levtest
#include <tpfeq.h>
#include <tpfapi.h>
|
char Vwork;
..
.
if(!levtest(DC))
work = getcc(DC, GETCC_TYPE, L2);
else
work = ecbptr()->ce1crc;
| This example gets and addresses a storage block on the level of a DECB if it does not already have an
| attached storage block.
| #include <tpfeq.h>
| #include <tpfapi.h>
| char
Vwork;
| TPF_DECB Vdecb;
||
..
|
.
| if(!levtest(decb))
| work = (char V)getcc(decb, GETCC_TYPE, L1);
Related information
12.2, “CRUSA – Release storage blocks from specified levels” on page 357.
12.19, “GETCC – Get a storage block” on page 375.
| 12.27, “RCUNC – Release a storage block and unhold a file address” on page 385.
12.28, “RELCC – Release a storage block” on page 387.
| 15.27, “tpf_rcrfc — Release a pool-file address and storage block” on page 408.
384
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
rcunc
|
15.16 rcunc — Release a storage block and unhold a file address
|
Format
| #include <tpfeq.h>
| #include <tpfio.h>
| void rcunc(enum t_lvl level);
| or
| #include <tpfeq.h>
| #include <tpfio.h>
| void rcunc(TPF_DECB Vdecb);
| level
|
An ECB storage level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351. Identifies the
|
ECB level containing the address of the storage block to be released and the file address to be
|
unheld.
| decb
|
A pointer to a data event control block (DECB). Identifies the DECB containing the address of the
|
storage block to be released and the file address to be unheld.
|
Description
| Use the rcunc function to release a storage block and unhold a file address.
| rcunc is the same as relcc followed by unfrc or unfrc_ext. See the Description sections for relcc,
| unfrc and unfrc_ext.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
|
Normal return
| Void.
|
Error return
| Not applicable.
|
Loss of control
| This function does not cause the entry to lose control.
|
Examples
| This example releases a storage block and unholds the record on ECB level 2.
| #include <tpfeq.h>
| #include <tpfio.h>
||
..
|
.
| rcunc(D2);
| This example releases a storage block and unholds the record on a DECB.
Chapter 15. ALCS API functions — reference
385
rcunc
| #include <tpfeq.h>
| #include <tpfio.h>
| TPF_DECB Vdecb;
||
..
|
.
| rcunc(decb);
|
|
|
|
|
Related information
12.19,
12.28,
12.31,
15.28,
“GETCC – Get a storage block” on page 375.
“RELCC – Release a storage block” on page 387.
“UNFRC – Unhold a file address” on page 319.
“unfrc_ext — Unhold a file address, with extended options” on page 410.
386
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
relcc
15.17 relcc — Release a storage block
Format
#include <tpfeq.h>
#include <tpfapi.h>
void relcc(enum t_lvl level);
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| void relcc(TPF_DECB Vdecb);
|
level
An ECB storage level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351. ALCS
releases the block currently attached at this level.
| decb
|
A pointer to a data event control block (DECB). ALCS releases the block currently attached to this
|
DECB.
Description
| Use the relcc function to release the storage block attached at the ECB storage level you specify in the
| level parameter, or the storage level of the DECB you specify in the decb parameter.
| Ensure that there is a storage block attached at the specified ECB level or DECB when you call relcc.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
Void.
Error return
Not applicable.
Loss of control
This function does not cause the entry to lose control.
|
Examples
| This example tests for the presence of a storage block on ECB level 11 (DB) and releases it if it exists.
#include <tpfeq.h>
#include <tpfapi.h>
..
.
if (levtest(DB))
relcc(DB);
Chapter 15. ALCS API functions — reference
387
relcc
| This example tests for the presence of a storage block attached to a DECB and releases it if it exists.
| #include <tpfeq.h>
| #include <tpfapi.h>
| TPF_DECB Vdecb;
||
..
|
.
| if (levtest(decb))
|
relcc(decb);
Related information
12.2, “CRUSA – Release storage blocks from specified levels” on page 357.
12.19, “GETCC – Get a storage block” on page 375.
| 12.27, “RCUNC – Release a storage block and unhold a file address” on page 385.
| 15.27, “tpf_rcrfc — Release a pool-file address and storage block” on page 408.
388
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
relfc
15.18 relfc — Release a pool-file record address
Format
#include <tpfeq.h>
#include <tpfio.h>
void relfc(enum t_lvl level);
| or
| #include <tpfeq.h>
| #include <tpfio.h>
| void relfc(TPF_DECB Vdecb);
|
|
level
An ECB data level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351. This is the ECB
data level containing the pool-file record address that is to be released.
| decb
|
A pointer to a data event control block (DECB). This is the DECB containing the pool-file record
|
address that is to be released.
Description
| Use the relfc function to release the pool-file record address currently in the ECB data level that you
| specify in the level parameter, or the data level of the DECB that you specify in the decb parameter.
If the file address you are releasing exists in other records, or in the application global area, set these
references to zero before calling relfc. Otherwise the database will be inconsistent.
Do not reference a file address after it has been released.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
Normal return
Void.
Error return
Not applicable.
Loss of control
This function can cause the entry to lose control.
Chapter 15. ALCS API functions — reference
389
relfc
|
Examples
The following example releases all forward chain pool-file records from a message block, and sets the
forward chain field in the prime message block to zero. The prime message block is attached at level 1
(D1).
#include <tpfeq.h>
#include <tpfio.h>
#include <c$amsg.h>
struct amsg Vprime,Vchain;
unsigned int adrs[1];
int j,i = ;
/V Pointers to message blocks
V/
prime = ecbptr()->ce1cr1;
chain = prime;
/V Base prime message block
V/
while(chain->amfch != )
/V Obtain all chain addresses
{
adrs[i] = chain->amfch;
crusa(D2);
/V Release last storage block
chain = find_record(D2,&adrs[i++],"OM",'\',NOHOLD);
}
for(j = ; j < i; j++)
{
ecbptr()->ce1fm2 = adrs[j];
relfc(D2);
V/
V/
/V Release all chain addresses V/
/V Set up data level
/V and release the address
V/
V/
}
| The following example releases a pool-file record that is held in the DECB named POOLREC.
| #include <tpfeq.h>
| #include <tpfio.h>
| #include <c$decb.h>
|
|
|
||
|
|
|
|
|
|
|
TPF_DECB Vdecb;
DECBC_RC rc;
char
decb_name[17] = "POOLREC
";
..
.
if ((decb = tpf_decb_locate(decb_name, &rc)) != NULL)
relfc(decb);
else
{
/V error V/
}
Related information
12.20, “GETFC – Get a pool-file record address” on page 378.
15.14, “getfc_alt — Get a pool-file record address” on page 381.
-- Heading 'RLCHA' unknown --.
| 15.27, “tpf_rcrfc — Release a pool-file address and storage block” on page 408.
390
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
sonic
15.19 sonic — Get symbolic file address information
Format
#include <tpfeq.h>
#include <tpfapi.h>
unsigned long sonic(enum t_lvl level)
| or
| #include <tpfeq.h>
| #include <tpfapi.h>
| unsigned long sonic(TPF_FA8 Vfa8)
|
|
level
An ECB data level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351. This is the ECB
data level containing the file address.
| fa8
|
A pointer to an 8-byte file address.
Description
You can use the sonic function to return information about a file address.
| Note: Applications that call this function using an 8-byte file address instead of an ECB data level must
| be compiled with the C++ compiler because this function has been overloaded.
Normal return
The return value of sonic contains non-exclusive bit settings which you can test using the following
defined values:
SONIC_TYPE_INDICATOR
If set, the record is a pool-file record; if unset, the record is a fixed-file record.
|
SONIC_POOL_LONGEVITY
If set, the record is a short-term pool-file record; if unset, the record is a long-term pool-file record
(SONIC_TYPE_INDICATOR must be set).
SONIC_FADDR_INVALID
If set, the file address is invalid; if unset, the file address is valid.
SONIC_REC_SIZE
If set, the record size is at least 1055 bytes; if unset, the record size is less than 1055 bytes.
For compatibility with TPF, you can also test for the following bit settings: SONIC_ADDRESS_FORMAT,
SONIC_FARF4_ADDRESS, SONIC_FARF5_ADDRESS, SONIC_RECORD_UNIQUE,
SONIC_ALT_REC_SIZE, and SONIC_DUPLICATED. In ALCS, these are always unset.
Error return
sonic returns the value SONIC_ERROR.
Chapter 15. ALCS API functions — reference
391
sonic
Loss of control
This function does not cause the entry to lose control.
|
Examples
| This example returns information about the file address in ECB data level 4 (D4).
| #include <tpfeq.h>
| #include <tpfapi.h>
| unsigned long ret_code;
||
..
|
.
| ret_code = sonic(D4);
| if (ret_code == SONIC_ERROR)
| {
|
/V error V/
| }
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
if (ret_code & SONIC_FADDR_INVALID)
{
/V invalid file address V/
}
else
{
if (ret_code & SONIC_TYPE_INDICATOR)
{
/V pool-file record V/
if (ret_code & SONIC_POOL_LONGEVITY)
{
/V short-term pool-file record V/
}
else
{
/V long-term pool-file record V/
}
}
else
{
/V fixed-file record V/
}
|
|
|
|
|
|
|
|
| }
if (sonic_return & SONIC_REC_SIZE)
{
/V record size >= 155 bytes V/
}
else
{
/V record size < 155 bytes V/
}
| This example returns information about an 8-byte file address.
| #include <tpfeq.h>
| #include <tpfapi.h>
| unsigned long ret_code;
| TPF_FA8 fa8;
||
..
|
.
| ret_code = sonic(fa8);
392
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
sonic
Related information
-- Heading 'RONIC' unknown --.
Chapter 15. ALCS API functions — reference
393
tpf_decb_create
|
15.20 tpf_decb_create — Create a data event control block
|
Format
| #include <tpfeq.h>
| #include <c$decb.h>
| TPF_DECB Vtpf_decb_create(char Vname, DECBC_RC Vrc);
| name
|
A pointer to a 16-byte user-specified DECB name. The name parameter is optional. If NULL is coded,
|
a name is not assigned to the DECB.
| rc A pointer to the return code. The rc parameter is optional. If NULL is coded, the return code will not
|
be set.
|
Description
| Use the tpf_decb_create function to allocate storage for a single data event control block (DECB),
| initialize it and attach it to the ECB.
|
|
|
|
The DECB is an alternative to an ECB level, which is used to identify a DASD record that is to be read or
written and to attach a storage block. The DECB fields specify the same data level and storage level
information without requiring the use of an ECB level. All the same requirements and conditions that
apply to the data level and storage level in the ECB also pertain to the same fields in the DECB.
| The data level in the DECB provides storage for an 8-byte file address in 4x4 format.
| The structure of the DECB (defined type TPF_DECB) is defined in <c$decb.h> and described in ALCS
| Application Programming Guide.
| The type DECBC_RC is defined in <c$decb.h>.
|
|
|
|
|
The functions that support the use of a DECB (for example file_record_ext and find_record_ext) will
only accept a DECB address as a valid reference to a DECB. If an application does not maintain the
address of a particular DECB and instead maintains the name of the DECB, the caller must first issue the
tpf_decb_locate function to obtain the address of the desired DECB. The resulting DECB address may
then be passed on to the subsequent function call.
| DECB names beginning with the letters I, i, TPF, TPF_, tpf, and tpf_ are reserved for future use by IBM.
| Note: Applications that use DECBs must be compiled with the C++ compiler.
|
Normal return
| A pointer to a DECB (defined type TPF_DECB) and the return code rc (defined type DECBC_RC) is set to the
| defined value DECBC_OK.
|
Error return
| A NULL pointer and the return code rc (defined type DECBC_RC) contains the defined value
| DECBC_DUPNAME if the name parameter specified contains a DECB name that already exists for this
| ECB.
394
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
tpf_decb_create
|
Loss of control
| This function does not cause the entry to lose control.
|
Example
| This example creates a DECB with the name "APPLWXY".
| #include <tpfeq.h>
| #include <c$decb.h>
|
|
|
|||
|
|
|
|
|
|
|
|
DECBC_RC rc;
TPF_DECB Vdecb;
char
decb_name[17] = "APPLWXY
";
...
if ( (decb = tpf_decb_create(decb_name, &rc)) != NULL )
{
/V DECB is successfully created V/
}
else
{
/V failed to create DECB, check rc for the reason V/
}
|
Related information
|
|
|
|
|
ALCS Application Programming Guide.
15.21, “tpf_decb_locate — Locate a data event control block” on page 396.
15.22, “tpf_decb_release — Release a data event control block” on page 398.
15.23, “tpf_decb_swapblk — Swap a storage block between an ECB level and a DECB” on page 400.
15.24, “tpf_decb_validate — Validate a data event control block” on page 402.
Chapter 15. ALCS API functions — reference
395
tpf_decb_locate
|
15.21 tpf_decb_locate — Locate a data event control block
|
Format
| #include <tpfeq.h>
| #include <c$decb.h>
| TPF_DECB Vtpf_decb_locate(char Vname, DECBC_RC Vrc);
| or
| #include <tpfeq.h>
| #include <c$decb.h>
| TPF_DECB Vtpf_decb_locate(TPF_DECB Vdecb, DECBC_CHAIN chain, DECBC_RC Vrc);
| name
|
A pointer to a 16-byte user-specified DECB name, as specified on a preceding tpf_decb_create call.
| decb
|
A pointer to the current DECB. If NULL is specified, the first DECB, as specified by the chain
|
parameter, will be returned.
| chain
|
Indicates whether an active DECB or any DECB will be returned. Use one of the defined values:
|
|
DECBC_CHAIN_INUSE
Indicates the next active DECB after the current DECB will be returned.
|
|
DECBC_CHAIN_ANY
Indicates the next DECB, active or inactive, after the current DECB will be returned.
| rc A pointer to the return code. The rc parameter is optional. If NULL is coded, the return code will not
|
be set.
|
Description
| Use the format of the tpf_decb_locate function with the name parameter to determine the address of a
| previously allocated data event control block (DECB) from it's associated name.
| Alternatively use the format of the tpf_decb_locate function with the chain parameter to step through each
| DECB associated with the ECB.
|
|
|
|
The DECB is an alternative to an ECB level, which is used to identify a DASD record that is to be read or
written and to attach a storage block. The DECB fields specify the same data level and storage level
information without requiring the use of an ECB level. All the same requirements and conditions that
apply to the data level and storage level in the ECB also pertain to the same fields in the DECB.
| The data level in the DECB provides storage for an 8-byte file address in 4x4 format.
| The structure of the DECB (defined type TPF_DECB) is defined in <c$decb.h> and described in ALCS
| Application Programming Guide.
| The type DECBC_RC is defined in <c$decb.h>.
| The functions that support the use of a DECB (for example file_record_ext and find_record_ext) will
| only accept a DECB address as a valid reference to a DECB. If an application does not maintain the
396
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
tpf_decb_locate
| address of a particular DECB and instead maintains the name of the DECB, the caller must first issue the
| tpf_decb_locate function to obtain the address of the desired DECB. The resulting DECB address may
| then be passed on to the subsequent function call.
| Note: Applications that use DECBs must be compiled with the C++ compiler.
|
Normal return
| A pointer to a DECB (defined type TPF_DECB) and the return code rc (defined type DECBC_RC) is set to the
| defined value DECBC_OK.
|
Error return
| A NULL pointer and the return code rc (defined type DECBC_RC) contains the defined value
| DECBC_NOTFOUND if the name parameter specified contains a DECB name that is not valid for this
| ECB.
|
Loss of control
| This function does not cause the entry to lose control.
|
Example
| This example locates the DECB with the name "APPLWXY".
| #include <tpfeq.h>
| #include <c$decb.h>
|
|
|
||
|
|
|
|
|
|
|
|
|
DECBC_RC rc;
TPF_DECB Vdecb;
char
decb_name[17] = "APPLWXY
";
..
.
if ( (decb = tpf_decb_locate(decb_name, &rc)) != NULL )
{
/V DECB is successfully located V/
}
else
{
/V failed to locate DECB, check rc for the reason V/
}
|
Related information
|
|
|
|
|
ALCS Application Programming Guide.
15.20, “tpf_decb_create — Create a data event control block” on page 394.
15.22, “tpf_decb_release — Release a data event control block” on page 398.
15.23, “tpf_decb_swapblk — Swap a storage block between an ECB level and a DECB” on page 400.
15.24, “tpf_decb_validate — Validate a data event control block” on page 402.
Chapter 15. ALCS API functions — reference
397
tpf_decb_release
|
15.22 tpf_decb_release — Release a data event control block
|
Format
| #include <tpfeq.h>
| #include <c$decb.h>
| void tpf_decb_release(TPF_DECB Vdecb);
| or
| #include <tpfeq.h>
| #include <c$decb.h>
| void tpf_decb_release(char Vname);
| decb
|
A pointer to the data event control block (DECB) to be released.
| name
|
A pointer to a 16-byte user-specified DECB name. The name must have been specified on a previous
|
tpf_decb_create call.
|
Description
| Use the tpf_decb_release function to release a data event control block (DECB) previously created with
| the tpf_decb_create function. The DECB is detached from the ECB and the storage is available to be
| allocated to other DECBs.
|
|
|
|
The DECB is an alternative to an ECB level, which is used to identify a DASD record that is to be read or
written and to attach a storage block. The DECB fields specify the same data level and storage level
information without requiring the use of an ECB level. All the same requirements and conditions that
apply to the data level and storage level in the ECB also pertain to the same fields in the DECB.
| The data level in the DECB provides storage for an 8-byte file address in 4x4 format.
| Note: Applications that use DECBs must be compiled with the C++ compiler.
|
Normal return
| Void.
|
Error return
| Not applicable.
|
Loss of control
| This function does not cause the entry to lose control.
|
Example
| This example locates a DECB and releases it.
398
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
tpf_decb_release
| #include <tpfeq.h>
| #include <c$decb.h>
|
|
|
||
|
|
|
|
|
|
|
|
|
DECBC_RC rc;
TPF_DECB Vdecb;
char
decb_name[17] = "APPLWXY
";
..
.
if ( (decb = tpf_decb_locate(decb_name, &rc)) != NULL )
{
tpf_decb_release(decb); /V release the decb that was located V/
}
else
{
/V failed to locate DECB, check rc for the reason V/
}
|
|
|
|
|
Related information
15.20,
15.21,
15.23,
15.24,
“tpf_decb_create — Create a data event control block” on page 394.
“tpf_decb_locate — Locate a data event control block” on page 396.
“tpf_decb_swapblk — Swap a storage block between an ECB level and a DECB” on page 400.
“tpf_decb_validate — Validate a data event control block” on page 402.
Chapter 15. ALCS API functions — reference
399
tpf_decb_swapblk
|
15.23 tpf_decb_swapblk — Swap a storage block between an ECB level
and a DECB
|
Format
|
| #include <tpfeq.h>
| #include <c$decb.h>
| void tpf_decb_swapblk(TPF_DECB Vdecb, enum t_lvl level);
| decb
|
A pointer to the data event control block (DECB).
| level
|
An ECB storage level, see 15.2, “Common parameters” on page 351.
|
Description
| Use the tpf_decb_swapblk function to swap a storage block between an ECB storage level and the
| storage level in a data event control block (DECB). Only the storage level is swapped; the data level in
| both the ECB and the DECB remains unchanged.
|
|
|
|
The DECB is an alternative to an ECB level, which is used to identify a DASD record that is about to be
read or written and to attach a storage block. The DECB fields specify the same data level and storage
level information without requiring the use of an ECB level. All the same requirements and conditions that
apply to the data level and storage level in the ECB also pertain to the same fields in the DECB.
| Note: Applications that use DECBs must be compiled with the C++ compiler.
|
Normal return
| Void.
|
Error return
| Not applicable.
|
Loss of control
| This function does not cause the entry to lose control.
|
Example
| This example swaps the storage level and associated block information between ECB storage level 2 (D2)
| and the specified DECB.
| #include <tpfeq.h>
| #include <c$decb.h>
| TPF_DECB Vdecb;
||
..
|
.
| tpf_decb_swapblk(decb, D2); /V swap storage block between decb and D2 V/
400
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
tpf_decb_swapblk
|
|
|
|
|
Related information
15.20,
15.21,
15.22,
15.24,
“tpf_decb_create — Create a data event control block” on page 394.
“tpf_decb_locate — Locate a data event control block” on page 396.
“tpf_decb_release — Release a data event control block” on page 398.
“tpf_decb_validate — Validate a data event control block” on page 402.
Chapter 15. ALCS API functions — reference
401
tpf_decb_validate
|
15.24 tpf_decb_validate — Validate a data event control block
|
Format
| #include <tpfeq.h>
| #include <c$decb.h>
| DECBC_RC tpf_decb_validate(TPF_DECB Vdecb);
| decb
|
A pointer to a data event control block (DECB).
|
Description
| Use the tpf_decb_validate function to determine whether the specified storage address is the address of
| an active and valid data event control block (DECB).
|
|
|
|
The DECB is an alternative to an ECB level, which is used to identify a DASD record that is to be read or
written and to attach a storage block. The DECB fields specify the same data level and storage level
information without requiring the use of an ECB level. All the same requirements and conditions that
apply to the data level and storage level in the ECB also pertain to the same fields in the DECB.
| The structure of the DECB (defined type TPF_DECB) is defined in <c$decb.h> and described in ALCS
| Application Programming Guide.
| The type DECBC_RC is defined in <c$decb.h>.
| Note: Applications that use DECBs must be compiled with the C++ compiler.
|
Normal return
| The return code (defined type DECBC_RC) is set to the defined value DECBC_OK.
|
Error return
| The return code (defined type DECBC_RC) is set to the defined value DECBC_NOTVALID.
|
Loss of control
| This function does not cause the entry to lose control.
|
Example
| This example validates a DECB address.
402
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
tpf_decb_validate
| #include <tpfeq.h>
| #include <c$decb.h>
|
||
|
|
|
|
|
|
|
|
|
TPF_DECB Vdecb;
..
.
if ( tpf_decb_validate(decb) == DECBC_OK )
{
/V decb is valid V/
}
else
{
/V DECB is not valid V/
}
|
Related information
|
|
|
|
|
ALCS Application Programming Guide.
15.20, “tpf_decb_create — Create a data event control block” on page 394.
15.21, “tpf_decb_locate — Locate a data event control block” on page 396.
15.23, “tpf_decb_swapblk — Swap a storage block between an ECB level and a DECB” on page 400.
15.22, “tpf_decb_release — Release a data event control block” on page 398.
Chapter 15. ALCS API functions — reference
403
tpf_fac8c
|
15.25 tpf_fac8c — Compute an online 8-byte file address
|
Format
| #include <tpfeq.h>
| #include <tpfio.h>
| int tpf_fac8c(TPF_FAC8 Vparm);
| parm
|
A pointer to a parameter block described by the structure defined as type TPF_FAC8. Fields in the
|
input area of this block must be initialized by the caller before the function is called. Output area fields
|
will be filled in by the function service routine.
|
Description
| Use the tpf_fac8c function to compute an 8-byte file address based on the input record type and 8-byte
| ordinal number. The service is similar to calling the face or facs functions.
| The data level in a data event control block (DECB) provides storage for the 8-byte file address.
| The structure of the parameter block (defined type TPF_FAC8) is defined in <tpfio.h>. (See 14.21,
| “<tpfio.h>” on page 349.)
| Before calling tpf_fac8c you must set the record ordinal number (ifacord) and the fixed-file record type
| (value (ifacrnb) or symbol (ifacrec)) in the parameter block.
| Before calling tpf_fac8c you must set field (ifactyp) in the parameter block to indicate whether the record
| type specified is a symbol (IFAC8FCS) or a value (IFAC8FCE).
| Note: Applications that use 8-byte file addresses must be compiled with the C++ compiler.
|
|
|
|
|
TPF Compatibility
The 8-byte file address support is required for compatibility with TPF. In ALCS, the tpf_fac8c function
returns an 8-byte file address in 4x4 format, where the high-order 4 bytes contain an indicator (a
full-word of zeros) that classifies it as a valid 4x4 format file address and the low-order 4 bytes contain
an ALCS band format file address.
|
Normal return
|
|
|
|
An integer containing the defined value TPF_FAC8_NRM and the following are stored in fields in the
output area of the parameter block. The ifacret field contains the return code (the same as the return
value from tpf_fac8c), ifacmax contains the maximum ordinal number for the requested record type and
ifacadr contains the 8-byte file address.
|
Error return
| An integer containing one of the following defined values:
| TPF_FAC8_TYP
|
Call type invalid or record type invalid.
404
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
tpf_fac8c
| TPF_FAC8_ORD
|
Record ordinal invalid.
|
Loss of control
| This function does not cause the entry to lose control.
|
Example
| This example generates the file address for ordinal 198 in fixed-file record type #WAARI and stores it in
| the output area of the TPF_FAC8 block.
| #include <tpfeq.h>
| #include <tpfio.h>
|
|||
|
|
|
|
TPF_FAC8 parm;
...
parm.ifacord = 198;
/V set ordinal V/
memcpy(parm.ifacrec, "#WAARI␣␣", sizeof(parm.ifacrec)); /V set rec type V/
parm.ifactyp = IFAC8FCS; /V set call type - rec type is symbol V/
tpf_fac8c(&parm);
/V call tpf_fac8c to calculate file address V/
|
|
|
|
|
|
|
|
if (parm.ifacret != TPF_FAC8_NRM)
{
/V error return V/
}
else
{
/V normal return V/
}
|
|
|
|
|
|
|
Related information
-- Heading 'FACE' unknown --.
-- Heading 'FACS' unknown --.
15.20, “tpf_decb_create — Create a data event control block” on page 394.
15.21, “tpf_decb_locate — Locate a data event control block” on page 396.
15.22, “tpf_decb_release — Release a data event control block” on page 398.
14.21, “<tpfio.h>” on page 349.
Chapter 15. ALCS API functions — reference
405
tpf_fa4x4c
|
15.26 tpf_fa4x4c — Convert a file address
|
Format
| #include <tpfeq.h>
| #include <tpfio.h>
| int tpf_fa4x4c(TPF_FACONV Vaction, unsigned long Vfa4, TPF_FA8 Vfa8);
| or format for use in ALCS only:
| #include <tpfeq.h>
| #include <tpfio.h>
| int tpf_fa4x4c(TPF_FACONV Vaction, unsigned int Vfa4, TPF_FA8 Vfa8);
| action
|
The type of conversion to be performed. Use one of the values:
|
|
FACONV_4TO8
Converts a 4-byte file address to an 8-byte file address in 4x4 format.
|
|
FACONV_8TO4
Converts an 8-byte file address in 4x4 format to a 4-byte file address.
| fa4
|
A pointer to a 4-byte file address. This parameter is the input if action is FACONV_4TO8. This
|
parameter is the output if action is FACONV_8TO4.
| fa8
|
A pointer to an 8-byte file address. This parameter is the input if action is FACONV_8TO4. This
|
parameter is the output if action is FACONV_4TO8.
|
Description
| Use the tpf_fa4x4c function to:
|
1. Convert a 4-byte file address to an 8-byte file address in 4x4 format.
|
2. Convert an 8-byte file address in 4x4 format to a 4-byte file address.
| 4x4 format is an 8-byte file address with a high-order 4-byte indicator (that contains zeros) and a low-order
| 4 bytes that contains an ALCS band format file address.
|
|
|
|
The data level in a data event control block (DECB) provides storage for an 8-byte file address. Use the
tpf_fa4x4c function to convert an existing 4-byte file address to an 8-byte file address and place it in a
DECB data level. Use the tpf_fa4x4c function to convert an 8-byte file address obtained using the data
level in a DECB to a 4-byte file address for subsequent use with an ECB data level.
| Type TPF_FA8 is defined in <c$decb.h> (#included by <tpfio.h>).
| Note: Applications that use 8-byte file addresses must be compiled with the C++ compiler.
|
Normal return
| A non-zero integer.
406
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
tpf_fa4x4c
|
Error return
| An integer value of zero. This can occur if FACONV_8TO4 is specified and the input 8-byte file address is
| not in 4x4 format, or if the specified action is not valid.
|
Loss of control
| This function does not cause the entry to lose control.
|
Example
| This example converts a 4-byte file address to an 8-byte file address and converts an 8-byte file address
| to a 4-byte file address.
| #include <tpfeq.h>
| #include <tpfio.h>
|
|
||
|
|
||
|
|
unsigned long fa4;
TPF_FA8
fa8;
..
.
tpf_fa4x4c(FACONV_4TO8, &fa4, &fa8); /V convert 4-byte fa to 8-byte V/
..
.
tpf_fa4x4c(FACONV_8TO4, &fa4, &fa8); /V convert 8-byte fa to 4-byte V/
| Related information
| 15.20, “tpf_decb_create — Create a data event control block” on page 394.
| 15.21, “tpf_decb_locate — Locate a data event control block” on page 396.
| 15.22, “tpf_decb_release — Release a data event control block” on page 398.
Chapter 15. ALCS API functions — reference
407
tpf_rcrfc
|
15.27 tpf_rcrfc — Release a pool-file address and storage block
|
Format
| #include <tpfeq.h>
| #include <tpfio.h>
| void tpf_rcrfc(enum t_lvl level);
| or
| #include <tpfeq.h>
| #include <tpfio.h>
| void tpf_rcrfc(TPF_DECB Vdecb);
| level
|
An ECB level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351. This indicates the data
|
level containing the pool-file address to be released and the storage level containing the address of
|
the storage block to be released.
| decb
|
A pointer to a data event control block (DECB).
|
Description
| Use the tpf_rcrfc function to release a pool-file address and associated storage block.
| RCRFC is the same as RELCC followed by RELFC. See the Description sections for RELCC and RELFC.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
|
Normal return
| Void.
|
Error return
| Not applicable.
|
Loss of control
| This function does not cause the entry to lose control.
|
Example
| This example releases a storage block and pool-file address from an ECB level and a DECB.
| #include <tpfeq.h>
| #include <tpfio.h>
| TPF_DECB Vdecb;
||
..
|
.
| tpf_rcrfc(D6);
|||
...
| tpf_rcrfc(decb);
408
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
tpf_rcrfc
| Related information
| 12.28, “RELCC – Release a storage block” on page 387.
| 12.29, “RELFC – Release a pool-file record address” on page 389.
Chapter 15. ALCS API functions — reference
409
unfrc_ext
|
15.28 unfrc_ext — Unhold a file address, with extended options
|
Format
| #include <tpfeq.h>
| #include <tpfio.h>
| void unfrc_ext(enum t_lvl level, unsigned int ext_find);
| or
| #include <tpfeq.h>
| #include <tpfio.h>
| void unfrc_ext(TPF_DECB Vdecb, unsigned int ext_find);
| level
|
An ECB data level (D0, D1, ..., DF), see 15.2, “Common parameters” on page 351. This data level
|
contains the file address of the record to be unheld. The file address must have been held by the
|
calling entry.
| decb
|
A pointer to a data event control block (DECB). This DECB contains the file address of the record to
|
be unheld. The file address must have been held by the calling entry.
| ext_find
|
ALCS ignores any values you code in this parameter (provided for compatibility with TPF). See 15.2,
|
“Common parameters” on page 351.
|
Description
|
|
|
|
Use the unfrc_ext function to unhold a file address that the entry has previously held with a finhc, or
fiwhc function call, or a find_record call with a HOLD value of the type parameter. The file address is
contained in the ECB data level specified in the level parameter, or the data level of the DECB specified in
the decb parameter.
| The function does not initiate any I/O and does not check or modify the storage level.
| Note: Applications that call this function using a DECB address instead of an ECB level must be
| compiled with the C++ compiler because this function has been overloaded.
|
Normal return
| Void.
|
Error return
| Not applicable.
|
Loss of control
| This function does not cause the entry to lose control.
|
Examples
| This example unholds the file address on level D7.
410
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
unfrc_ext
| #include <tpfeq.h>
| #include <tpfio.h>
||
..
|
.
| unfrc_ext(D7, FIND_GDS);
| This example unholds the file address in a DECB.
| #include <tpfeq.h>
| #include <tpfio.h>
| TPF_DECB Vdecb;
||
..
|
.
| unfrc_ext(decb, FIND_DEFEXT);
| Related information
| -- Heading 'FINDREC' unknown --.
| 12.12, “FINHC – Read a DASD record and hold the file address” on page 274.
| 12.15, “FIWHC – Read a DASD record, hold the file address, and wait for I/O completion” on page 281.
Chapter 15. ALCS API functions — reference
411
Chapter 16. C library functions available under ISO-C, ALCS,
and TPF
Figure 164 (Page 1 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
FUNCTION NAME
FUNCTION DESCRIPTION
C
ALCS
TPF
abort
Abnormally stops a program
√
■
■
abs
Calculates the absolute value of an integer
√
√
√
acos
Calculates the arc cosine
√
√
√
asctime
Converts time stored as a structure to a character
string in store
√
√
√
asin
Calculates the arc sine
√
√
√
assert
Prints diagnostic message
√
■
■
atan
Calculates the arc tangent of x
√
√
√
atan2
Calculates the arc tangent of x/y
√
√
√
atawait
Waits for one or more asynchronous APPC/MVS
calls to complete
atexit
Records program termination routine
√
√
atof
Converts a character string to float
√
√
√
atoi
Converts a character string to integer
√
√
√
atol
Converts a character string to long integer
√
√
√
attac
Attaches a previously detached storage block
X
X
|
attac_ext
Attaches a previously detached storage block
X
X
|
attac_id
Attaches a previously detached storage block
X
X
bessel
Bessel functions
√
√
bsearch
Performs a binary search of a sorted array
√
√
√
ISO-C
calloc
Reserves storage space for an array and initializes
the values of all elements to 0
√
√
√
ceil
Calculates the double value representing the
smallest integer that is greater than or equal to a
number
√
√
√
cifrc
Cipher program interface
X
cinfc
Extracts data from monitor table
X
cinfc_fast
Extracts data from monitor table, fast
X
clearerr
Resets error indicators
√
√
clock
Determines processor time
√
√
412
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
X
√
ISO-C
Figure 164 (Page 2 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
FUNCTION NAME
FUNCTION DESCRIPTION
C
comic
Gets communication resource information
X
corhc
Defines and holds a resource
X
X
coruc
Unholds a resource
X
X
cos
Calculates the cosine
√
√
√
cosh
Calculates the hyperbolic cosine
√
√
√
credc
Creates an entry for deferred scheduling
X
X
creec
Creates an entry with an attached storage block
X
X
cremc
Creates an entry for immediate scheduling
X
X
cretc
Creates an entry for scheduling after a time delay
X
X
crexc
Creates an entry for deferred scheduling
X
X
crusa
Releases storage blocks from specified levels
X
X
ctime
Converts time stored as a long value to a character
string
√
√
defrc
Defers processing of current entry
X
X
|
detac
Detaches a storage block from the ECB or a DECB
X
X
|
detac_ext
Detaches a storage block from the ECB or a DECB
X
X
|
detac_id
Detaches a storage block from the ECB or a DECB
X
X
difftime
Computes the difference between two times
√
√
√
div
Calculates the quotient and remainder
√
√
√
dlayc
Delays processing of the current entry
X
X
ecbptr
Accesses the entry control block
X
X
entdc
Enters a program with no return allowed to any
program
X
X
entrc
Enters a program with a return expected to the
calling program
X
erf
Calculates the error function
√
√
erfc
Calculates the error function for large numbers
√
√
exit
Normally ends a program
√
■
■
exp
Calculates an exponential function
√
√
√
fabs
Calculates the absolute value of a floating point
number
√
√
√
face
Computes an online file address from a record type
number
X
X
facs
Computes an online file address from a record type
symbol
X
X
fclose
Closes a specified stream
√
√
ALCS
TPF
M
Chapter 16. C library functions available under ISO-C, ALCS, and TPF
413
Figure 164 (Page 3 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
FUNCTION NAME
FUNCTION DESCRIPTION
C
ALCS
feof
Tests end-of-file indicator for stream input
√
M
ferror
Tests the error indicator for a specific stream
√
M
fflush
Causes the system to write the contents of a buffer
to a file
√
M
fgetc
Reads a character from a specified input stream
√
M
fgetpos
Gets the current position of the file pointer
√
M
fgets
Reads a string from a specified input stream
√
M
filec
Writes a DASD record
X
X
filec_ext
Writes a record, with extended options
X
X
file_record
Writes a DASD record
X
X
file_record_ext
Writes a record, extended
X
X
filnc
Writes a DASD record and retains the attached
storage block
X
X
filnc_ext
Writes a DASD record and retains the attached
storage block, with extended options
X
X
filuc
Writes a DASD record and unholds the file address
X
X
filuc_ext
Writes a DASD record and unholds the file address,
with extended options
X
X
findc
Reads a DASD record
X
X
find_record
Reads a DASD record
X
X
find_record_ext
Reads a DASD record, with extended options
X
X
finhc
Raeds a DASD record and holds the file address
X
X
finhc_ext
Reads a DASD record and holds the file address,
with extended options
X
X
finwc
Reads a DASD record and waits for I/O completion
X
X
finwc_ext
Reads a DASD record and waits for I/O completion,
with extended options
X
X
fiwhc
Reads a DASD record, holds the file address, and
waits for I/O completion
X
X
fiwhc_ext
Reads a DASD record, holds the file address, and
waits for I/O completion, with extended options,
X
X
flipc
Exchanges the content of two storage and data
levels
X
X
floor
Calculates the floating point value representing the
largest integer less than or equal to a number
√
√
√
fmod
Calculates the floating point remainder of one
argument divided by another
√
√
√
fopen
Opens a specified stream
√
M
414
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
TPF
Figure 164 (Page 4 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
FUNCTION NAME
FUNCTION DESCRIPTION
C
ALCS
fprintf
Formats and prints characters to the output stream
√
M
fputc
Prints a character to a specified output stream
√
M
fputs
Prints a string to a specified output stream
√
M
fread
Reads items from a specified input stream
√
M
free
Frees storage blocks
√
√
freopen
Closes a file and reassigns a stream
√
M
frexp
Separates a floating point number into its mantissa
and exponent
√
√
fscanf
Reads data from a stream into locations given by
arguments
√
M
fseek
Moves the file pointer to a new location
√
M
fsetpos
Moves the file pointer to a new location
√
M
ftell
Gets the current position of the file pointer
√
M
fwrite
Writes items to a specified output stream
√
M
gamma
Calculates the gamma function
√
√
gdsnc
Opens or closes a general data set
X
X
gdsrc
Computes a general data set record file address
X
X
getc
Reads a character from a specified input stream
getcc
Gets a storage block
getchar
Reads a character from stdin
√
√
getenv
Searches environment variables for a specified
variable
√
√
getfc
Gets a pool file record file address
gets
Reads a line
glob
√
TPF
√
√
M
X
X
X
X
√
■
Addresses an application global field or record
X
X
global
Operates on an application global field
X
X
gmtime
Converts time to a structure
√
√
√
hypot
Calculates the hypotenuse
√
√
inqrc
Converts communication resource identifiers and
names
isalnum
Tests for alphanumeric characters
√
√
√
isalpha
Tests for alphabetic characters
√
√
√
iscntrl
Tests for control characters
√
√
√
isdigit
Tests for decimal digits
√
√
√
isgraph
Tests for printable characters excluding the space
√
√
√
islower
Tests for lowercase letters
√
√
√
√
X
Chapter 16. C library functions available under ISO-C, ALCS, and TPF
415
Figure 164 (Page 5 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
FUNCTION NAME
FUNCTION DESCRIPTION
C
ALCS
TPF
isprint
Tests for printable characters including the space
√
√
√
ispunct
Tests for printable characters excluding the space
√
√
√
isspace
Tests for whitespace characters
√
√
√
isupper
Tests for uppercase letters
√
√
√
isxdigit
Tests for hexadecimal digits
√
√
√
labs
Calculates the absolute value of a long integer
√
√
√
ldexp
Multiplies a floating point number by an integral
power of 2
√
√
√
ldiv
Calculates the quotient and remainder
√
√
√
levtest
Tests a storage level
X
X
localeconv
Formats numeric quantities in struc lconv according
to the current locale
√
√
√
localtime
Converts time to a structure
√
√
√
lodic
Extracts system load information
log
Calculates the natural logarithm
√
√
√
log1
Calculates the base 10 logarithm
√
√
√
longc
Sets maximum entry life
X
X
longjmp
Restores a stack environment
√
√
malloc
Allocates storage
√
√
√
mblen
Determines the length of a string
√
√
√
ISO-C
mbstowcs
Converts multibyte string to codes
√
√
√
ISO-C
mbtowc
Converts multibyte characters to wchar_t characters
√
√
√
ISO-C
memchr
Searches a buffer for the first occurrence of a given
character
√
√
√
memcmp
Compares two buffers
√
√
√
memcpy
Copies a string of bytes
√
√
√
memmove
Moves a string of bytes
√
√
√
memset
Sets a string of bytes to a given value
√
√
√
mktime
Converts local time into calender time
√
√
√
modec
Sets current addressing mode
X
X
modf
Calculates the integer remainder of one argument
divided by another
√
√
mqawait
Waits for one or more assynchronous MQI calls to
complete
416
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
X
√
X
Figure 164 (Page 6 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
|
|
FUNCTION NAME
FUNCTION DESCRIPTION
C
ALCS
TPF
perror
Issues system error with message
√
■
■
Not
in
ISO-C
pow
Calculates the value of an argument raised to a
power
√
√
√
printf
Sends formatted message to terminal
√
√
■
putc
Prints a character to a specified output stream
√
M
putchar
Prints a character to stdout
√
√
puts
Writes a string to stdout
√
√
■
qsort
Performs a search on an array of elements
√
√
√
ISO-C
raisa
Computes the file address of a general file record
raise
Sends signal
√
X
X
rand
Returns a pseudo-random integer
√
√
√
rcunc
Releases a storage block and unholds a file address
X
X
realloc
Changes storage size allocated for an object
√
√
rehka
Rehooks storage address
relcc
Releases a storage block
X
X
relfc
Releases a pool file record file address
X
X
remove
Deletes a specified file
√
M
rename
Renames a specified file
√
M
rewind
Repositions the file pointer to the beginning of the
file
√
M
rlcha
Releases a chain of pool file record file addresses
X
ronic
Returns information about a DASD record or record
type
X
routc
Routes a message to a terminal or application
X
X
scanf
Scans input for variables
√
■
selec
Selects a thread application interface
serrc_op
Requests an error dump
X
X
serrc_op_ext
Requests an error dump, with extended options
X
X
serrc_op_slt
Requests an error dump, with storage list
X
X
setbuf
Allows control of buffering
√
setjmp
Saves a stack environment
√
√
setlocale
Changes or queries locale
√
√
X
√
X
√
X
X
√
Chapter 16. C library functions available under ISO-C, ALCS, and TPF
417
Figure 164 (Page 7 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
FUNCTION NAME
FUNCTION DESCRIPTION
C
setvbuf
Controls buffering and buffer size for a specified
stream
√
signal
Allows handling of an interrupt signal from the
operating system
√
√
sin
Calculates the sine
√
√
√
sinh
Calculates the hyperbolic sine
√
√
√
slimc
Sets or removes processing limits for the entry
X
snapc
Requests an error dump
X
X
sonic
Get information about a file address
X
X
sprintf
Formats and stores characters in a buffer
√
√
√
sqrt
Calculates the square root of a number
√
√
√
srand
Sets the starting point for pseudo-random numbers
√
√
√
sscanf
Reads data from a buffer into locations given by
arguments
√
√
√
strcat
Concatenates two strings
√
√
√
strchr
Locates the first occurrence of a specified character
in a string
√
√
√
strcmp
Compares the value of two strings
√
√
√
strcoll
Compares the locale-defined value of two strings
√
√
√
strcpy
Copies one string to another
√
√
√
strcspn
Finds the length of the first substring in a string of
characters not in a second string
√
√
√
strerror
Sets pointer to system error message
√
√
strftime
Multibyte time conversion
√
√
√
strlen
Calculates the length of a string
√
√
√
strncat
Concatenates a part of a string to another string
√
√
√
strncmp
Compares parts of two strings
√
√
√
strncpy
Copies part of one string to another
√
√
√
strpbrk
Locates specified characters in a string
√
√
√
strrchr
Locates the last occurrence of a set of characters in
a string
√
√
√
strspn
Locates the first character in a string that is not part
of a specified set of characters
√
√
√
strstr
Locates the first occurrence of a string in another
string
√
√
√
strtod
Converts a character string to double
√
√
√
strtok
Locates a specified token in a string
√
√
√
418
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
ALCS
TPF
Figure 164 (Page 8 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
FUNCTION NAME
FUNCTION DESCRIPTION
C
ALCS
TPF
strtol
Converts a character string to long integer
√
√
√
strtold
Converts a character string to a double integer
√
√
√
strtoul
Converts a character string to an unsigned long
integer
√
√
√
strxfrm
Transforms strings according to locale
√
√
√
system
Passes a string to the command interpreter
√
tan
Calculates the tangent
√
√
√
tanh
Calculates the hyperbolic tangent
√
√
√
tape_close
Closes a general sequential file
X
X
tape_cntl
Tape control
tape_open
Opens a general sequential file
X
X
tape_read
Reads a record from a general sequential file
X
X
tape_write
Writes a record to a general sequential file
X
X
tasnc
Assigns a general sequential file
X
X
tbspc
Backspaces a tape and waits
tclsc
Closes a general sequential file
tconfirmed
Sends a confirmation reply
tdspc
Gets information about any type of sequential file
time
Returns the time in seconds
timec
Gets time and date
tmpfile
Creates a temporary file and returns a pointer to that
file
√
tmpnam
Produces a temporary file name
√
tolower
Converts a character to lowercase
√
topnc
Opens a general sequential file
toupper
Converts a character to uppercase
tourc
X
X
√
X
X
X
X
√
√
X
√
√
X
X
√
√
Writes a storage block to a real-time sequential file
X
X
toutc
Writes a record to a real-time sequential file
X
X
|
tpf_decb_create
Creates a DECB
X
X
|
tpf_decb_locate
Locates a DECB
X
X
|
tpf_decb_release
Releases a DECB
X
X
|
|
tpf_decb_swapblk
Swaps a storage level between a DECB and the
ECB
X
X
|
tpf_decb_validate
Validates a DECB
X
X
|
|
tpf_fa4x4c
Converts an 8-byte to a 4-byte file address or a
4-byte to an 8-byte file address
X
X
√
Chapter 16. C library functions available under ISO-C, ALCS, and TPF
419
Figure 164 (Page 9 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
FUNCTION NAME
FUNCTION DESCRIPTION
|
tpf_fac8c
|
|
|
|
ALCS
TPF
Computes an online 8-byte file address
X
X
tpf_rcrfc
Releases a pool-file record address and a storage
block
X
X
tpf_STCK
Gets S/390 TOD clock value
X
X
tppc_activate_
on_confirmation
Activates a program after confirmation received
X
tppc_activate_
on_receipt
Activates a program after information received
X
tppc_allocate
Allocates a conversation
X
tppc_confirm
Sends confirmation request
X
tppc_confirmed
Sends a confirmation reply
X
tppc_deallocate
Deallocates a conversation
X
tppc_flush
Flushes data from a local LU's buffer
X
tppc_get_attributes
Gets information about a conversation
X
tppc_post_on_receipt
Sets posting active for a conversation
X
tppc_prepare_to_receive
Changes to receive status
X
tppc_test
Tests conversation
X
tppc_receive
Receives information
X
tppc_request_to_send
Requests change to send status
X
tppc_send_data
Sends data to remote application program
X
tppc_send_error
Sends error notification
X
tppc_wait
Waits for posting
X
tprdc
Reads a record from a general sequential file
trewc
Rewinds a tape
trsvc
Reserves a general sequential file
tsync
Synchronizes a tape
twrtc
Writes a record to a general sequential file
uatbc
Requests MDBF user attribute
unfrc
Unholds a file address
X
X
unfrc_ext
Unholds a file address, with extended options
X
X
ungetc
Pushes a character back onto a specified input
unhka
Unhooks storage block
va_arg
Allows access to variable number of function
arguments
√
√
√
va_end
Allows access to variable number of function
arguments
√
√
√
420
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
C
X
X
X
X
X
X
X
X
X
√
M
X
Figure 164 (Page 10 of 10). Comparison of C library functions available under ISO-C, ALCS, and TPF.
Key
√ Fully compatible with ISO-C standards
X Supported but not an ISO-C standard
■ Equivalent to ISO-C standard but works in a nonstandard way
M Fully compatible with ISO-C standards but supported for memory files only.
FUNCTION NAME
FUNCTION DESCRIPTION
C
ALCS
TPF
va_start
Allows access to variable number of function
arguments
√
√
√
vfprintf
Formats and prints characters to the output stream
using a variable number of arguments
√
M
vprintf
Formats and prints characters to stdout using a
variable number of arguments
√
√
vsprintf
Formats and stores characters in a buffer using a
variable number of arguments
√
√
√
waitc
Waits for all outstanding I/O requests to complete
X
X
wcscat
Concatenates wchar_t strings
√
√
wcschr
Searches wchar_t strings for character
√
√
wcscmp
Compares wchar_t strings
√
√
wcscpy
Copies wchar_t string
√
√
wcscspn
Searches wchar_t string for characters
√
√
wcslen
Reads length of wchar_t string
√
√
wcsncat
Concatenates wchar_t string segment
√
√
wcsncmp
Compares wchar_t string segments
√
√
wcsncpy
Copies wchar_t segments
√
√
wcspbrk
Locates wchar_t characters in a string
√
√
wcsrchr
Locates a wchar_t character in a string
√
√
wcsspn
Finds number of wchar_t characters
√
√
wcstombs
Converts wchar_t characters to multibyte string
√
√
wcswcs
Locates a wchar_t string in another wchar_t string
√
√
wctomb
Converts wchar_t characters to multibyte characters
√
√
wgtac
Locates terminal entry
wtopc
Sends a message to a terminal
X
X
wtopc_insert_header
Saves a header for wtopc
X.
X
wtopc_routing_list
Saves a routing list for wtopc
X
X
wtopc_text
Sends a message to a terminal
X
X
√
ISO-C
√
ISO-C
X
Chapter 16. C library functions available under ISO-C, ALCS, and TPF
421
Callable services
Chapter 17. Customizing ALCS
This chapter describes the installation-wide monitor exits that are supplied with ALCS and how to use
them to customize ALCS in your installation.
Note: This chapter contains Product-Sensitive Programming and Associated Guidance Information.
When you use the ALCS installation-wide monitor exits and the ALCS callable services you must ensure
that all addresses and labels are valid. ALCS assumes that your customization code is written and fully
tested before it is used.
17.1 ALCS services for installation-wide monitor exits
ALCS provides macros and callable services to implement commonly required functions (get an ECB, get
an IOCB, and so on). You must use these macros and callable services in the installation-wide monitor
exits, because the ALCS monitor services are not directly available to installation-wide monitor exits.
17.1.1 Macros you can call in installation-wide monitor exits
The available macros are:
COMCC Update communication resource information.
CPDMP Take a control system error dump.
| DECBC DECB management
DXCPKEY Change PSW key.
DXCSAVE Save area management macro.
GLOBZ Access a global area.
TIMEC
Get the ALCS time and date.
WTOPC Send a message.
Update communication resource entry – COMCC
ALCS Application Programming Reference – Assembler describes this macro.
You can use this macro with some restrictions. You can use the following for fields or bits:
5
5
5
5
5
5
5
RECOARN
REC1AAA
REC1CST
REC1LOG
RETDACK
RETDARC
RETDSDD
Restriction
The FIELD= parameter is not supported in register notation.
422
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Callable services
Take system error dump – CPDMP
Use the CPDMP macro to take a system error dump. See “Problem determination in ALCS” in ALCS
Operation and Maintenance for information about system error dumps.
Format
[label] CPDMP error_code
[,EXIT=NO]
[,ECB={YES|NO}]
[,MSG={NO|YES|'text'}]
[,DUMP={SEL|ALL|NO}]
Where:
label
Any valid Assembler label.
error_code
A unique six hexadecimal-digit code that indicates which condition caused the dump to be taken.
Specify a code in the range X'000000' through X'000FFF'.
See “System error codes” 000000 through 000FFF in ALCS Messages and Codes for a list of system
error codes that ALCS uses.
EXIT=NO
The action to take following the dump.
NO
Return control to the next sequential instruction after the CPDMP macroinstruction.
ECB={YES|NO}
YES
The system error dump is associated with a particular active entry.
NO
The system error dump is not associated with a particular active entry.
ECB=YES is allowed only for the following installation-wide monitor exits:
5
5
5
5
5
5
5
USRCOM2
USRCOM4
USRMQI1
USRSQL1
USRSQL2
USRSVC
USRTCP1
MSG={NO|YES|'text'}
Indicates whether the online monitor appends an optional user message to the standard message that
it generates when it takes the system error dump.
NO
No message is appended.
YES
General register 0 (RAC) contains the address of a field that contains the message with the
following format:
Byte 0
Contains the length of the field (in binary).
Chapter 17. Customizing ALCS
423
Callable services
Successive bytes Contain the text of the message. The message text must not contain
control characters such as new line (#CAR).
text
Message text.
DUMP={SEL|ALL|NO}
SEL
Include only blocks attached to the active entry, if there is one.
ALL
Include all storage blocks in the system error dump.
NO
Generate the system error dump message but do not include any dump data.
Loss of Control
If there is an active entry, this macro does not cause it to lose control.
Register Usage
If you specify MSG=YES, no registers are used. If you specify MSG=text, ALCS uses general register 0 (RAC)
and does not restore it.
Usage Notes
Use CPDMP when an error condition is detected. CPDMP expands to give an operation exception that the
online monitor recognizes as a CPDMP request.
Use the diagnostic file processor offline program (DXCDTP) to format and print the system error dump
(see “Running the ALCS diagnostic file processor” in ALCS Operation and Maintenance).
Note: Some installation-wide monitor exits do not tolerate CPDMP. Do not include CPDMP in the following
exits:
5
5
5
5
5
5
5
|
USRAPPC
USRCOM6
USRCOM7
USRDMP
USRPCH
USRTCP2
USRTCP4
DECB management – DECBC
| Use this macro as described in ALCS Application Programming Reference – Assembler, with the following
| restriction.
| Restriction
| ALCS uses general registers 1 and 2 (RG1 and RGA) and does not restore them.
Change PSW key – DXCPKEY
Format
424
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Callable services
[label] DXCPKEY PSW,SET,KEY={TABLES|ENTRY|GLOBAL1}
Where:
KEY=TABLES|ENTRY
Key to be moved to the PSW. Valid keys are:
TABLES
To update monitor controlled data fields.
ENTRY
To update storage units which hold the ECBs and associated blocks.
GLOBAL1
To update global areas 1 or 3.
Description
Use the DXCPKEY macro to change the Program Status Word (PSW) key.
ALCS save area management macro – DXCSAVE
Restriction
You must use the forms of DXCSAVE in the sample installation-wide monitor exits. Do not use any other
form of this macro.
Format
[label] DXCSAVE PUSH
,ID={USER|UPCH|UDMP|USR1|USR2}
,SIZE=512,WORKREG=R02
Stacks the save area and registers of the calling routine in ALCS.
[label] DXCSAVE POP,RESTORE,EXCEPT=((R15))
Restores the save area and registers (except R15) of the calling routine in ALCS.
[label] DXCSAVE SRBSAVE,ID=USER,SIZE=512,WORKREG=R06
Stacks the save area and registers of the calling routine in ALCS.
[label] DXCSAVE FREESRB,RESTORE,EXCEPT=((R15))
Restores the save area and registers (except R15) of the calling routine in ALCS.
Chapter 17. Customizing ALCS
425
Callable services
Where:
ID=USER
Most installation-wide monitor exits use this form of DXCSAVE.
ID=UPCH
USRPCH uses this form of DXCSAVE.
ID=UDMP
USRDMP uses this form of DXCSAVE.
ID=USR1
USRRTN1 uses this form of DXCSAVE.
ID=USR2
USRRTN2 uses this form of DXCSAVE.
The following installation-wide monitor exits do not use the DXCSAVE macro:
5 USRCOM5
5 USRTAB1 through USRTAB6
5 USRFAR
The following installation-wide monitor exits use the SRBSAVE and FREESRB parameters:
5 USRCOM6
5 USRCOM7
Access a global area – GLOBZ
Use this macro as described in ALCS Application Programming Reference – Assembler.
Get the ALCS time and date – TIMEC
Use this macro as described in ALCS Application Programming Reference – Assembler, with the following
restriction.
Restriction
The AREA= parameter is mandatory and must point to a field of the appropriate size in tables key.
Write to operator – WTOPC
Use this macro as described in ALCS Application Programming Reference – Assembler, with the following
restriction.
Restriction
In execute form, the plist label is mandatory.
17.1.2 Entry conditions for callable services
All callable services are invoked as follows:
DXCSERV Uservice_name,PARM=({(Rnn)|label|0},...)
Where
426
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Callable services
Uservice_name
One of:
|
|
|
|
|
UCNTINC
UCOMCHG
UCOMGET
UDLEVGET
UDLEVREL
UDLEVVAL
UDISP
UECBGET
UECBQUE
UECBREL
UECBVAL
UIOBGET
UIOBQUE
UIOBREL
ULEVGET
ULEVREL
ULEVVAL
UPROGF
URTN1
URTN2
USTRGET
USTRREL
USTRVAL
UTAB1
:
UTAB6
UTAB7
:
UTAB10
UWSEQ
Increment system counter.
Change a CRN in a communication table item.
Obtain a communication table item address.
Obtain a storage block and attach it to a DECB.
Release a storage block attached to a DECB.
Validate a DECB storage level.
Branch to dispatcher.
Obtain an ECB.
Queue an ECB.
Release an ECB.
Validate an ECB address.
Obtain an IOCB.
Queue an IOCB.
Release an IOCB.
Obtain a storage block and attach it to an ECB.
Release a storage block attached to an ECB.
Validate an ECB storage level.
Find program address
Call USRRTN1.
Call USRRTN2.
Obtain MVS virtual storage.
Release MVS virtual storage.
Validate an MVS virtual storage address.
Find a translate table
Find a translate table
Find a translate table for ASCIC
Find a translate table for ASCIC
Write to a system-sequential file.
PARM=
One or more parameters to pass between the callable service and the user code. The parameters
include the passed and returned parameters. Each parameter occupies a fullword. Specify 0 to
initialize each unused parameter.
Attention
You must specify all passed and returned parameters required by a callable service, otherwise the call
may fail unpredictably. The format is a standard MVS CALL parameter list.
Figure 165 on page 428 gives an overview of the calling process for a service with two input parameters
and three output parameters.
Chapter 17. Customizing ALCS
427
Callable services
Installation-wide
monitor exit
┌─────────────┐
┌;┌───────────────┐
│
│
│ │ User code
│
│
│
├ ─ ─ ─ ─ ─ ─ ─ ┤K────────────────────────┐
│
│
│ │
│
│
│
ALCS
│
└────────┬──────┘
│
│
│
│
│
│
│ CALL
│
│
├ ─ ─ ─ ─ ─ ─ ┤── ─ ─ ─ ─┘
│
├ ─ ─ ─ ─ ─ ─ ┤K─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
│
│
│
R1┌──────────┐
Passed parameters
│
│
│
└─────┬────┘
ip1 ip2
│
│
│
└──────;┌───┐┌───┐┌───┐┌───┐┌───┐ │
│
│
└┴┴┴┘└┴┴┴┘└───┘└───┘└───┘ │
│
│
K─ ─ ─ ─ ─ ─ ─ ─ ──
│
├─────────────┤K─────────────────────────────────────────────────────┘
│ Callable
│
─ ─ ─ ─ ─ ─ ─ ─ ─ ;
│ service
│
R1┌──────────┐
├─────────────┤
└─────┬────┘
x
x Returned parameters
└──────;┌───┐┌───┐┌───┐┌───┐┌───┐
├─────────────┤
R15┌──────────┐ └───┘└───┘└┴┴┴┘└┴┴┴┘└┴┴┴┘
│
│
└──────────┘ Return code
│
│
└─────────────┘
Figure 165. Callable service linkage conventions
The callable services use the standard MVS CALL macro as follows:
5 R14 for the return address
5 R15 for the return code
5 R01 to point to the start of the parameter list
5 R00 can be corrupted
Notes:
1. The output parameters are offset by one fullword for each input parameter.
2. Unless specifically mentioned, all callable services are entered (and return) in tables storage key.
Register usage on return from the callable service
R00
R01
R14
R15
Can be overwritten by the MVS CALL macro.
Points to the start of the parameter list.
The return address to the user code.
Return code from the service, it is set to:
0
Successful completion
<>0 Unsuccessful completion.
All other registers are the same as on entry to the callable service.
17.1.3 Increment system counter — UCNTINC
param_1
The address of a 1-byte indicator field. Use one of the following bit symbols to indicate which type of
information is passed to UCNTINC:
IW0IMSG The number of input messages.
IW0OMSG The number of output messages.
UCNTINC returns with the following conditions:
R15=0
428
The count is incremented.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Callable services
This UCNTINC call increments the number of received
input messages
Label CNTIND is defined as DC 'X'' in the user
monitor save area
MVI
CNTIND,IWIMSG
SET INPUT MESSAGE RECEIVED
SPACE 1
DXCSERV UCNTINC,PARM=(CNTIND)
SPACE 1
Figure 166. Example: UCNTINC incrementing the system counter
17.1.4 Change a CRN in a communication table entry — UCOMCHG
param_1
The address of the communication table entry for the resource to change.
param_2
The address of an 8-byte field containing either:
5 The CRN to remove from the communication table entry
5 Zero, if there is nothing to remove
param_3
The address of an 8-byte field containing either:
5 The CRN to add to the communication table entry
5 Zero, if there is nothing to add
UCOMCHG returns with the following conditions:
R15=0
R15=4
R15=8
R15=12
R15=16
R15=20
R15=24
The change is successful.
The CRN cannot be added because it already exists.
The CRN cannot be removed because it does not exist.
The CRN cannot be added because an ALCS table is full. Or, the CRN cannot be removed
because it does not match the resource that param_1 specifies.
The resource cannot be changed because it is active or logon is in progress.
The CRN cannot be removed because it does not match any existing resource. Or, param_1
is omitted.
Unable to obtain lock for communication table entry.
This UCOMCHG changes a CRN in the communication
tables.
The old CRN is taken from the communication table
item while the new CRN is taken from an 8 bytes field
which is addressed by register R2.
The communication table address is in register R6.
SPACE 1
CORE REG=R6
COMMUNICATION TABLE ITEM DSECT
DXCSERV UCOMCHG,PARM=((R6),RECOCRN,(R2))
LTR
R15,R15
HAS THE CHANGE TAKEN PLACE
BNZ
ERROR
NO - BRANCH
SPACE 1
DROP R6
DROP COMMUNICATION TABLE BASE
Figure 167. Example usage of UCOMCHG
17.1.5 Obtain a communication table entry address — UCOMGET
param_1
Specify zero.
Chapter 17. Customizing ALCS
429
Callable services
param_2
The address of a 1-byte indicator field. Use one of the following bit symbols to indicate which type of
information is passed to UCOMGET:
IW0CRI
The CRI is supplied.
IW0CRN
The CRN is supplied.
IW0NEXT Point to the communication table entry for the next resource (after the specified CRI).
IW0LEID
The LEID is supplied.
IW0UDATA Return the address of the user part of the communication table entry.
param_3
The address of an input area for the function:
5 3-byte CRI for the CRI or next function
5 8-byte CRN for the CRN function
5 3-byte LEID for the LEID function
param_4
Specify zero if IW0UDATA is included in param_2.
V
V
V
V
V
V
This UCOMGET obtains the communication table address
of a device using the CRI as a search argument.
Label COMIND is defined as DC X'' in the user monitor
save area.
ECB label EBROUT holds a 3 byte CRI.
Label PARM1 is equated to (R1).
MVI
COMIND,IWCRI
SET CRI AVAILABLE FOR SEARCH
SPACE 1
DXCSERV UCOMGET,PARM=(,COMIND,EBROUT)
SPACE 1
LTR
R15,R15
IS THIS DEVICE KNOWN TO ALCS
BNZ
ERROR
NO - BRANCH ERROR
SPACE 1
L
R14,PARM1
LOAD COMMS TABLE ADDRESS
Figure 168. Example: UCOMGET using a CRI
V
V
V
V
V
V
V
V
V
This UCOMGET obtains the communication table address
of a device using the CRN as a search argument.
It also obtains the address of the start of the user
part of the communication table for this device.
Label COMIND is defined as DC X'' in the user monitor
save area.
Label LUNAME holds an 8 byte CRN padded to the right with
blanks.
Label PARM1 is equated to (R1).
MVI
COMIND,IWCRN+IWUDATA SET CRN AVAILABLE FOR SEARCH
SPACE 1
DXCSERV UCOMGET,PARM=(,COMIND,LUNAME,)
SPACE 1
LTR
R15,R15
IS THIS DEVICE KNOWN TO ALCS
BNZ
ERROR
NO - BRANCH ERROR
SPACE 1
L
R14,PARM1
LOAD COMMS TABLE ADDRESS
L
R15,PARM4
LOAD ADDRESS OF USER AREA
Figure 169. Example: UCOMGET using a CRN
430
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Callable services
V
V
V
V
V
V
This UCOMGET obtains the communication table address
of a device using the LEID as a search argument.
Label COMIND is defined as DC X'' in the user
monitor save area.
Label CM5MLD holds a 3-byte LEID as part of an input message.
Label PARM1 is equated to (R1).
MVI
COMIND,IWLEID
SET LEID AVAILABLE FOR SEARCH
SPACE 1
DXCSERV UCOMGET,PARM=(,COMIND,CM5MLD)
SPACE 1
LTR
R15,R15
IS THIS DEVICE KNOWN TO ALCS
BNZ
ERROR
NO - BRANCH ERROR
SPACE 1
L
R14,PARM1
LOAD COMMS TABLE ADDRESS
Figure 170. Example: UCOMGET using an LEID
UCOMGET returns with the following conditions:
R15=0
The communication table entry exists.
param_1 The address of the communication table entry.
param_4 The address of the start of the user part of the communication table entry, if
IW0UDATA is included in param_2.
R15=4
The communication table entry does not exist.
R15=8
Internal error detected.
SLC-ID option
The SLC ID option uses the following parameters (param_3 through param_7):
param_1
Specify zero.
param_2
The address of a 1-byte indicator field. Use one of the following bit symbols to indicate which type of
information is passed to UCOMGET:
IW0SLCID The SLCID is supplied.
IW0UDATA Return the address of the user part of the communication table entry.
param_3
The address of the 3-byte CRI of the SLC link.
param_4
The address of the 2-byte HEX of the remote terminal.
param_5
The address of the 1-byte TCID of the remote terminal.
param_6
The address of the 1-byte IA of the remote terminal.
param_7
The address of the 1-byte TA of the remote terminal.
param_8
Specify zero if IW0UDATA is included in param_2.
Chapter 17. Customizing ALCS
431
Callable services
V
V
V
V
V
V
V
V
V
V
V
This UCOMGET obtains the communication table address
of an SLC terminal.
Label COMIND is defined as DC X'' in the user monitor
save area.
Label LK4CRI holds a 3-byte CRI of the SLC link on which
this terminal is defined.
Label CM8HEN holds the 2-byte HEX of the terminal.
Label CM8TXH holds the 1-byte TCID of the terminal.
Label CM8TXH+1 holds the 1-byte IA of the terminal in line code.
Label CM8TXH+2 holds the 1-byte TA of the terminal in line code.
Label PARM1 is equated to (R1).
MVI
COMIND,IWSLCID
SET SLCID AVAILABLE FOR SEARCH
SPACE 1
DXCSERV UCOMGET,
PARM=(,COMIND,LK4CRI,CM8HEN,CM8TXH,CM8TXH+1,CM8TXH+2)
SPACE 1
LTR
R15,R15
IS THIS DEVICE KNOWN TO ALCS
BNZ
ERROR
NO - BRANCH ERROR
SPACE 1
L
R14,PARM1
LOAD COMMS TABLE ADDRESS
Figure 171. Example: UCOMGET for an SLC terminal
UCOMGET with the SLC-ID option returns with the following conditions:
R15=0
The communication table entry exists.
param_1 The address of the communication table entry.
param_8 The address of the start of the user part of the communication table entry, if
IW0UDATA is included in param_2.
R15=4
R15=8
|
The communication table entry does not exist.
Internal error detected.
17.1.6 Obtain a storage block and attach it to a DECB — UDLEVGET
| param_1
|
The address of the ECB.
| param_2
|
The address of the DECB.
| param_3
|
The address of a 2-byte field containing the block size code. Use the same conventions as the GETCC
|
monitor-request macro.
| See ALCS Application Programming Reference – Assembler for a description of the GETCC monitor-request
| macro.
| UDLEVGET returns with the following conditions:
| R15=0
| R15=4
432
A block is obtained.
A block is not obtained.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Callable services
|
|
|
|
|
|
|
|
|
V
V
V
V
This UDLEVGET obtains a storage block of size L2 attached to the DECB
R9 - has the ECB address
R14 - has the DECB address
Label SIZE is defined as DC AL2(L2) in the program
DXCSERV UDLEVGET,PARM=((R9),(R14),SIZE)
SPACE 1
LTR
R15,R15
DID WE GET THE BLOCK
BNZ
ERROR
NO - BRANCH
SPACE 1
| Figure 172. Example: UDLEVGET
|
17.1.7 Release a storage block attached to a DECB — UDLEVREL
| param_1
|
The address of the ECB.
| param_2
|
The address of the DECB.
| UDLEVREL returns with the following conditions:
| R15=0
|
|
|
|
|
|
V
V
V
V
The block is released.
This UDLEVREL releases the storage block attached to the DECB
R9 - has the ECB address
R14 - has the DECB address
DXCSERV UDLEVREL,PARM=((R9),(R14))
SPACE 1
NO NEED TO CHECK RETURN CODE
| Figure 173. Example: UDLEVREL
|
17.1.8 Validate a DECB storage level — UDLEVVAL
| param_1
|
The address of the ECB.
| param_2
|
The address of the DECB.
| UDLEVVAL returns with the following conditions:
| R15=0
| R15=4
| R15=8
| V
| V
| V
|
|
|
|
|
|
|
The storage level is valid and in use.
The storage level is not in use.
The storage level is corrupted.
This UDLEVVAL validates the block attached to the DECB
R9 - has the ECB address
R14 - has the DECB address
DXCSERV UDLEVVAL,PARM=((R9),(R14))
SPACE 1
B
V+4(R15)
CHECK THE RETURN CODE
B
USEIT
- LEVEL IN USE AND OK
B
EMPTY
4 - LEVEL NOT IN USE
B
ERROR
8 - LEVEL CORRUPTED
SPACE 1
| Figure 174. Example: UDLEVVAL
Chapter 17. Customizing ALCS
433
Callable services
17.1.9 Branch to dispatcher — UDISP
This service branches to the ALCS dispatcher (CPU loop) and does not return.
Note: You must use this service only in post-interrupt routines which are queued with UIOBQUE or
UECBQUE.
DXCSERV UDISP
SPACE 1
BRANCH TO CPU LOOP
Figure 175. Example: UDISP
434
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
000000 9 000005
Chapter 18. System error codes: 000000–000FFF
000000
ZDUMP message
000003
Module: DXCCOMP, DXCOMR, DXCCOMT
Module: Any ECB-controlled program.
Explanation: A manual dump was
requested by entering the ZDUMP
command. The message is a copy of the
data entered with the ZDUMP command.
Explanation: There was a program
exception while an ALCS application
program was executing.
System Action: ALCS terminates the
entry.
System Action: ALCS continues
processing normally.
000001
Problem Determination: ALCS
diagnostic file processor prints the type of
program interruption in the system error
dump header.
PROGRAM EXCEPTION IN ONLINE
MONITOR
Module: Any ALCS online monitor
module.
Explanation: There was a program
exception while the ALCS online monitor
was executing.
000004
Explanation: An ALCS online monitor
routine requested a system error dump.
The system error routines could not return
control to the routine that requested the
system error dump.
Operator Response: If ALCS goes
catastrophic then activate the alternate
ALCS if there is one, or restart ALCS. If
this is an isolated instance, follow your
normal procedure for a non-urgent
problem. If it happens repeatedly, inform
your system programmer.
System Programmer Response: If an
application program did not cause the
system error then inform your IBM
programming support representative.
NO BASE REGISTER FOR ERROR
RETURN
Module: DXCPCH
System Action: If there is an active
entry, then ALCS terminates it and
continues. If there is no active entry, then
ALCS ends abnormally.
Problem Determination: ALCS
diagnostic file processor prints the type of
program interruption in the system error
dump header. If there is an active entry
then it is possible that an application
programming error caused the system
error. The system error dump contains
information about the active entry (for
example, the ECB). Use this information
to check, for example, if an ECB-controlled
program issued a monitor-request macro
with incorrect register contents.
PROGRAM EXCEPTION IN
APPLICATION PGM program_name
System Action: ALCS ends abnormally.
Operator Response: Activate the
alternate ALCS if there is one, or restart
ALCS. If this is an isolated instance,
follow your normal procedure for a
non-urgent problem. If it happens
repeatedly, inform your system
programmer.
System Programmer Response: If this
error occurs, inform your IBM
programming support representative.
000005
INVALID MONITOR REQUEST CODE
Module: DXCNUC
Explanation: An ECB-controlled program
issued a monitor-request macro linkage
instruction, BRANCH AND SAVE AND
SET MODE (BASSM), but the 2 bytes
following the BASSM did not contain a valid
monitor request code.
System Action: ALCS terminates the
entry.
User Response: Check if the application
program issued a monitor-request macro
for a user-written monitor service. If so,
check that the installation-wide exit routine
correctly implements the service.
Chapter 18. System error codes: 000000–000FFF
435
000006 9 00000D
000006
|
|
|
00000A
STORAGE LEVEL ALREADY IN USE
Module: DXCSTM, DXCHLD
Module: DXCNUC
Explanation: An ECB-controlled program
issued a GETCC or implied get storage
monitor-request macro with a storage
block already attached at the ECB or
DECB storage level.
Explanation: The ALCS online monitor
detected that the ECB I/O counter for an
entry was invalid.
System Action: ALCS ends abnormally.
Operator Response: Activate the
alternate ALCS if there is one, or restart
ALCS. If this is an isolated instance,
follow your normal procedure for a
non-urgent problem. If it happens
repeatedly, inform your system
programmer.
System Action: ALCS terminates the
entry.
Application Programmer Response:
Correct the programming error.
000007
STORAGE LEVEL NOT IN USE
Module: DXCSTM
System Programmer Response: If this
error occurs, inform your IBM
programming support representative.
Explanation: An ECB-controlled program
issued a RELCC or implied release storage
monitor-request macro with no block
attached at the ECB or DECB storage
level.
|
|
|
System Action: ALCS terminates the
entry.
Application Programmer Response:
Correct the programming error.
000008
RECORD(S) HELD AT EXIT
00000B
|
|
|
|
|
|
Explanation: An ECB-controlled program
issued a monitor-request macro that
specified an ECB or DECB storage level
or data level The level reference was
invalid. Valid ECB level references are D0
(value 0), D1 (value 8), and so on up to
DF (value decimal 120).
System Action: ALCS terminates the
entry.
Explanation: An ECB-controlled program
issued an EXITC monitor-request macro
with one or more records held.
System Action: ALCS unholds the
records before it terminates the entry.
Application Programmer Response:
Correct the programming error.
00000C
Application Programmer Response:
Correct the programming error.
Explanation: An ECB-controlled program
issued a monitor-request macro, but the
ECB base register, general register 9
(REB), did not contain the ECB address.
Module: DXCSTM
System Action: ALCS terminates the
entry.
Application Programmer Response:
Correct the programming error.
CORRUPTED ECB ADDRESS
Module: DXCNUC
RELEASE STORAGE ERROR – SU
STORAGE CONTROL CORRUPTED
Explanation: During release storage
processing ALCS detected corruption of
fields it uses to manage storage for the
entry. This is most likely caused by the
application working through data and
stepping outside a storage block. General
register 14 points to the area where
corruption was observed.
INVALID LEVEL REFERENCE
Module: DXCSTM, DXCVFM
Module: DXCVFA
000009
INVALID ECB I/O COUNT
System Action: ALCS terminates the
entry.
Application Programmer Response:
Correct the programming error.
00000D
INVALID RELEASE STORAGE BLOCK
variable
Module: DXCSTM
Explanation: An ECB-controlled program
issued a RELCC or implied release storage
monitor-request macro, but the block
address or type was invalid. Variable is
either ADDRESS or TYPE.
System Action: ALCS terminates the
entry.
436
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
00000E 9 0001C5
00000E
Application Programmer Response:
Correct the programming error.
| 0001C2
DECBC – I/O IN PROGRESS
|
Module: DXCSTG
FLIPC – INVALID LEVEL REFERENCE
|
|
|
Explanation: An ECB-controlled program
issued a DECBC macro that specified a DECB
for which I/O was in progress.
|
|
System Action: ALCS terminates the
entry.
|
|
Application Programmer Response:
Correct the programming error.
| 0001C3
DECBC – BLOCK ATTACHED
|
Module: DXCSTG
|
|
|
|
Explanation: An ECB-controlled program
issued a DECBC FUNC=RELEASE that
specified a DECB with a storage block
attached.
|
|
System Action: ALCS terminates the
entry.
|
|
Application Programmer Response:
Correct the programming error.
| 0001C4
DECBC – DECB NAME NOT KNOWN
|
Module: DXCSTG
|
|
|
|
|
Explanation: An ECB-controlled program
issued a DECBC FUNC=RELEASE and
specified the NAME parameter. However
the DECB name specified did not reference
a known DECB
|
|
System Action: ALCS terminates the
entry.
|
|
Application Programmer Response:
Correct the programming error.
Module: DXCSTG
Explanation: An ECB-controlled program
issued a FLIPC monitor-request macro.
One or both of the level references was
invalid. Valid level references are D0
(value 0), D1 (value 8), and so on up to
DF (value decimal 120).
System Action: ALCS terminates the
entry.
Application Programmer Response:
Correct the programming error.
00000F
ENTRY LIFE LIMIT EXCEEDED
Module: DXCTIR
Explanation: The entry exceeded its
maximum entry life. The ALCS generation
specifies two entry life limits; the entry can
use the SLIMC monitor-request macro to
reset one, but the other is fixed. This
error occurs if the entry exceeds either
limit.
System Action: ALCS terminates the
entry.
Application Programmer Response: If
the entry exceeded the limit that SLIMC can
reset, and if the entry genuinely needs to
execute for a very long time, then include
a SLIMC monitor-request macro in the
application to increase the entry life limit
for this type of entry.
| 0001C1
DECBC – INVALID DECB REFERENCE
| 0001C5
DECBC – INVALID FUNCTION CODE
|
Module: DXCSTG
|
Module: DXCSTG
|
|
|
|
|
Explanation: An ECB-controlled program
issued a monitor-request macro that
specified a DECB address. The DECB
address did not reference a valid DECB or
referenced one that had been released.
|
|
|
|
Explanation: An ECB-controlled program
issued a DECBC macro but the function type
specified in the monitor-request macro
instructions was not valid.
|
|
System Action: ALCS terminates the
entry.
|
|
System Action: ALCS terminates the
entry.
|
|
Application Programmer Response:
Correct the programming error.
|
|
|
System Programmer Response: This
should not occur. If it does, contact your
IBM programming service representative.
Chapter 18. System error codes: 000000–000FFF
437
0001C6
| 0001C6
DECBC – INVALID LEVEL REFERENCE
|
Module: DXCSTG
|
|
|
|
|
|
Explanation: An ECB-controlled program
issued a DECBC FUNC=SWAPBLK that
specified a data level that was invalid.
Valid ECB level references are D0 (value
0), D1 (value 8), and so on up to DF
(value decimal 120).
438
|
|
System Action: ALCS terminates the
entry.
|
|
Application Programmer Response:
Correct the programming error.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
DXC8267E
Chapter 19. Responses to ALCS commands:
DXC8000–DXC8999
| DXC8267E Invalid DECB address
|
|
|
Explanation: This message is an error
response to ALCS conversation trace
commands which refer to DECBs.
|
System Action: Processing continues.
Chapter 19. Responses to ALCS commands: DXC8000–DXC8999
439
Appendix A. Acronyms and abbreviations
The following acronyms and abbreviations are used in books of the ALCS Version 2 library. Not all are
necessarily present in this book.
AAA
ACB
ACF
ACF/NCP
ACF/VTAM*
ACK
ACP
AID
AIX
ALC
ALCI
ALCS/MVS/XA
ALCS/VSE
ALCS V2
AML
AMS
AMSG
APAR
APF
API
APPC
ARINC**
ASCU
AT&T**
ATA
ATSN
BATAP
BSC
C
CAF
CCW
CDPI
CEC
CI
CICS/VS*
CLIST
CMC
CML
CPI-C
CPU
CRAS
CRI
CRN
CSA
CSECT
CSID
440
agent assembly area
VTAM access method control block
Advanced Communications Function
Advanced Communications Function for the Network Control Program, usually referred
to simply as “NCP”
Advanced Communications Function for the Virtual Telecommunication Access Method,
usually referred to simply as “VTAM”
positive acknowledgment (SLC LCB)
Airline Control Program
IBM 3270 attention identifier
add item index
airlines line control
Airlines Line Control Interconnection
Airline Control System/MVS/XA
Airline Control System/Virtual Storage Extended
Airline Control System Version 2
acknowledge message label (SLC LCB)
access method services
AMSG application message format
authorized program analysis report
authorized program facility
application program interface
advanced program-to-program communications
Aeronautical Radio Incorporated
agent set control unit (SITA), a synonym for “terminal control unit”
American Telephone and Telegraph Co.
Air Transport Association of America
acknowledge transmission sequence number (SLC)
Type B application-to-application program
binary synchronous communication
C programming language
DB2 Call Attach Facility
channel command word
clearly differentiated programming interface
central electronic complex
VSAM control interval
Customer Information Control System/VS
command list
communication management configuration
clear message label (synonym for AML)
Common Programming Interface – Communications
central processing unit
computer room agent set
communication resource identifier
communication resource name
common service area
control section
cross system identifier
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
|
CSW
CTKB
CTL
DASD
DBCS
DBRM
DB2*
DCB
DECB
DF
DFDSS
DFHSM
DFP
DFSMS*
DFT
DIX
DRIL
DSI
DSECT
DTP
EBCDIC
ECB
EIB
EID
ENQ
EOF
EOM
EOI
EOP
EOU
EP
EP/VS
EVCB
FACE
FIFO
FI
FM
FMH
GDS
GFS
GMT
GTF
GUPI
HEN
HEX
HLL
HLN
HLS
IA
IASC
IATA
IATA5
IATA7
ICF
channel status word
Keypoint record B
control system error
direct access storage device
double-byte character set
DB2 database request module
IBM DATABASE 2*
data set control block
data event control block
delayed file record
Data Facility Data Set Services
Data Facility Hierarchical Storage Manager
Data Facility Product
Data Facility Storage Management Subsystem
distributed function terminal
delete item index
data record information library
direct subsystem interface
dummy control section
ALCS diagnostic file processor
extended binary-coded decimal interchange code
ALCS entry control block
error index byte
event identifier
enquiry (SLC LCB)
end of file
end of message
end of message incomplete
end of message pushbutton
end of message unsolicited
Emulation Program
Emulation Program/VS
MVS event control block
file address compute
first-in-first-out
file immediate record
function management
function management header
general data set
get file storage (called pool file storage in ALCS)
Greenwich Mean Time
generalized trace facility (MVS)
general-use programming interface
high-level network entry address
high-level network exit address
high-level language
high-level network
high-level system (for example, SITA)
interchange address
International Air Transport Solution Centre
International Air Transport Association
ATA/IATA transmission code 5
ATA/IATA transmission code 7
integrated catalog facility
Appendix A. Acronyms and abbreviations
441
ID
ILB
IMA
IMS
IMSG
I/O
IOCB
IP
IPARS
IPCS
IPL
ISA
ISC
ISO/ANSI
ISPF
ISPF/PDF
ITA2
JCL
JES
KB
KCN
KSDS
LAN
LCB
LDB
LDI
LEID
LE
LICRA
LMT
LN
LN/ARID
LSI
LU
MATIP
MB
MBI
MCHR
MESW
MNOTE
MQI
MQM
MSNF
MVS
MVS/DFP*
MVS/ESA*
MVS/XA*
NAB
NAK
NCB
NCP
NEF
NEF2
NPDA
442
identifier
idle (SLC LCB)
BATAP acknowledgement
Information Management System
IMSG input message format
input/output
I/O control block
Internet Protocol
International Programmed Airlines Reservation System
Interactive Problem Control System
initial program load
initial storage allocation
intersystem communication
International Standards Organization/American National Standards Institute
Interactive System Productivity Facility
Interactive System Productivity Facility/Program Development Facility
International Telegraph Alphabet number 2
job control language
job entry subsystem
kilobyte (1024 bytes)
link channel number (SLC)
VSAM key-sequenced data set
local area network
link control block (SLC)
link data block (SLC)
local DXCREI index
logical end-point identifier
Language Environment*
Link Control – Airline
long message transmitter
line number (ALCS/VSE and TPF terminology)
line number and adjusted resource identifier (ALCS/VSE terminology)
link status identifier (SLC)
logical unit
Mapping of airline traffic over IP
megabyte (1 048 576 bytes)
message block indicator (SLC)
module/cylinder/head/record
message switching
message note
Message Queueing Interface
Message Queue Manager
Multisystem Networking Facility
Multiple Virtual Storage (refers to both MVS/XA and MVS/ESA)
Multiple Virtual Storage/Data Facility Product
Multiple Virtual Storage/Enterprise System Architecture
Multiple Virtual Storage/Extended Architecture
next available byte
negative acknowledgment (SLC LCB)
network control block (SLC)
Network Control Program (refers to ACF/NCP)
Network Extension Facility
Network Extension Facility 2
Network Problem Determination Application
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
NPSI
NTO
OCR
OMSG
OPR
OSID
OS/2*
PARS
PDF
PDM
PDS
PDSE
PDU
PER
PFDR
PL/I
PLM
PLU
PNL
PNR
PP
PPI
PPMSG
PPT
PR
PRC
PRDT
PRPQ
PR/SM*
PS
PSPI
PSW
PTF
PTT
PU
PVC
QSAM
RACF*
RB
RBA
RCC
RCPL
RCR
RCS
REI
RLT
RMF*
RO CRAS
RON
RPL
RPQ
RSM
RTM
RU
Network Control Program packet switching interface
Network Terminal Option
one component report
OMSG output message format
operational system error
other-system identification
IBM Operating System/2*
Programmed Airlines Reservation System
parallel data field (refers to NCP)
possible duplicate message
partitioned data set
partitioned data set extended
pool directory update
program event recording
pool file directory record
programming language one
purge long message (name of ALCS/VSE and TPF general tape)
primary logical unit
passenger name list
passenger name record
IBM program product
program-to-program interface
program-to-program message format
program properties table
permanently resident record
prime computer room agent set
physical record (block) descriptor table
programming request for price quotation
Processor Resource/Systems Manager*
VTAM presentation services
product sensitive programming interface
program status word
program temporary fix
Post Telephone and Telegraph Administration
physical unit
permanent virtual circuit
queued sequential access method
resource access control facility*
request block
relative byte address
record code check
routing control parameter list
resource control record
regional control center
resource entry index
record locator table
Resource Measurement Facility*
receive-only computer room agent set
record ordinal number
VTAM request parameter list
request for price quotation
resume (SLC LCB)
recovery and termination management
request unit
Appendix A. Acronyms and abbreviations
443
SAA*
SAF
SAL
SAM
SDLC
SDMF
SDSF
SDWA
SI
SITA**
SLC
SLIP
SLN
SLR
SLU
SMP/E
SNA
SO
SON
SQA
SQL*
SQLCA
SQLDA
SRB
SRG
SRM
STC
STP
STV
SWB
SYN
TA
TAS
TCB
TCID
TCP/IP
TI
TOD
TPF
TPF/DBR
TPFDF
TPF/MVS
TP_ID
TSI
TSN
TSO
TUT
UCB
UCTF
VFA
VM
VM/CMS
VS
VSAM
444
Systems Application Architecture*
System Authorization Facility
system allocator list (TPF terminology)
sequential access method
Synchronous Data Link Control
standard data and message file
System Display and Search Facility
system diagnostic work area
DBCS shift in
Société Internationale de Télécommunications Aéronautiques
ATA/IATA synchronous link control
serviceability level indication processing
symbolic line number
Service Level Reporter
secondary logical unit
System Modification Program Extended
Systems Network Architecture
DBCS shift out
system ordinal number
system queue area
Structured Query Language
SQL Communication Area
SQL Descriptor Area
service request block
statistical report generator
System Resource Manager
system test compiler
stop (SLC LCB)
system test vehicle
service work block
character synchronization character
terminal address
time available supervisor
task control block
terminal circuit identity
Transmission Control Protocol / Internet Protocol
time-initiated record
time of day
Transaction Processing Facility
Transaction Processing Facility/Data Base Reorganization
TPF Database Facility
Transaction Processing Facility/MVS (alternative name for ALCS V2)
transaction program identifier
transmission status indicator
transmission sequence number
time-sharing option
test unit tape (sequential file)
unit control block
Universal Communications Test Facility
virtual file access
virtual machine
virtual machine/conversational monitor system
virtual storage
virtual storage access method
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
VSE
VSE/AF
VSE/VSAM
VTAM*
VTOC
WSF
WTTY
XMSG
XREF
Virtual Storage Extended
Virtual Storage Extended/Advanced Function
Virtual Storage Extended/Virtual Storage Access Method
Virtual Telecommunications Access Method (refers to VTAM)
volume table of contents
Write Structured Field
World Trade Teletypewriter
XMSG message switching message format
ALCS cross referencing facility
Appendix A. Acronyms and abbreviations
445
Glossary
Notes:
agent set. Synonym for communication terminal.
1. Acronyms and abbreviations are listed separately
from this Glossary. See Appendix A, “Acronyms
and abbreviations” on page 440.
2. For an explanation of any term not defined here,
see the IBM Dictionary of Computing.
agent set control unit (ASCU). Synonym for terminal
interchange.
Airline Control Program (ACP). An earlier version of
the IBM licensed program Transaction Processing
Facility (TPF).
AAA hold. See terminal hold.
Airline Control System (ALCS). A transaction
processing platform providing high performance,
capacity, and availability, that runs specialized (typically
airline) transaction processing applications.
abnormal end of task (abend). Termination of a task
before its completion because of an error condition that
cannot be resolved by recovery facilities while the task
is executing.
Airline Control System/Multiple Virtual
Storage/Extended Architecture (ALCS/MVS/XA). An
ALCS release designed to run under an MVS/XA
operating system.
access method services (AMS). A utility program that
defines VSAM data sets (or files) and allocates space
for them, converts indexed sequential data sets to
key-sequenced data sets with indexes, modifies data
set attributes in the catalog, facilitates data set
portability between operating systems, creates backup
copies of data sets and indexes, helps make
inaccessible data sets accessible, and lists data set
records and catalog entries.
Airline Control System Version 2 (ALCS V2). An
ALCS release designed to run under an MVS/ESA
operating system.
A
activity control variable. A parameter that ALCS
uses to control its workload. The system programmer
defines activity control variables in the ALCS system
configuration table generation.
Advanced Communications Function for the
Network Control Program (ACF/NCP). An IBM
licensed program that provides communication
controller support for single-domain, multiple-domain,
and interconnected network capability.
Advanced Program-to-Program Communications
(APPC). A set of inter-program communication
services that support cooperative transaction processing
in an SNA network. APPC is the implementation, on a
given system, of SNA’s logical unit type 6.2 (LU 6.2).
See APPC component and APPC transaction
scheduler.
Aeronautical Radio Incorporated (ARINC). An
organization which provides communication facilities for
use within the airline industry.
agent assembly area (AAA). A fixed-file record used
by IPARS applications. One AAA record is associated
with each terminal and holds data that needs to be kept
beyond the life of an entry. For example, to collect
information from more than one message.
446
Airline Control System/Virtual Storage Extended
(ALCS/VSE). An ALCS release designed to run under
a VSE/AF operating system.
airlines line control (ALC). A communication protocol
particularly used by airlines.
Airlines Line Control Interconnection (ALCI). A
feature of Network Control Program (NCP) that allows it
to manage ALC networks in conjunction with a request
for price quotation (RPQ) scanner for the IBM 3745
communication controller.
Airline X.25 (AX.25). A discipline conforming to the
ATA/IATA AX.25 specification in the ATA/IATA
publication ATA/IATA Interline Communications Manual,
ATA/IATA document DOC.GEN 1840. AX.25 is based
on X.25 and is intended for connecting airline computer
systems to SITA or ARINC networks.
ALCS command. A command addressed to the ALCS
system. All ALCS commands start with the letter Z
(they are also called “Z messages”) and are 5
characters long.
These commands allow the operator to monitor and
control ALCS. Many of them can only be entered from
CRAS terminals. ALCS commands are called
“functional messages” in TPF.
ALCS data collection file. A series of sequential data
sets to which ALCS writes performance-related data for
subsequent processing by the statistical report
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
generator or other utility program. See also data
collection and statistical report generator.
ALCS diagnostic file. A series of sequential data sets
to which the ALCS monitor writes all types of diagnostic
data for subsequent processing by the diagnostic file
processor.
ALCS diagnostic file processor. An offline utility,
often called the “post processor”, that reads the ALCS
diagnostic file and formats and prints the dump, trace,
and system test vehicle (STV) data that it contains.
ALCS entry dispatcher. The ALCS online monitor's
main work scheduler. Often called the “CPU loop”.
ALCS offline program. An ALCS program that runs
as a separate MVS job (not under the control of the
ALCS online monitor).
ALCS online monitor. The part of ALCS that
performs the services for the ECB-controlled programs
and controls their actions.
ALCS trace facility. An online facility that monitors the
execution of application programs. When it meets a
selected monitor-request macro, it interrupts processing
and sends selected data to an ALCS display terminal,
to the ALCS diagnostic file, or to the system macro
trace block. See also instruction step.
The ALCS trace facility also controls tracing to the MVS
generalized trace facility (GTF), for selected VTAM
communication activity.
ALCS update log file. A series of sequential data sets
in which the ALCS monitor records changes to the
real-time database.
allocatable pool. The ALCS record class that includes
all records on the real-time database. Within this class,
there is one record type for each DASD record size.
The allocatable pool class is special in that ALCS itself
can dispense allocatable pool records and use them for
other real-time database record classes. For example,
all fixed-file records are also allocatable pool records
(they have a special status of “in use for fixed file”).
When ALCS is using type 2 long-term pool dispense,
ALCS satisfies requests for long-term pool by
dispensing available allocatable pool records.
See DASD record, real-time database, record class,
and record type.
alternate CRAS. A computer room agent set (CRAS)
that is not Prime CRAS or receive only CRAS. See
computer room agent set, Prime CRAS, and receive
only CRAS.
alternate CRAS printer. A CRAS printer that is not
receive only CRAS. See CRAS printer and receive only
CRAS.
answerback. A positive acknowledgement (ACK) from
an ALC printer.
APPC component. The component of MVS that is
responsible for extending LU 6.2 and SAA CPI
Communications services to applications running in any
MVS address space. Includes APPC conversations and
scheduling services.
APPC transaction scheduler. A program such as
ALCS that is responsible for scheduling incoming work
requests from cooperative transaction programs.
application plan. See DB2 application plan.
application. A group of associated application
programs that carry out a specific function.
application global area. An area of storage in the
ALCS address space containing application data that
any entry can access.
The application global area is subdivided into
keypointable and nonkeypointable records.
Keypointable records are written to the database after
an update; nonkeypointable records either never
change, or are reinitialized when ALCS restarts.
C programs refer to global records and global fields
within the application global area.
application program. A program that runs under the
control of ALCS. See also ECB-controlled program.
application program load module. In ALCS, a load
module that contains one or more application programs.
application queue. In message queuing with ALCS,
any queue on which application programs put and get
messages using MQI calls.
assign. Allocate a general sequential file to an entry.
The TOPNC monitor-request macro (or equivalent C
function) opens and allocates a general sequential file.
The TASNC monitor-request macro (or equivalent C
function) allocates a general sequential file that is
already open but not assigned to an entry (it is
reserved).
associated resource. Some ALCS commands
generate output to a printer (for example, ZDCOM prints
information about a communication resource). For this
type of command the printed output goes to the
associated resource; that is, to a printer associated with
the originating display. There is also a response to the
originating display that includes information identifying
the associated resource.
Glossary
447
asynchronous trace. One mode of operation of the
ALCS trace facility. Asynchronous trace is a
conversational trace facility to interactively trace entries
that do not originate from a specific terminal.
automatic storage block. A storage block that is
attached to an entry, but is not attached at a storage
level. An assembler program can use the ALASC
monitor-request macro to obtain an automatic storage
block and BACKC monitor-request macro to release it. C
programs cannot obtain automatic storage blocks.
B
backward chain. The fourth fullword of a record
stored on the ALCS database, part of the record
header. See chaining of records.
When standard backward chaining is used, this field
contains the file address of the previous record in the
chain, except that the first record contains the file
address of the last record in the chain. (If there is only
one record, the backward chain field contains zeros.)
balanced path. A path where no single component
(channel, DASD director or control unit, head of string,
and internal path to the DASD device) is utilized beyond
the limits appropriate to the required performance.
C
catastrophic. A type of system error that results in the
termination of ALCS.
chain-chase. See Recoup.
chaining of records. One record can contain the file
address of another (usually a pool-file record). The
addressed record is said to be chained from the
previous record. Chains of records can contain many
pool-file records. See forward chain and backward
chain.
class. See record class.
clearly differentiated programming interfaces
(CDPI). A set of guidelines for developing and
documenting product interfaces so that there is clear
differentiation between interfaces intended for general
programming use (GUPIs) and those intended for other
specialized tasks.
close. Close a sequential file data set (MVS CLOSE
macro) and deallocate it from ALCS. For general
sequential files this is a function of the TCLSC
monitor-request macro (or equivalent C function).
ALCS automatically closes other sequential files at
end-of-job.
BATAP. Type B application-to-application program
command. See ALCS command.
Binary Synchronous Communication (BSC). A form
of telecommunication line control that uses a standard
set of transmission control characters and control
character sequences, for binary synchronous
transmission of binary-coded data between stations.
bind. See DB2 bind
BIND. In SNA, a request to activate a session between
two logical units (LUs). The BIND request is sent from
a primary LU to a secondary LU. The secondary LU
uses the BIND parameters to help determine whether it
will respond positively or negatively to the BIND
request.
binder. The program that replaces the linkage editor
and batch loader programs that were provided with
earlier versions of MVS.
BIND image. In SNA, the set of fields in a BIND
request that contain the session parameters.
block. See storage block.
command list (CLIST). A sequential list of commands,
control statements, or both, that is assigned a name.
When the name is invoked the commands in the list are
executed.
common entry point (CEP). A function in the
Transaction Processing Facility Database Facility
(TPFDF) product that provides common processing for
all TPFDF macro calls issued by ALCS application
programs. It also provides trace facilities for TPFDF
macro calls.
commit. An operation that terminates a unit of
recovery. Data that was changed is now consistent.
Common Programming Interface – Communications
(CPI-C). The communication element of IBM Systems
Application Architecture (SAA). CPI-C provides a
programming interface that allows program-to-program
communication using the IBM SNA logical unit 6.2.
communication management configuration (CMC).
A technique for configuring a network that allows for the
consolidation of many network management functions
for the entire network in a single host processor.
communication resource. A communication network
component that has been defined to ALCS. These
448
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
include each terminal on the network and other network
components that ALCS controls directly (for example,
SLC links). Resources can include, for example:
SNA LUs (including LU 6.1 links)
ALC terminals
SLC and WTTY links
Applications.
communication resource identifier (CRI). A 3-byte
field that uniquely identifies an ALCS communication
resource. It is equivalent to the LN/IA/TA in TPF and
the LN/ARID in ALCS/VSE. ALCS generates a CRI for
each resource.
communication resource name (CRN). A 1- to
8-character name that uniquely identifies an ALCS
communication resource. For SNA LUs, it is the LU
name. The system programmer defines the CRN for
each resource in the ALCS communication generation.
communication resource ordinal. A unique number
that ALCS associates with each communication
resource. An installation can use the communication
resource ordinal as a record ordinal for a particular
fixed-file record type. This uniquely associates each
communication resource with a single record.
For example, IPARS defines a fixed-file record type
(#WAARI) for AAA records. Each communication
resource has its own AAA record – the #WAARI record
ordinal is the communication resource ordinal. See also
record ordinal and agent assembly area.
computer room agent set (CRAS). An ALCS terminal
that is authorized for the entry of restricted ALCS
commands.
Prime CRAS is the primary terminal that controls the
ALCS system. Receive Only CRAS (RO CRAS) is a
designated printer or NetView operator identifier to
which certain messages about system function and
progress are sent.
configuration data set. (1) A data set that contains
configuration data for ALCS. See also
configuration-dependent table. (2) The ALCS record
class that includes all records on the configuration data
set. There is only one record type for this class. See
record class and record type.
configuration-dependent table. A table, constructed
by the ALCS generation process, which contains
configuration-dependent data. Configuration-dependent
tables are constructed as conventional MVS load
modules. In ALCS V2, there are separate
configuration-dependent tables for:
System data
DASD data
Sequential file data
Communication data
Application program data.
See also configuration data set.
control byte. The fourth byte of a record stored on the
ALCS database, part of the record header. ALCS
ignores this byte; some applications, however, make
use of it.
control interval (CI). A fixed-length area of direct
access storage in which VSAM stores records. The
control interval is the unit of information that VSAM
transmits to or from direct access storage.
control transfer. The process that the ALCS online
monitor uses to create a new entry and to transfer
control to an ECB-controlled program.
conversation_ID:. An 8-byte identifier, used in
Get_Conversation calls, that uniquely identifies a
conversation. APPC/MVS returns a conversation_ID on
the CMINIT, ATBALLOC, and ATBGETC calls; a
conversation_ID is required as input on subsequent
APPC/MVS calls.
CPU loop. See ALCS entry dispatcher.
CRAS printer. A computer room agent set (CRAS)
that is a printer terminal. See computer room agent set.
CRAS display. A computer room agent set (CRAS)
that is a display terminal. See computer room agent
set.
CRAS fallback. The automatic process that occurs
when the Prime CRAS or receive only CRAS becomes
unusable by which an alternate CRAS becomes Prime
CRAS or receive only CRAS. See also Prime CRAS,
receive only CRAS, and alternate CRAS.
create service. An ALCS service that enables an
ALCS application program to create new entries for
asynchronous processing. The new ECBs compete for
system resources and, once created, are not dependent
or connected in any way with the creating ECB.
cycling the system. The ALCS system can be run in
one of four different system states. Altering the system
state is called cycling the system. See SLC link for
another use of the term “cycling”.
D
DASD record. A record stored on a direct access
storage device (DASD). ALCS allows the same range
of sizes for DASD records as it allows for storage
blocks, except no size L0 DASD records exist.
data collection. An online function that collects data
about selected activity in the system and sends it to the
ALCS data collection file, if there is one, or to the ALCS
diagnostic file. See also statictical report generator.
Glossary
449
database request module (DBRM). A data set
member created by the DB2 precompiler that contains
information about SQL statements. DBRMs are used in
the DB2 bind process. See DB2 bind.
DATABASE 2 (DB2). An IBM licensed program that
provides relational database services.
data-collection area. An ECB area used by the ALCS
online monitor for accumulating statistics about an
entry.
|
|
|
|
data event control block (DECB). An ALCS control
block, that may be acquired dynamically by an entry to
provide a storage level and data level in addition to the
16 ECB levels. It is part of entry storage.
| The ALCS DECB is independent of the MVS control
| block with the same name.
data file. A sequential data set, created by the system
test compiler (STC) or by the ZDATA DUMP command,
that contains data to be loaded on to the real-time
database. (An ALCS command ZDATA LOAD can be
used to load data from a data file to the real-time
database.) A data file created by STC is also called a
“pilot” or “pilot tape”.
DB2 package list. An ordered list of package names
that may be used to extend an application plan.
|
|
|
|
|
DECB level. When an application program, running
under ALCS, reads a record from a file, it must “own” a
storage block in which to put the record. The address
of the storage block may be held in an area of a DECB
called a storage level.
|
|
|
|
Similarly, there is an area in a DECB used for holding
the 8-byte file address, record ID, and record code
check (RCC) of a record being used by an entry. This
is a data level.
| The storage level and data level in a DECB, used
| together, are called a DECB level.
| See also ECB level.
diagnostic file. See ALCS diagnostic file.
dispatching priority. A number assigned to tasks,
used to determine the order in which they use the
processing unit in a multitasking situation.
dispense (a pool-file record). To allocate a long-term
or short-term pool-file record to a particular entry.
ALCS performs this action when requested by an
application program. See release a pool-file record.
| data level. An area in the ECB or a DECB used to
hold the file address, and other information about a
| record. See ECB level and DECB level.
data record information library (DRIL). A data set
used by the system test compiler (STC) to record the
formats of data records on the real-time system. DRIL
is used when creating data files.
DB2 application plan. The control structure produced
during the bind process and used by DB2 to process
SQL statements encountered during program execution.
See DB2 bind.
DB2 bind. The process by which the output from the
DB2 precompiler is converted to a usable control
structure called a package or an application plan.
During the process, access paths to the data are
selected and some authorization checking is performed.
DB2 Call Attach Facility (CAF). An interface between
DB2 and batch address spaces. CAF allows ALCS to
access DB2.
DB2 host variable. In an application program, an
application variable referenced by embedded SQL
statements.
DB2 package. Also called application package. An
object containing a set of SQL statements that have
been bound statically and that are available for
processing. See DB2 bind.
450
double-byte character set. A set of characters in
which each character is represented by 2 bytes.
Languages such as Japanese, Chinese, and Korean,
which contain more symbols than can be represented
by 256 code points, require double-byte character sets.
Because each character requires 2 bytes, entering,
displaying, and printing DBCS characters requires
hardware and supporting software that are
DBCS-capable.
duplex. A communication link on which data can be
sent and received at the same time. Synonymous with
full duplex. Communication in only one direction at a
time is called “half-duplex”. Contrast with simplex
transmission.
duplex database. Synonym for duplicated database.
duplicated database. A database where each data
set is a mirrored pair. In ALCS, you can achieve this
using either ALCS facilities or DASD controller facilities
(such as the IBM 3990 dual copy facility). See mirrored
pair.
product sensitive programming interface(PSPI). An
interface intended for use in customer-written programs
for specialized purpose only, such as diagnosing,
modifying, monitoring, repairing, tailoring or tuning of
ALCS. Programs using this interface may need to be
changed in order to run with new product releases or
versions, or as a result of service.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
dynamic program linkage. Program linkage where
the connection between the calling and called program
is established during the execution of the calling
program. In ALCS dynamic program linkage, the
connection is established by the ALCS ENTER/BACK
services. Contrast with static program linkage.
entry. The basic work scheduling unit of ALCS. An
entry is represented by its associated entry control
block (ECB). It exists either until a program that is
processing that entry issues an EXITC monitor-request
macro (or equivalent C function), or until it is purged
from the system. An entry is created for each input
message, as well as for certain purposes unrelated to
transactions. One transaction can therefore generate
several entries.
dynamic SQL. SQL statements that are prepared and
executed within an application program while the
program is executing. In dynamic SQL, the SQL source
is contained in host language variables rather than
being coded into the application program. The SQL
statement can change several times during the
application program's execution. Contrast with
embedded SQL.
entry control block (ECB). A control block that
represents a single entry during its life in the system.
entry dispatcher. See ALCS entry dispatcher.
entry macro trace block. There is a macro trace
block for each entry. Each time an entry executes a
monitor-request macro (or a corresponding C function),
ALCS records information in the macro trace block for
the entry.
E
ECB-controlled program. A program that runs under
the control of an entry control block (ECB). These
programs can be application programs or programs that
are part of ALCS, for example the ALCS programs that
process operator commands (Z messages).
ECB-controlled programs are known as E-type
programs in TPF.
This information includes the macro request code, the
name of the program that issued the macro, and the
displacement in the program. The ALCS diagnostic file
processor formats and prints these macro trace blocks
in ALCS system error dumps.
See also system macro trace block.
|
ECB level. When an application program, running
under ALCS, reads a record from file, it must “own” a
storage block in which to put the record. The address
of the storage block may be held in an area of the ECB
called a storage level.
There are 16 storage levels in the ECB. A storage
block with its address in slot zero in the ECB is said to
be attached on level zero.
|
|
|
entry storage. The storage associated with an entry.
It includes the ECB for the entry, storage blocks that
are attached to the ECB or DECBs, storage blocks that
are detached from the ECB or DECBs, automatic
storage blocks and DECBs.
equate. Informal term for an assignment instruction in
assembler languages.
Similarly, there are 16 areas in the ECB that may be
error index byte (EIB). See SLC error index byte.
| used for holding the 4-byte file addresses, record ID,
and record code check (RCC) of records being used by
an entry. These are the 16 data levels.
Execute Channel Program (EXCP). An MVS macro
used by ALCS V2 to interface to I/O subsystems for
SLC support.
Storage levels and data levels, used together, are
called ECB levels.
| See also DECB level.
embedded SQL. Also called static SQL. SQL
statements that are embedded within an application
program and are prepared during the program
preparation process before the program is executed.
After it is prepared, the statement itself does not change
(although values of host variables specified within the
statement can change). Contrast with dynamic SQL.
Emulation Program/Virtual Storage (EP/VS). A
component of NCP/VS that ALCS V2 uses to access
SLC networks.
ENTER/BACK. The general term for the application
program linkage mechanism provided by ALCS.
F
fetch access. Access which only involves reading (not
writing). Compare with store access.
|
|
|
|
file address. 4-byte (8 hexadecimal digits) value or
8-byte value in 4x4 format (low order 4-bytes contain a
4-byte file address, high order 4 bytes contain
hexadecimal zeroes) that uniquely identifies an ALCS
record on DASD. FIND/FILE services use the file
address when reading or writing DASD records. See
fixed file and pool file.
file address compute routine (FACE). An ALCS
routine, called by a monitor-request macro (or
equivalent C function) that calculates the file address of
a fixed-file record. The application program provides
Glossary
451
the FACE routine with the fixed-file record type and the
record ordinal number. FACE returns the 4-byte file
address.
| There is also an FAC8C monitor-request macro (or
| equivalent C function), that will return an 8-byte file
| address in 4x4 format.
FIND/FILE. The general term for the DASD I/O
services that ALCS provides.
fixed file. An ALCS record class – one of the classes
that reside on the real-time database. All fixed-file
records are also allocatable pool records (they have a
special status of “in use for fixed file”).
Within this class there are two record types reserved for
use by ALCS itself (#KPTRI and #CPRCR). There can
also be installation-defined fixed-file record types.
Each fixed-file record type is analogous to a relative file.
Applications access fixed-file records by specifying the
fixed-file record type and the record ordinal number.
Note however that fixed-file records are not physically
organized as relative files (logically adjacent records are
not necessarily physically adjacent).
See real-time database, record class, and record type.
See also system fixed file. Contrast with pool file.
| fixed-file record. One of the two major types of record
|
|
|
|
|
in the real-time database (the other is a pool-file
record). When the number of records of a particular
kind will not vary, the system programmer can define a
fixed file record type for these records. ALCS
application programs accessing fixed-file records use
the ENTRC monitor-request macro to invoke the 4-byte
file address compute routine (FACE or FACS) or use
the FAC8C monitor-request macro to compute an 8-byte
file address. The equivalent C functions are face or
facs or tpf_fac8c.
fixed-file record type. (Known in TPF as FACE ID.)
The symbol, by convention starting with a hash sign (#)5
which identifies a particular group of fixed-file records.
It is called the fixed-file record type symbol. The
equated value of this symbol (called the fixed-file record
type value) also identifies the fixed-file record type.
forward chain. The third fullword of a record stored on
the ALCS database (part of the record header). When
standard forward chaining is used, this field contains
the file address of the next record in the chain, except
that the last (or only) record contains binary zeros.
full-duplex. Deprecated term for duplex.
functional message. See ALCS command.
5
G
general data set (GDS). The same as a general file,
but accessed by different macros or C functions in
ALCS programs.
general file. (1) A DASD data set (VSAM cluster) that
is used to communicate data between offline utility
programs and the online system. General files are not
part of the real-time database. (2) The ALCS record
class that includes all records on the general files and
general data sets. Each general file and general data
set is a separate record type within this class. See
record class and record type.
general file record. A record on a general file.
generalized trace facility (GTF). An MVS trace
facility. See also ALCS trace facility.
general sequential file. A class of sequential data set
that is for input or output. ALCS application programs
must have exclusive access to a general sequential file
before they can read or write to it. See also real-time
sequential file.
general tape. TPF term for a general sequential file.
general-use programming interface (GUPI). An
interface intended for general use in customer-written
applications.
get file storage (GFS). The general term for the pool
file dispense mechanisms that ALCS provides.
global area. See application global area.
global resource serialization. The process of
controlling access of entries to a global resource so as
to protect the integrity of the resource.
H
half-duplex. A communication link that allows
transmission in one direction at a time. Contrast with
duplex.
halt. (1) The ALCS state when it is terminated.
(2) The action of terminating ALCS.
heap. An area of storage that a compiler uses to
satisfy requests for storage from a high-level language
(for example, calloc or malloc C functions). ALCS
provides separate heaps for each entry (if needed).
The heap is part of entry storage.
This character might appear differently on your equipment. It is the character represented by hexadecimal 7B.
452
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
hold. A facility that allows multiple entries to share
data, and to serialize access to the data. The data can
be a database record, or any named data resource.
This facility can be used to serialize conflicting
processes. See also record hold and resource hold.
host variable. See DB2 host variable
high-level designator. The SLC address of a
switching center that is part of a high-level network. It
comprises two bytes in the 7-bit transmission code used
by SLC.
high-level language (HLL) storage unit. Alternative
name for a type 2 storage unit. See storage unit.
high-level network (HLN). A network that provides
transmission services between transaction processing
systems (for example, ALCS) and terminals. Strictly,
the term “high-level network” applies to a network that
connects to transaction processing systems using SLC.
But in ALCS publications, this term is also used for a
network that connects by using AX.25.
HLN entry address (HEN). The high-level designator
of the switching center where an SLC link data block
enters a high-level network.
HLN exit address (HEX). The high-level designator of
the switching center where an SLC link data block
leaves a high-level network.
I
information block. See SLC link data block.
initial storage allocation (ISA). An area of storage
acquired at initial entry to a high-level language
program. ALCS provides a separate ISA for each entry
(if required). The ISA is part of entry storage.
initiation queue. In message queuing, a local queue
on which the queue manager puts trigger messages.
You can define an initiation queue to ALCS, in order to
start an ALCS application automatically when a trigger
message is put on the queue. See trigger message.
input/output control block (IOCB). A control block
that represents an ALCS internal “task”. For example,
ALCS uses an IOCB to process a DASD I/O request.
a customer’s system programmers to change or extend
the functions of the IBM software product. Such
modifications consist of exit routines written to replace
an existing module of an IBM software product, or to
add one or more modules or subroutines to an IBM
software product for the purpose of modifying (including
extending) the functions of the IBM software product.
Contrast with user exit.
instruction step. One mode of operation of the ALCS
trace facility. Instruction step is a conversational trace
facility that stops the traced application program before
the execution of each processor instruction.
interchange address (IA). In ALC, the 1-byte address
of a terminal interchange. Different terminal
interchanges connected to the same ALC link have
different interchange addresses. Different terminal
interchanges connected to different ALC links can have
the same interchange address. See also terminal
interchange
International Programmed Airlines Reservation
System (IPARS). A set of applications for airline use.
The principal functions are reservations and message
switching.
IPARS for ALCS. The ALCS shipment includes IPARS
as a sample application, and installation verification aid
for ALCS.
K
KCN. Abbreviation for an SLC channel number. See
SLC channel.
keypointable. See application global area.
keypoint B (CTKB). A record that contains dynamic
system information that ALCS writes to DASD when it is
updated so that ALCS can restart from its latest status.
L
Language Environment. A common run-time
environment and common run-time services for OS/390
High Level Language compilers.
level. See ECB level.
input queue. In message queuing with ALCS, you can
define a local queue to ALCS in order to start an ALCS
application automatically when a message is put on that
queue. ALCS expects messages on the input queue to
be in PPMSG message format. See PPMSG.
line number (LN). (1) In ALC, the 1-byte address of
an ALC link. Different links connected to the same
communication controller have different line numbers.
Different links connected to different communication
controllers can have the same line number.
(2) Synonym for symbolic line number.
installation-wide exit. The means specifically
described in an IBM software product’s documentation
by which an IBM software product may be modified by
Link Control — Airline (LICRA). The name of a
programming request for price quotation (PRPQ) to the
Glossary
453
IBM 3705 Emulation Program (EP/VS). This modifies
EP/VS to support SLC networks.
link control block (LCB). See SLC link control block.
link data block (LDB). See SLC link data block.
link trace. See SLC link trace.
local DXCREI index (LDI). The first byte of a
communication resource indicator (CRI).
local queue. In message queuing, a queue that
belongs to the local queue manager. A local queue can
contain a list of messages waiting to be processed.
Contrast with remote queue.
lock. A serialization mechanism whereby a resource is
restricted for use by the holder of the lock. See also
hold.
log. See ALCS update log.
logging. The process of writing copies of altered
database records to a sequential file. This is the
method used to provide an up-to-date copy of the
database should the system fail and the database have
to be restored. The database records are logged to the
ALCS update log file.
long-term pool. An ALCS record class – one of the
classes that reside on the real-time database. Within
this class, there is one record type for each DASD
record size. All long-term pool-file records are also
allocatable pool records. ALCS application programs
can use long-term pool records for long-lived or
high-integrity data. See pool file, real-time database,
record class, and record type.
L0, L1, L2, L3, ..., L8. Assembler symbols (and
defined values in C) for the storage block sizes and
record sizes that ALCS supports. See DASD record
and storage block size.
M
macro trace block. See entry macro trace block and
system macro trace block.
Mapping of Airline Traffic over IP (MATIP). A
protocol for transporting traditional airline messages
over an IP (Internet Protocol) network. Internet RFC
(Request for Comments) number 2351 describes the
MATIP protocol.
logical end-point identifier (LEID). In NEF2 and ALCI
environments, a 3-byte identifier assigned to an ALC
terminal.
message. For terminals with an Enter key, an input
message is the data that is sent to the host when the
Enter key is hit. A response message is the data that is
returned to the terminal. WTTY messages have special
“start/end of message” character sequences. One or
more input and output message pairs make up a
transaction.
logical unit type 6.2 (LU 6.2). The SNA logical unit
type that supports general communication between
programs in a distributed processing environment; the
SNA logical unit type on which Common Programming
Interface – Communications (CPI-C) is built.
Message Queue Interface (MQI). The programming
interface provided by the IBM MQSeries message
queue managers. This programming interface allows
application programs to access message queuing
services.
log in. TPF term for establishing routing between a
terminal and an application.
message queue manager. See queue manager.
log on. Establish a session between an SNA terminal
and an application such as ALCS. See also routing.
MQSeries for OS/390. An IBM licensed program that
provides message queuing services. It is part of the
IBM MQSeries set of products.
logon mode. In VTAM, a set of predefined session
parameters that can be sent in a BIND request. When
a set is defined, a logon mode name is associated with
the set.
logon mode table. In VTAM, a table containing
several predefined session parameter sets, each with its
own logon mode name.
long message transmitter (LMT). A part of the
IPARS application that is responsible for blocking and
queuing printer messages for output. Also called
XLMT.
454
message queuing. A programming technique in which
each program within an application communicates with
the other programs by putting messages on queues.
This enables asynchronous communication between
processes that may not be simultaneously active, or for
which no data link is active. The message queuing
service can assure subsequent delivery to the target
application.
MBI exhaustion. The condition of an SLC link when a
sender cannot transmit another message because all 7
SLC message labels are already “in use”; that is, the
sender must wait for acknowledgement of a message
so that it can reuse the corresponding message label.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
See also SLC link, SLC message label, and SLC
message block indicator.
NetView*. A family of IBM licensed programs for the
control of communication networks.
message block indicator. See SLC message block
indicator.
NetView operator identifier (NetView operator ID). A
1- to 8-character name that identifies a NetView
operator.
message label. See SLC message label.
message switching. An application that routes
messages by receiving, storing, and forwarding
complete messages. IPARS for ALCS includes a
message switching application for messages that
conform to ATA/IATA industry standards for interline
communication ATA/IATA Interline Communications
Manual, DOC.GEN/1840.
monitor-request macro. Assembler language macro
provided with ALCS, corresponding to TPF “SVC-type”
or “control program” macros. Application programs use
these macros to request services from the online
monitor.
mirrored pair. Two units that contain the same data
and are referred to by the system as one entity.
multibyte character. A mixture of single-byte
characters from a single-byte character set and
double-byte characters from a double-byte character
set.
NetView program. An IBM licensed program used to
monitor a network, manage it, and diagnose network
problems.
NetView resource. A NetView operator ID which
identifies one of the following:
5 A NetView operator logged on to a terminal.
5 A NetView operator ID automation task. One of
these tasks is used by ALCS to route RO CRAS
messages to the NetView Status Monitor Log
(STATMON).
network control block (NCB). A special type of
message, used for communication between a
transaction processing system and a high-level network
(HLN). For example, an HLN can use an NCB to
transmit information about the network to a transaction
processing system.
For a network that connects using SLC, an NCB is an
SLC link data block (LDB). Indicators in the LDB
differentiate NCBs from other messages.
multiblock message. In SLC, a message that is
transmitted in more than one link data block. See link
data block.
For a network that connects using AX.25, NCBs are
transmitted across a dedicated permanent virtual circuit
(PVC).
Multiple Virtual Storage/Enterprise System
Architecture (MVS/ESA). This operating system is
required to run ALCS V2.
Network Control Program (NCP). An IBM licensed
program resident in an IBM 37xx Communication
Controller that controls attached lines and terminals,
performs error recovery, and routes data through the
network.
Multisystem Networking Facility (MSNF). An
optional feature of VTAM that permits these access
methods, together with NCP, to control a
multiple-domain network.
N
namelist. In message queuing, a namelist is an object
that contains a list of other objects.
native file address. For migration purposes ALCS
allows two or more file addresses to refer to the same
database or general file record. The file address that
ALCS uses internally is called the native file address.
NCP Packet Switching Interface (NPSI). An IBM
licensed program that allows communication with X.25
lines.
Network Control Program Packet Switching
Interface (NPSI). An IBM licensed program that
provides a bridge between X.25 and SNA.
Network Control Program/Virtual Storage (NCP/VS).
An IBM licensed program. ALCS V2 uses the EP/VS
component of NCP/VS to access SLC networks.
Network Extension Facility (NEF). The name of a
programming request for price quotation (PRPQ
P09021) that allows management of ALC networks by
NCP; now largely superseded by ALCI.
Network Terminal Option (NTO). An IBM licensed
program that converts start-stop terminal device
communication protocols and commands into SNA and
VTAM communication protocols and commands. ALCS
uses NTO to support World Trade Teletypewriter
(WTTY).
Glossary
455
O
received until the reponse is sent to the communication
facilities.
object. In message queuing, objects define the
attributes of queue managers, queues, process
definitions, and namelists.
pilot.
offline. A function or process that runs independently
of the ALCS online monitor. For example, the ALCS
diagnostic file processor is an offline function. See also
ALCS offline program.
online. A function or process that is part of the ALCS
online monitor, or runs under its control. For example,
all ALCS commands are online functions. See also
ALCS online monitor.
open. Allocate a sequential file data set to ALCS and
open it (MVS OPEN macro). For general sequential files
this is a function of the TOPNC monitor-request macro (or
equivalent C function). ALCS automatically opens other
sequential files during restart.
operator command. See ALCS command. Can also
refer to non-ALCS commands, for example, MVS or
VTAM commands.
ordinal. See communication resource ordinal and
record ordinal.
P
See data file.
pool directory update (PDU). A facility of TPF that
recovers long-term pool file addresses without running
Recoup. PDU identifies and makes available all
long-term pool-file records that have been released.
pool file. Short-term pool, long-term pool, and
allocatable pool. Within each pool file class, there is
one record type for each record size; for example,
short-term pool includes the record type L1STPOOL
(size L1 short-term pool records).
Each pool-file record type contains some records that
are in-use and some that are available. There is a
dispense function that selects an available record,
changes its status to in-use, and returns the file
address. Also, there is a release function that takes the
file address of an in-use pool-file record and changes
the record status to available.
To use a pool-file record, a program must:
1. Request the dispense function. This returns the file
address of a record. Note that the record contents
are, at this stage, unpredictable.
2. Write the initial record contents, using the file
address returned by step 1.
3. Save the file address returned by step 1.
package. See DB2 package
package list. See DB2 package list
padded ALC. A transmission code that adds one or
more bits to the 6-bit airline line control (ALC)
transmission code so that each ALC character occupies
one character position in a protocol that uses 7- or 8-bit
transmission codes. See also airlines line control.
4. Read and write the record to access and update the
information as required. These reads and writes
use the file address saved in step 3.
When the information in the record is no longer
required, a program must:
5. Delete (clear to zeros) the saved copy of the file
address (see step 3).
6. Request the release function.
padded SABRE. Synonym for padded ALC.
See also record class. Contrast with fixed file.
passenger name record (PNR). A type of record
commonly used in reservation systems. It contains all
the recorded information about an individual passenger.
pool file directory record (PFDR). The ALCS pool file
management routine keeps a directory for each size
(L1, L2, ...L8) of short-term pool file records and
long-term pool-file records. It keeps these directories in
pool file directory records.
path. The set of components providing a connection
between a processor complex and an I/O device. For
example, the path for an IBM 3390 DASD volume might
include the channel, ESCON Director, 3990 Storage
Path, 3390 Device Adapter, and 3390 internal
connection. The specific components used in a
particular path are dynamic and may change from one
I/O request to the next. See balanced path.
pathlength. The number of machine instructions
needed to process a message from the time it is
456
pool-file record. ALCS application programs access
pool-file records with file addresses similar to those for
fixed-file records. To obtain a pool-file record, an
application program uses a monitor-request macro (or
equivalent C function) that specifies a 2-byte record ID
or a pool-file record type.
When the data in a pool-file record is no longer
required, the application uses a monitor-request macro
(or equivalent C function) to release the record for
reuse. See pool file.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
pool-file record identifier (record ID). The record ID
of a pool-file record. On get file requests (using the
GETFC monitor-request macro or equivalent C function)
the program specifies the pool-file record ID. This
identifies whether the pool-file record is a short-term or
long-term pool-file record and also determines the
record size (L1, L2, ...L8). (Coding the 2-byte record
IDs, and the corresponding pool-file record sizes and
types, is part of the ALCS generation procedure.) See
also record ID qualifier.
pool-file record type. Each collection of short-term
and long-term pool-file records of a particular record
size (identified by the symbols L1, L2, ..., L8) is a
different record type. Each pool-file record type has a
different name. For short-term pool-file records, this is
LnSTPOOL, where Ln is the record size symbol. For
long-term pool-file records the name is LnLTPOOL.
post processor. See ALCS diagnostic file processor.
PPMSG. ALCS program-to-program message format,
used by the ALCS message router to send and receive
messages on a message routing path to another
system. In PPMSG message format, the routing control
parameter list (RCPL) precedes the message text.
primary action code. The first character of any input
message. The primary action code Z is reserved for
ALCS commands. See secondary action code.
Prime CRAS. The primary display terminal, or
NetView ID, that controls the ALCS system. See also
computer room agent set (CRAS).
process definition object. In message queuing, an
object that contains the definition of a message queuing
application. For example, a queue manager uses the
definition when it works with trigger messages.
program linkage. Mechanism for passing control
between separate portions of the application program.
See dynamic program linkage and static program
linkage.
program nesting level. One of 32 ECB areas used by
the ENTER/BACK mechanism for saving return control
data.
program-to-program interface. In NetView, a facility
that allows user programs to send data to, or receive
data from, other user programs. It also allows system
and application programs to send alerts to the NetView
hardware monitor.
P.1024. A SITA implementation of SLC. See SLC.
P.1124. A SITA implementation of SLC. See SLC.
Q
queue manager. A system program that provides
queuing services to applications. It provides an
application programming interface so that programs can
access messages on the queues that the queue
manager owns. MQSeries for OS/390 is an example of
a queue manager.
R
real-time database. The database to which ALCS
must have permanent read and write access. As an
ALCS generation option, the real-time database can be
duplicated in order to minimize the effects of a DASD
failure.
real-time sequential file. A sequential data set used
only for output. ALCS application programs can write to
any real-time sequential file without requiring exclusive
access to the data set. See also general sequential file.
real-time tape. TPF term for a real-time sequential file.
receive only (RO). The function of a communication
terminal that can receive but not send data. An
example is a printer that does not have a keyboard.
receive only CRAS. A printer terminal (or NetView
operator ID) that ALCS uses to direct status messages.
Commonly known as RO CRAS.
record. A set of data treated as a unit.
record class. The first (highest) level categorization of
ALCS DASD records. ALCS defines the following
record classes:
Allocatable pool
Application fixed file
Configuration data set
General file
Long-term pool
Short-term pool
System fixed file.
See also record type and record ordinal.
record code check (RCC). The third byte of any
record stored in the ALCS database. It is part of the
record header.
The RCC field is intended to help detect the incorrect
chaining of records which have the same record ID.
This is particularly useful for passenger name records
(PNRs), of which there are often hundreds of
thousands. A mismatch in RCC values shows that the
chain is broken, probably as a result of an application
program releasing a record too soon. (A false match
P.1024A. The SITA implementation of airline line
control (ALC).
Glossary
457
cannot be excluded, but the RCC should give early
warning of a chaining problem.)
record type number. A number that identifies a
record type.
record header. A standard format for the first 16 bytes
of a record stored on the ALCS database. It contains
the following fields:
record type symbol. The character string that
identifies a fixed-file record type (#xxxxx), a long-term
pool-file record type (LsLTPOOL), a short-term pool-file
record type (LsSTPOOL), or a general file (GF-nnn).
The value of the record type symbol is the record type
number.
Record ID
Record code check
Control byte
Application program name
Forward chain
Backward chain.
Not all records contain forward chains and backward
chains. Some applications extend the record header by
including extra fields. TPFDF uses an extended record
header.
record hold. A type of hold that applies to DASD
records. Applications that update records can use
record hold to prevent simultaneous updates. See also
resource hold.
record identifier (record ID). The first two bytes of a
record stored on the ALCS database, part of the record
header.
The record ID should always be used to indicate the
nature of the data in the record. For example, airlines
reservations applications conventionally store passenger
name records (PNRs) as long-term pool-file records
with a record ID of 'PR'.
When application programs read such records, they can
(optionally) request ALCS to check that the record ID
matches that which the application program expects.
When application programs request ALCS to dispense
pool file records, ALCS uses the record ID to select an
appropriate long-term or short-term pool-file record of
the requested record size (L1, L2,...,L8). See also
record ID qualifier.
record ID qualifier. A number 0 through 9 that
differentiates between record types that have the same
record ID.
For compatibility with previous implementations of the
record ID qualifier, ALCS also accepts the character
qualifiers P and O. P (primary) is equivalent to 0, and
O (overflow) is equivalent to 1.
record ordinal. The relative record number within a
record type. See record class and record type.
record size. See DASD record.
record type. The second level categorization of ALCS
DASD records. Within any one record class, the
records are categorized into one or more record types.
See also record type number, record type symbol,
record class and record ordinal.
458
Recoup. A real-time database validation routine which
runs online in the ALCS system. (Note that, while the
Recoup routines of TPF consist of a number of phases,
some online and some offline, the ALCS Recoup is a
single online phase that runs, without operator
intervention, in any system state.)
Recoup reads selected fixed-file records in the
database, and then follows up all chains of pool-file
records in the database, noting that these records are in
use and giving a warning of any that have been
corrupted or released. It then updates the pool file
directory records (PFDRs) to show the status of all
records.
The ALCS pool file dispense procedure identifies
records not in a chain (and so apparently available for
reuse) that have not been released.
recoup descriptors. These describe the structure of
the entire real-time database.
reentrant. The attribute of a program or routine that
allows the same copy of the program or routine to be
used concurrently by two or more tasks. All ALCS
application programs must be reentrant.
relational database. A database that is in accordance
with the relational model of data. The database is
perceived as a set of tables, relationships are
represented by values in tables, and data is retrieved by
specifying a result table that can be derived from one or
more base tables.
release (a pool-file record). To make available a
long-term or short-term pool-file record so that it can be
subsequently dispensed. An application program
requests the release action. See dispense a pool-file
record.
release file storage (RFS). The general term for the
pool-file release mechanisms that ALCS provides.
remote queue. In message queuing, a queue that
belongs to a remote queue manager. Programs can
put messages on remote queues, but they cannot get
messages from remote queues. Contrast with local
queue.
reservations. An online application which is used to
keep track of seat inventories, flight schedules, and
other related information. The reservation system is
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
designed to maintain up-to-date data and to respond
within seconds or less to inquiries from ticket agents at
locations remote from the computing system.
S
IPARS for ALCS includes a sample reservations
application for airlines.
scroll. To move a display image vertically or
horizontally to view data that otherwise cannot be
observed within the boundaries of the display screen.
Remote terminal trace.. One mode of operation of the
ALCS trace facility. Remote terminal trace is a
conversational trace facility to interactively trace entries
from a terminal other than your own.
secondary action code. The second character of an
ALCS command. (ALCS commands are made up of 5
characters: Z followed by a secondary action code.)
See primary action code.
reserve. Unassign a general sequential file from an
entry but leave the file open, so that another (or the
same) entry can assign it. Application programs can
use the TRSVC monitor-request macro (or equivalent C
function) to perform this action.
sequential file. A file in which records are processed
in the order in which they are entered and stored in the
file. See general sequential file and real-time sequential
file.
resource. Any facility of a computing system or
operating system required by a job or task, and
including main storage, input/output devices, processing
unit, data sets, and control or processing programs.
See also communication resource.
serialization. A service that prevents parallel or
interleaved execution of two or more processes by
forcing the processes to execute serially.
RO CRAS. See receive only CRAS.
For example, two programs can read the same data
item, apply different updates, and then write the data
item. Serialization ensures that the first program to
start the process (read the item) completes the process
(writes the updated item) before the second program
can start the process – the second program applies its
update to the data item which already contains the first
update. Without serialization, both programs can start
the process (read the item) before either completes the
process (writes the updated item) – the second write
destroys the first update. See also assign, lock, and
hold.
rollback. An operation that reverses all the changes
made during the current unit of recovery. After the
operation is complete, a new unit of recovery begins.
Serviceability Level Indicator Processing (SLIP). An
MVS operator command which acts as a problem
determination aid.
routing. The connection between a communication
resource connected to ALCS (typically a terminal on an
SNA or non-SNA network) and an application (running
under ALCS or another system). Also sometimes called
“logging in”, but this must be distinguished from logging
on, which establishes the SNA connection (session)
between the terminal and ALCS.
short-term pool. An ALCS record class – one of the
classes that resides on the real-time database. Within
this class, there is one record type for each DASD
record size. All short-term pool-file records are also
allocatable pool records (they have a special status of
“in use for short-term pool”). ALCS application
programs can use short-term pool records for
short-lived low-integrity data. See pool file, real-time
database, record class, and record type.
resource entry index (REI). The second and third
bytes of a communication resource identifier (CRI).
resource hold. A type of hold that can apply to any
type of resource. Applications can define resources
according to their requirements, and identify them to
ALCS using a unique name. See also record hold.
routing control parameter list (RCPL). A set of
information about the origin, destination, and
characteristics of a message. With each input
message, ALCS provides an RCPL in the ECB. An
output message that is sent using the ROUTC (routc)
service also has an RCPL associated with it.
6
simplex transmission. Data transmission in one
direction only. See also duplex and half-duplex.
sine in/out. Those applications that provide different
functions to different end users of the same application
can require the user to sine in6 to the specific functions
they require. The sine-in message can, for example,
include an authorization code.
This spelling is established in the airline industry.
Glossary
459
single-block message. In SLC, a message that is
transmitted in one link data block. See link data block.
single-phase commit. A method in which a program
can commit updates to a message queue or relational
database without coordinating those updates with
updates the program has made to resources controlled
by another resource manager. Contrast with two-phase
commit.
messages are assigned SLC message labels in the
sequence: 0, 2, 3, ... 6, 7, 0, 2, and so on. In P.1124,
single-block messages are (optionally) also included in
the sequence. See also P.1024, P.1124 and SLC
message block indicator.
SLC transmission status indicator (TSI). A 1-byte
field in the SLC link data block that contains the SLC
transmission sequence number. See also SLC
transmission sequence number.
SLC. See synchronous link control.
SLC channel. A duplex telecommunication line using
ATA/IATA SLC protocol. There can be from 1 to 7
channels on an SLC link.
SLC error index byte (EIB). A 1-byte field generated
by Line Control – Airline (LICRA) and transferred to
ALCS with each incoming link control block and link
data block. Certain errors cause LICRA to set on
certain bits of the EIB. See also Link Control — Airline
(LICRA).
SLC information block. Synonym for SLC link data
block.
SLC link. A processor-to-processor or
processor-to-HLN connection. ALCS supports up to
255 SLC links in an SLC network.
An SLC link that is in the process of an open, close,
start, or stop function is said to be “cycling”.
SLC link control block (LCB). A 4-byte data item
transmitted across an SLC link to control
communications over the link. LCBs are used, for
example, to confirm that a link data block (LDB) has
arrived, to request retransmission of an LDB, and so on.
SLC link data block (LDB). A data item, transmitted
across an SLC link, that contains a message or part of
a message. One LDB can contain a maximum of 240
message characters, messages longer than this must
be split and transmitted in multiple LDBs. Synonymous
with SLC information block.
SLC link trace. A function that provides a record of
SLC communication activity. It can either display the
information in real time or write it to a diagnostic file for
offline processing, or both. Its purpose is like that of an
NCP line trace, but for the SLC protocol.
SLC message block indicator (MBI). A 1-byte field in
the SLC link data block that contains the SLC message
label and the block number. A multiblock message is
transmitted in a sequence of up to 16 link data blocks
with block numbers 1, 2, 3, ... 16. See also multiblock
message, SLC link data block, and SLC message label.
SLC message label. A number in the range 0 through
7, excluding 1. In P.1024, consecutive multiblock
460
SLC transmission sequence number (TSN). A
number in the range 1 through 31. Consecutive SLC
link data blocks transmitted in one direction on one SLC
channel are assigned TSNs in the sequence: 1, 2, 3, ...
30, 31, 1, 2, and so on. See also SLC link data block,
SLC channel, and SLC transmission status indicator.
SLC Type A traffic. See Type A traffic.
SLC Type B traffic. See Type B traffic.
Société Internationale de Télécommunications
Aéronautiques (SITA). An international organization
which provides communication facilities for use within
the airline industry.
SQL Communication Area (SQLCA). A structure
used to provide an application program with information
about the execution of its SQL statements.
SQL Descriptor Area (SQLDA). A structure that
describes input variables, output variables, or the
columns of a result table used in the execution of
manipulative SQL statements.
stack. An area of storage that a compiler uses to
allocate variables defined in a high-level language.
ALCS provides separate stacks for each entry (if
needed). The stack is part of entry storage.
standby. The state of ALCS after it has been
initialized but before it has been started. Standby is not
considered one of the system states.
static program linkage. Program linkage where the
connection between the calling and called program is
established before the execution of the program. The
connection is established by the assembler, compiler,
prelinker, or linkage editor. Static program linkage does
not invoke ALCS monitor services. See also dynamic
program linkage.
static SQL. See embedded SQL.
statistical report generator (SRG). An offline ALCS
utility that is a performance monitoring tool. It takes the
data written to the ALCS data collection or diagnostic
file processor by the data collection function and
produces a variety of reports and bar charts. The SRG
is the equivalent of TPF “data reduction”.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
STATMON. See NetView resource.
storage block. An area of storage that ALCS allocates
to an entry. It is part of entry storage. See storage
block sizes.
storage block size. ALCS allows storage blocks of up
to 9 different sizes. These are identified in programs by
the assembler symbols (or defined C values) L0, L1, L2,
..., L8. Installations need not define all these block
sizes but usually define at least the following:
Size
Size
Size
Size
Size
L0
L1
L2
L3
L4
contains
contains
contains
contains
contains
127 bytes of user data
381 bytes of user data
1055 bytes of user data
4000 bytes of user data
4095 bytes of user data.
The system programmer can alter the size in bytes of
L1 through L4, and can specify the remaining block
sizes.
| storage level. An area in the ECB or a DECB used to
hold the address and size of a storage block. See ECB
| level and DECB level.
storage unit. The ALCS storage manager allocates
storage in units called storage units. Entry storage is
suballocated within storage units; for example, one
storage unit can contain an ECB and several storage
blocks attached to that ECB.
ALCS uses two types of storage unit:
5 Prime and overflow storage units for entry storage
(also called type 1 storage units)
5 High-level language storage units for heap and
stack storage (also called type 2 storage units).
Communication Control Procedures (ADCCP) of the
American National Standards Institute (ANSI) and
High-level Data Link Control (HDLC) of the International
Organization for Standardization, for managing
synchronous, code-transparent, serial-by-bit information
transfer over a link connection.
Transmission exchanges can be duplex or half-duplex
over switched or nonswitched links. The configuration
of the link connection can be point-to-point, multipoint,
or loop.
Synchronous Link Control (SLC). A discipline
conforming to the ATA/IATA Synchronous Link Control,
as described in the ATA/IATA publication ATA/IATA
Interline Communications Manual, ATA/IATA document
DOC.GEN 1840.
syncpoint. An intermediate or end point during
processing of a transaction at which the transaction's
protected resources are consistent. At a syncpoint,
changes to the resources can safely be committed, or
they can be backed out to the previous syncpoint.
system error. Error that the ALCS monitor detects.
Typically, ALCS takes a dump, called a system error
dump, to the ALCS diagnostic file. See also ALCS
diagnostic file and ALCS diagnostic file processor. See
also system error dump, system error message.
system error dump. (1) A storage dump that ALCS
writes to the ALCS diagnostic file when a system error
occurs. See also ALCS diagnostic file and system
error. (2) The formatted listing of a storage dump
produced by the ALCS diagnostic file processor. See
also ALCS diagnostic file processor.
The size of a storage unit, and the number of each type
of of storage unit, is defined in the ALCS generation.
See entry storage.
system error message. A message that ALCS sends
to receive only CRAS when a system error occurs. See
also receive only CRAS and system error.
store access. Access which only involves writing (not
reading). Compare with fetch access.
system error option. A parameter that controls what
action ALCS takes when it detects a system error. See
also system error.
striping. A file organization in which logically adjacent
records are stored on different physical devices. This
organization helps to spread accesses across a set of
physical devices.
Structured Query Language (SQL). a standardized
language for defining and manipulating data in a
relational database.
symbolic line number (SLN). In TPF, a 1-byte
address of an ALC link, derived from the line number
but adjusted so that all ALC links connected to the TPF
system have a different symbolic line number. See also
line number.
Synchronous Data Link Control (SDLC). A discipline
conforming to subsets of the Advanced Data
system fixed file. An ALCS record class – one of the
classes that reside on the real-time database. All
system fixed-file records are also allocatable pool
records (they have a special status of “in use for system
fixed file”).
System fixed-file records are reserved for use by ALCS
iteslf. See real-time database, record class, and record
type.
system macro trace block. There is one system
macro trace block. Each time an entry issues a
monitor-request macro (or equivalent C function), ALCS
records information in the system macro trace block.
This information includes the ECB address, the macro
request code, the name of the program that issued the
Glossary
461
macro, and the displacement in the program. The
ALCS diagnostic file processor formats and prints the
system macro trace block in ALCS system error dumps.
See also entry macro trace block.
System Modification Program/Extended (SMP/E).
An IBM licensed program used to install software and
software changes on MVS systems. In addition to
providing the services of SMP, SMP/E consolidates
installation data, allows flexibility in selecting changes to
be installed, provides a dialog interface, and supports
dynamic allocation of data sets.
Systems Application Architecture (SAA). A set of
software interfaces, conventions, and protocols that
provide a framework for designing and developing
applications with cross-system consistency.
Systems Network Architecture (SNA). The
description of the logical structure, formats, protocols,
and operational sequences for transmitting information
units through, and controlling the configuration and
operation of networks.
system sequential file. A class of sequential data
sets used by ALCS itself. Includes the ALCS diagnostic
file, the ALCS data collection file, and the ALCS update
log file or files.
system state. The ALCS system can run in any of the
following system states: IDLE, CRAS, message
switching (MESW), and normal (NORM).
Each state represents a different level of availability of
application functions. Altering the system state is called
“cycling the system”. See also standby.
system test compiler (STC). An offline ALCS utility
that compiles data onto data files for loading on to the
real-time database. STC also builds test unit tapes
(TUTs) for use by the system test vehicle (STV).
system test vehicle (STV). An online ALCS function
that reads input messages from a general sequential file
test unit tape (TUT) and simulates terminal input. STV
intercepts responses to simulated terminals and writes
them to the ALCS diagnostic file.
T
terminal. A device capable of sending or receiving
information, or both. In ALCS this can be a display
terminal, a printer terminal, or a NetView operator
identifier.
terminal address (TA). In ALC, the 1-byte address of
an ALC terminal. Different terminals connected to the
same terminal interchange have different terminal
addresses. Different terminals connected to different
462
terminal interchanges can have the same terminal
address. See also terminal interchange.
terminal circuit identity (TCID). Synonym for line
number.
terminal hold. When an ALCS application receives an
input message, it can set terminal hold on for the input
terminal. Terminal hold remains on until the application
sets it off. The application can reject input from a
terminal that has terminal hold set on. Also referred to
as AAA hold.
terminal interchange (TI). In ALC, synonym for
terminal control unit.
terminate. (1) To stop the operation of a system or
device. (2) To stop execution of a program.
test unit tape (TUT). A general sequential file that
contains messages for input to the system test vehicle
(STV). TUTs are created by the system test compiler
(STC).
time available supervisor (TAS). An ALCS or TPF
function that creates and dispatches low priority entries.
time-initiated function. A function initiated after a
specific time interval, or at a specific time. In ALCS this
is accomplished by using the CRETC monitor-request
macro or equivalent C function. See create service.
TP profile. The information required to establish the
environment for, and attach, an APPC/MVS transaction
program on MVS, in response to an inbound allocate
request for the transaction program.
trace facility. See ALCS trace facility, generalized
trace facility, and SLC link trace.
transaction. The entirety of a basic activity in an
application. A simple transaction can require a single
input and output message pair. A more complex
transaction (such as making a passenger reservation)
requires a series of input and output messages.
Transaction Processing Facility (TPF). An IBM
licensed program with many similarities to ALCS. It
runs native on IBM System/370 machines, without any
intervening software (such as MVS). TPF supports only
applications that conform to the TPF interface. In this
book, TPF means Airline Control Program (ACP), as
well as all versions of TPF.
Transaction Processing Facility Database Facility
(TPFDF). An IBM licensed program that provides
database management facilities for programs that run in
an ALCS or TPF environment.
Transaction Processing Facility/MVS (TPF/MVS).
Alternative name for ALCS V2.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Transaction program identifier (TP_ID). A unique
8-character token that APPC/MVS assigns to each
instance of a transaction program. When multiple
instances of a transaction program are running
sumultaneously, they have the same transaction
program name, but each has a unique TP_ID.
transaction scheduler name. The name of an
APPC/MVS scheduler program. The ALCS transaction
scheduler name is ALCSx000, where x is the ALCS
system identifier as defined during ALCS generation.
transfer vector. An ALCS application program written
in assembler, SabreTalk, or C, can have multiple entry
points for dynamic program linkage. These entry points
are called transfer vectors. Each transfer vector has a
separate program name.
type. See record type.
Type A traffic. ATA/IATA conversational traffic – that
is, high-priority low-integrity traffic transmitted across an
SLC or AX.25 link.
Type B application-to-application program
(BATAP). In any system (such as ALCS) that
communicates with SITA using AX.25, this is the
program which receives and transmits type B
messages.
Type B traffic. ATA/IATA conventional traffic – that is,
high-integrity, low-priority traffic transmitted across an
SLC or AX.25 link.
transmission status indicator. See SLC transmission
status indicator.
type 1 pool file dispense mechanism. The
mechanism used in ALCS prior to V2 Release 1.3 (and
still available in V2 Release 1.3) to dispense both
short-term and long-term pool-file records.
transmission sequence number. See SLC
transmission sequence number.
type 1 storage unit. Prime or overflow storage unit for
entry storage. See storage unit.
trigger event. In message queuing, an event (such as
a message arriving on a queue) that causes a queue
manager to create a trigger message on an initiation
queue.
type 2 pool file dispense mechanisms. The
mechanisms available in ALCS V2 Release 1.3 to
dispense pool-file records (the mechanisms are different
for short-term and long-term pool-file records).
trigger message. In message queuing, a message
that contains information about the program that a
trigger monitor is to start.
trigger monitor. In message queuing, a
continuously-running application that serves one or
more initiation queues. When a trigger message arrives
on an initiation queue, the trigger monitor retrieves the
message. When ALCS acts as a trigger monitor, it
uses the information in the trigger message to start an
ALCS application that serves the queue on which a
trigger event occurred.
IBM recommends users to migrate to type 2 dispense
mechanisms as part of their migration process.
type 2 storage unit. High-level language storage unit
for heap and stack storage. See storage unit.
U
unit of recovery. A recoverable sequence of
operations within a single resource manager (such as
MQSeries for OS/390 or DATABASE 2). Compare with
unit of work.
triggering. In message queuing, a facility that allows a
queue manager to start an application automatically
when predetermined conditions are met.
unit of work. A recoverable sequence of operations
performed by an application between two points of
consistency. Compare with unit of recovery.
TSI exhaustion. The condition of an SLC channel
when a sender cannot transmit another SLC link data
block (LDB) because the maximum number of
unacknowledged LDBs has been reached. The sender
must wait for acknowledgement of at least one LDB so
that it can transmit further LDBs. See also SLC
channel, SLC link data block, SLC transmission
sequence number, and SLC transmission status
indicator.
Universal Communications Test Facility (UCTF). An
application used by SITA for SLC protocol acceptance
testing.
two-phase commit. A protocol for the coordination of
changes to recoverable resources when more than one
resource manager is used by a single transaction.
Contrast with single-phase commit.
update log. See ALCS update log.
user data-collection area. An optional extension to
the data-collection area in the ECB. Application
programs can use the DCLAC macro to update or read
the user data-collection area.
user exit. A point in an IBM-supplied program at which
a user exit routine can be given control.
Glossary
463
user exit routine. A user-written routine that receives
control at predefined user exit points. User exit routines
can be written in assembler or a high-level language.
address X.25 PVC resources by converting the unique
SLN of a virtual SLC link to the CRI of its associated
X.25 PVC.
V
W
version number. In ALCS and TPF, two characters
(not necessarily numeric), optionally used to distinguish
between different versions of a program. Sometimes
also used with other application components such as
macro definitions.
wide character. A character whose range of values
can represent distinct codes for all members of the
largest extended character set specified among the
supporting locales. For the OS/390 C compiler, the
character set is DBCS, and the value is 2 bytes.
virtual file access (VFA). An ALCS caching facility for
reducing DASD I/O. Records are read into a buffer,
and subsequent reads of the same record are satisfied
from the buffer. Output records are written to the
buffer, either to be written to DASD – immediately or at
a later time – or to be discarded when they are no
longer useful.
Workstation trace.. One mode of operation of the
ALCS trace facility. Workstation trace controls the
remote debugger facility. The remote debugger is a
source level debugger for C/C++ application programs.
virtual SLC link. Used to address an X.25 PVC
resource for transmitting and receiving Type B traffic.
Some applications (such as IPARS MESW) address
communication resources using a symbolic line number
(SLN) instead of a CRI. These applications can
464
World Trade Teletypewriter (WTTY). Start-stop
telegraph terminals that ALCS supports through
Network Terminal Option (NTO).
Z
Z message. See ALCS command.
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
Index
Special Characters
<c$amsg.h> 338
<c$cm1cm.h> 339
<c$coic.h> 340
<c$decb.h> 342
<c$ebeb.h> 342
<c$globz.h> 342
<c$rcpl.h> 342
<c$stdhd.> 345
<tpfapi.h> 346
<tpfeq.h> 347
<tpfglbl.h> 349
<tpfio.h> 349
<tpftape.h> 350
A
AAA hold 193
AAA, agents assembly area
data-gathering transactions 3
hold, terminal hold facility 4
records in VFA 34
abbreviations, list of 440
acronyms, list of 440
ADSTOP trace command 182
agent set 68
ALCS
how it processes a message 69
operating environment 67
overview 67
what it provides 67
ALCS data collection facility
general description 244
ALCS diagnostic file processor 165
ALCS entry dispatcher
general description 44
ALCS entry dispatcher work lists
defer 44
deferred IOCB 44
delay 44
general description 44
input 44
IOCB 44
schematic format of 45
system error dump example 231
ALCS resources
See resources
algorithm-based addressing
file addresses 30
alignment, boundary
data macros, converting 336
allocatable pool
general description 27
AMSG message format 338
ANYSTOP trace command 183
APARS 247
API functions 351
APPC
entry management 51
application global area 49
serializing access to
by block-concurrent referencing 91
for compatibility with loosely coupled systems
using CS and CDS 92
using global 95
using resource hold 93
using SHR and XCL 93
using SYNCC 95
sharing access to 91, 92, 93
system error dump example 233
updating
by block-concurrent referencing 91
in a multiprocessing environment 90
in a multiprogramming environment 90
in a uniprocessing environment 91, 94
using CS and CDS 92
using resource hold 93
using SHR and XCL 93
application loop timeout 46
application processes, SQL threads 52
application program load modules
loading 240
application programs
associated with a particular entry
system error dump example 226
control tables 230
CPI-C and APPC 52
loading 236
logic errors 159
MQI 52
performance 245
reentrancy requirements 74
reentrant 10
sharing data between 91
TCP/IP 53
testing 236, 240
transferring data between 22
writing one-off 236
asynchronus
trace 181
ATTAC 250
attac C function 135
Index
95
465
attac_ext function 353
attac_id function 355
authorization 3
automatically-allocated storage
132, 134
B
backout 117
backward chain 84
BEGIN macro
parameters of 93
block list descriptors
system error dump example 231
block sizes 74
boundary alignment
data macros, converting 336
BRANCH trace command 178, 184
C
C language functions
for entry management 64
for global area processing 66
for program linkage 66
for sequential file processing 62
global 95
waitc 47
C programs
function names 333
load modules 332
source module 332
structure 332
calculating the file address of
a fixed file record from a record type symbol 404
a fixed file record from a record type value 404
a general data set record 373
callable services 323
list of services 427
UCNTINC 428
UCOMCHG 429
UCOMGET 429
UDISP 434
UDLEVGET 432
UDLEVREL 433
UDLEVVAL 433
calling assembler programs with different names 334
canned messages 5
catastrophic system errors 218
CE1CCn 128
CE1CRn 128
CE1CTn 128
CE1FA0 – CE1FAF 127
CE1FXn 127
ce1out 128
CE1SUD 153
466
CE1SUG 141, 153
CE1USA
general description 11
CE1WKA 125
CE1WKB 125
chain chasing 78
chaining 77
chains
backward 20
fields in header 34
forward 19
standard 19
CISIZE 7
cm1cm message format 339
COMCC
fields and bits 422
commands
SLIP 206
SMP/E 248
commit and backout 117
services 118
communication 80
between entries 48
macros for 60
communication network
simulating 240
communication resource identifier (CRI) 81, 128
communication resource name (CRN) 81
communication tables
system error dump example 225
compatibility
with TPF 324
compiling and link editing C programs 332
computer room agent set (CRAS) 68
configuration testing 240
contention 89
control
loss of 148
loss of by entries 46
control byte 34, 83
control interval, (VSAM) 7
conversational trace
activating 171
running 176
corrective service, applying 246
CPDMP 423
CPI-C calls
entry management 51
CPU loop
See ALCS entry dispatcher
CRAS 68
create-type macros 178
CRET table
system error dump example 228
CRI
in input messages 42
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
CRUSA 252
crusa function 357
CTKB
system error dump example
cursor
SQL 52
228
D
DASD
file address 82
input and output 82
record sizes 75
DASD processing
macros for 61
DASD records 75
fixed file 75
general file 75
pool file 75
reading 84, 86, 271, 274, 279, 281, 284
standard header format for 33
writing 84, 86, 263, 265, 269
data
sharing
between entries 49
data collection 244
general description 13
data collection area 132
data event control block
See DECB
data gathering transactions 3
data in ALCS 82
data levels 127
See also ECB levels
data levels and storage levels 127
data sets
creating 40
DASD 40
DASD configuration 40
general description 15
spill
See spill data sets
updating 41
databases
duplicating 16
extending 35
organizing 16
real-time
See real-time database (ALCS)
reorganizing 35
test
See test databases
testing
See test database facility
DCLAC macro 132
DECB 75, 76, 82, 84, 127, 134, 136, 342
4x4 format file address 76, 82, 84, 139
8-byte file address 76, 82, 84, 138, 139
accessing DASD records 140
accessing in programs 141
creating 394
data level fields 138
DECB management functions
tpf_decb_create 394
tpf_decb_locate 396
tpf_decb_release 398
tpf_decb_swapblk 400
tpf_decb_validate 402
error handling 141
error indicator 152
fields 137
format 136
functional flow 142
general description 13
locating 396
management 254
managing 138, 139
releasing 398
storage level fields 137
swapping storage block with 400
symbolic name 139
using storage blocks 140
validating 402
DECB application areas
system error dump example 224
DECB descriptor
system error dump example 223
DECB fields
referencing 303
DECB level 137
DECBC 254, 424
DECBC macro 138
defer list 44
defer/delay loops 48
deferred IOCB list 44
Defining structures 336
delay and defer processing 47
delay list 44
designing databases for use with ALCS 111
DETAC 257
detac C function 135
detac_ext function 359
detac_id function 361
detail trace command 186
diagnostic facilities
ALCS 209
MVS 204
diagnostic file 243
tracing programs to 165
writing TCP/IP error messages 243
Index
467
diagnostics 146
direct access files 82
directly-addressable global records 102
dispatching
See entry dispatching
dispensing pool-file records 77
DISPLAY trace command 187
double-byte character set 341
dual copy facility
using 16
dumps
analyzing 208
CTL-type 217
formatting 208
manual 217
MVS 205
OPR-type 217
duplex databases
reading from 277
writing to 267
duplicate databases 16
DXCCDDLD 121
DXCFARIC 121
DXCMRT 121
DXCPKEY 424
DXCSAVE 425
DXCSTC
STC
See system test compiler
dynamic program load facility 240
E
EB0EB 10
EBEB DSECT 131
EBCFAn 127
EBCIDn 127
EBCM01 125
EBCM02 125
EBCM03 125
EBCRCn 127
EBCSDn 152
EBER01 125
ebrout 128
EBRS01 125
EBSW01 125
EBSW02 125
EBSW03 125
EBXSW0 – EBXSW7 125
ECB 123, 127, 342
addressing 131
C function to access 131
data level fields 127
displaying 188
Entry origin fields 128
error indicators 130, 152
468
ECB (continued)
format 10, 123
general description 10
local program work area 123
reserved areas 131
routing control parameter list (RCPL) 130
system error dump example 225
TCP/IP socket descriptor 130
user area reserved for system-wide fields 130
user data collection area 132
user register save area 128
work areas 1 and 2 125
ECB descriptor
system error dump example 223
ECB fields
installation-wide 11
referencing 259, 261, 304
user-defined 11
ECB levels
data 13
storage 12
testing 305
ECB prefix
system error dump example 224
ECB-controlled programs 74, 121, 334
ecbptr macro 131
entries 69
cancelling 46
communication between 48
creating 42
using an existing entry 49
dispatching
See entry dispatching
exiting 46
monitor-created 43
multiple
See multiple entries
processing 9
running under MVS tasks 9
serializing 14, 89
suspending 47
test
See test entries
entry control block (ECB) 69
data levels 127
displaying 188
entry dispatcher
See ALCS entry dispatcher
entry dispatcher work lists
See ALCS entry dispatcher work lists
entry dispatching
See also ALCS entry dispatcher
general description 44
non-preemptive 46
on a multiprocessor 45
preemptive 46
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
entry macro trace block 162
system error dump example 224
entry management
C language functions for 64
macros for 63
entry origin fields 128
entry priorities
See ALCS entry dispatcher work lists
entry processing limits
application loop timeout 46
function of 46
entry storage
general description 55
limits for 58
on exit 134
equate macros 323
error conditions 146
detected by ALCS immediately 146
detected by application programs 147
detected later by ALCS 147
error conditions in ALCS 146
error indicators 130, 141, 152
error processing 146
error recovery 159
errors
application program logic 159
dealing with 152
designing recovery routines 160
I/O
testing for 47
multiple 155
pool chain 209, 214
pool usage 209, 211
recovery from 159
sequential file 156
testing 157
testing for 153
events
system
intercepting 206
trapping 206
tracing 204
exit an entry 73
EXIT trace command 190
exits
See ECB-controlled exits
See monitor exits
external functions
providing linkage for 334
F
FA4X4C 261
FA4X4C macro
FAC8C 259
82
FAC8C macro 82
FACE
ID 17
ordinal 17
face C function 82
FACE macro 82
facs C function 82
FACS macro 82
file address 76, 82, 83, 84
4x4 format 76, 82, 139
computing an 8-byte 404
converting a 406
tracing 166, 173
unholding 364, 385, 410
file address formats
band
allocating 25
general description 24
general description 23
multiple 26
file address hold
test for 301
file addresses
calculating 291
constructing 23
general data set 291
holding 274, 281
testing 301
unholding 269, 311, 319
file_record_ext function 363
FILEC 263
FILNC 265
FILSC 267
FILUC 269
find_record function 366
FINDC 271
FINHC 274
FINSC 277
FINWC 279
FIWHC 281
fixed file
miscellaneous file records 76
fixed files 114
fixed-file record type 76
fixed-file records 75
general description 17
miscellaneous 17
flipc C function 134
FLUSH trace command 191
FNDPC 284
forward chain 83
function keys
See PF keys
function names 333
length of 334
Index
469
functions
time and date
global area (continued)
unprotected globals 107
use in C language programs 106
global area fields
locking 95
unlocking 96
updating 95
global area processing
C language functions for 66
macros for 65
global directories 102
globals
protected 108
unprotected 108
GLOBZ 426
granularity 89
group names
macros 325
GTF 204
See also MVS generalized trace facility
producing output from 205
GTF traces
analyzing 208
formatting 208
337
G
GDSNC 287
gdsnc function 370, 373
GDSRC 291
general data set records
getting file addresses of 291
general data sets 79, 80
See also general files
allocating 22
closing 287
deallocating 22
getting a file address 373
offline access 98
opening 287
opening and closing 370
general files 79
allocating 22
deallocating 22
offline access 98
general sequential files 99
assigning 99
reserving 99
services for 100
several entries using 99
general-file records 75
generalized trace facility
See MVS generalized trace facility
GETCC 293
getcc C function 133, 134
getcc function 375
GETCC macro 133
GETFC 297
getfc function 378
getfc_alt function 381
global area 79
additional ALCS services for TPF compatibility
attention when using 104
C functions for using 105, 107
global function 107
directly-addressable global records 102
directories 102
general description 101
in TPF 108
indirectly-addressable global records 103
keypointing global records 103
logical global records 103
protected globals 107
read-only access to records and fields 106
records and fields 101
serialization of access 104
serializing access 106
sharing data 49
470
H
109
header file contents and use 338
header files 335, 338
headers
for DASD records 33
heap storage 133
heap, for HLL 56
HELP trace command 192
high level languages
tracing 179
high-level language storage
general description 56
high-level languages
getting storage 132
hiperspace
cache-type 35
expanded storage only (ESO) 35
HLDTC 301
HLL
See high level languages
See remote terminal
HLL storage 56
holding a record 88
I
I/O (DASD)
services for 97
I/O completion
waiting for 279, 281
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
I/O control blocks
system error dump example 232
I/O counter 47
I/O errors
testing for 47
I/O interruptions 204
I/O messages
cm1cm message format 339
I/O services 96
summary of 150
IDECB 13, 303
IDECB DSECT 141
IDECCRW 137, 138
IDECCT0 137
IDECDAD 137
IDECDET 138
IDECDLH 137
IDECFA 138, 139
IDECFX0 138
IDECNAM 137
IDECRCC 138
IDECRID 138
IDECSUD 138, 141, 153
IDECUSR 138
IFAC8 304
implied-wait services 148
indirectly-addressable global records 103
information and error messages 243
TCP/IP error messages 243
initial storage allocation (ISA) 133
input list 44
input messages 134
input-message editor 1
installation-wide exits
for ALCS customization 422
instruction stepping 199
Interactive problem control system
See IPCS
intermediate results
storing 11
IOCB list 44
IPARS applications 81
IPCS 205, 208
ISA, initial storage allocation 56
ISPF panels
maintaining ALCS 247
ISTEP command 177, 200
J
JCL
for MVS dumps
205
K
keypointing global records
keypoints
CTKB 228
SLC 236
keys
storage protect 107
103
L
LEVTA 305
LEVTA macro 134
levtest C function 134
levtest function 383
limits
entry processing 46
entry storage 58
link trace facility
See SLC link trace facility
LISTC 307
load modules 332
local save stack 126
program 240
locks 87, 88, 89
granularity 89
logical global records 103
long-term pool file 116
long-term pool file records
error information 209, 211, 214, 216
long-term pool-file records 77
recovering 78
loosely coupled systems 105
loss of control 148, 150
lost addresses 19
LU 6.2
entry management 52
M
macro trace blocks
See system macro trace block
macro trace control area
system error dump example 229
macros
assembly 322
COMCC 422
create-type 42, 49
DECBC 424
DSECT 322
dummy 323
DXCPKEY 424
DXCSAVE 425
ENTER/BACK 66
equate 323
for communication 60
for DASD processing 61
Index
471
macros (continued)
for entry management 63
for global area processing 65
for program linkage 66
for sequential file processing 62
GLOBZ 426
group names 325, 331
IPARS 324
monitor-request 322
request types 325
send-type 43
STDHD 33
system error 43, 322
table of 325, 331
TIMEC 426
TPF 324
WTOPC 426
maintenance (ALCS) 204, 247
message
AMSG message format 338
cm1cm message format 339
message editors
input 1
output 4
message processing 69
message routing
for Z messages 1
messages 134
canned 5
response 5
routing 337
standard 5
storing information about 11
mirroring data 16
miscellaneous file records 17, 76
monitor interface area
system error dump example 232
monitor keypoint record
See CTKB
monitor work areas
system error dump example 232
monitor-request macro 162
branching round 197
request type 176
multiple entries
creating 50
multiple errors 155
multiple required-wait services 149
multiprocessing 9
multiprogramming 9
MVS
diagnostic facilities 204
dumps 205
system diagnostic work area
system error dump example 227
472
MVS generalized trace facility 204, 205
MVS generalized trace facility (GTF) 168
N
network problem determination
204
O
offline access to general files and general data sets
ordinal number 76
organizing data 114
output messages 134
output-message editor 4
overflow record 19
P
parameters
passing between programs 11
performance
application programs 245
control 243
impact of
SLC trace 237
improving 245
message mix 246
monitoring 243
MVS facilities 244
overall 244
record access mix by ID 246
record access mix by type 246
tracing 237
transaction response time 89
VFA buffers 34
VTAM facilities 244
performance and design 111
PF keys
customizing 1
pool chain errors 209, 214
pool file control tables
system error dump example 230
pool file identifier 246
pool file management
diagnostic data 209, 211, 214, 216
pool file records
dispense control tables 230
long-term
error information 209
release control tables 230
short-term
error information 213
pool files 115
pool management functions
getfc 378
getfc_alt 381
relfc 389
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
98
pool management functions (continued)
tpf_rcrfc 408
pool usage errors 209, 211, 214, 216
diagnostic file processor output for 211
examples of 209
pool-file record
dispensing 77
pool-file record addresses
getting 297
releasing 309, 315
pool-file records 75, 76
chaining 77
dispense 18
dispense rate 19
long-term 77
integrity 19
lost addresses 19
minimum requirement 19
release 18
short-term 77
post-interrupt routine 45
primary action code 2
prime record 19
priorities
See ALCS entry dispatcher work lists
problem determination 209
PROCESS trace command 193
processing
delay and defer 47
global area 65, 66
sequential file 62
program control tables
system error dump example 230
program driver facility 236
program failure 44
program linkage
macros for 66
program name in header 34
program stamp 83
program status word
See PSW
programming rules 334, 335
programs
CPI-C and APPC 52
MQI 52
TCP/IP 53
protect keys 107
protected globals
accessing 108
PSW
areas addressed by
system error dump example 222
PSW key
changing 108
restoring 108
PTF
247
R
random access files 17
RBA, relative byte address 30, 31
RCC, record code check 33
RCPL 130, 337, 342
RCRFC 309
RCUNC 311
rcunc function 385
reading and writing DASD records 84, 86
real-time database (ALCS)
accessing records on 16
general description 16
real-time sequential files 99
recommendations when creating header files
record
standard header 83
record classes 17, 114
record code check 83
See also RCC
record control fields 284
record headers 33
record hold 88
record hold facility
different file address formats 27
record ID 33, 83
record locks 88
record type/ordinal
tracing 166, 173
record types
adding 35
records
adding 35
addressing 23
chained
checking for errors in 216
releasing 216
chaining 19
DASD
See DASD records
general data set 287
how ALCS stores them 7
logical, VSAM and ALCS 7
reading 34
referencing 23
writing 34
Recoup
progress information 209
Recoup program 78
recovering long-term pool-file records 78
recovery from wait-completion errors 158
reentrant program requirements 334
reentrant programs 74
necessity for 10
335
Index
473
REFSTOP trace command 194
register labels
floating-point 129
general 128
registers
areas addressed by
system error dump example 222
general
saving contents of 129
system error dump example 221
REGSTOP trace command 195
RELCC 313
relcc function 387
RELCC macro 134
releasing a pool-file record address 389, 408
releasing a storage block 357, 385, 387, 408
RELFC 315
relfc function 389
remote terminal
tracing 180
request types 323
required-wait services 149
resource hold 105
resource hold table
system error dump example 228
resources
entry use of 13
forcing exclusive access to 14, 89
response messages 5
RLCHA monitor request macro 216
routing 1
routing control parameter list (RCPL) 337
routing of messages 337
S
sample applications
SAVEC macro 136
scrolling 5
secondary action code 2
self-modifying code (not allowed) 334
sending messages 337
sequential file errors 156
sequential file processing
C language functions for 62
macros for 62
sequential files 80, 87, 98
general 99
real-time 99
services for processing 101
system 99
sequential update technique 118, 119
serialization 87
SERRC macro 43
serviceability level indication processing
See SLIP
474
services
that include an implied wait 148
services for DASD processing 96, 97
services for managing DECBs 139
SET trace command 196
sharing data
between entries 49
short-term pool file 115
short-term pool file records
error information 213
short-term pool-file records 77
SHR parameter
single-phase commit 117
SKIP trace command 178
SLC channels
keypoints for
system error dump example 236
SLC link trace facility
activating 237
deactivating 237
general description 237
SLC links
keypoints for
system error dump example 236
SLC network
monitoring 237
SLIP 206
SMP/E commands 248
software failures
diagnosing 208
SONIC 317
sonic function 391
source module 332
spill data sets
example of use of 35
SQL
entry management 51
SQL calls 109, 111
coding in application programs 110, 111
SQL communication area (SQLCA) 110
SQL descriptor area (SQLDA) 110
SQLCA 110
SQLDA 110
SQLDSECT 110
stack storage 133
stack, for HLL 56
standard headers 33
standard messages 5
standard record header 83
STC
See system test compiler
STDHD macro 33
STEP trace command 200
storage
automatic allocation to entries 134
entry 55
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
storage (continued)
for C language programs
heap 57
for high-level languages 56
initial allocation, (ISA) 56
unprotected
See unprotected storage
storage areas
user-requested
system error dump example 236
storage block 338, 339, 340, 353, 357, 359, 361, 375,
385, 387, 400, 408
storage blocks 133
activity control 135
automatic 12
C functions for handling 135
detached 12
detaching
temporarily 257
detaching and attaching 135
detail 186
displaying 184
getting 293
obtaining 12
reattaching
to an ECB 250
releasing 311, 313
conditionally 252
from a specified level 309
system error dump example 226
storage level
testing 383
storage levels 128
See also ECB levels
fields 128
swapping 134
storage management
C language functions for 64
macros for 64
storage protect keys 107
storage units
block list descriptor
system error dump example 222
contents of
system error dump example 233
summary of
system error dump example 234
striping
balancing the distribution 16
structure of C programs 332
SVC
interruptions 204
SWAP trace command 203
SXIPC 179, 190
symbolic file address 391
symbols
defining 304
SYNCC macro 95
synchpoint manager
reasons for non-provision in ALCS 120
SYSMODS
applying 247
SYSRA macro 43
system diagnostic work area
example of error dump 227
system error dumps
ALCS entry dispatcher work lists 231
application global area 233
application programs associated with an entry
areas addressed by general registers 222
areas addressed by PSW 222
block list descriptors 231
communication table 225
control (CTL) 217
CRET table 228
CTKB 228
DECB application areas 224
DECB descriptor 223
ECB 225
ECB descriptor 223
ECB prefix 224
entry macro trace block 224
entry storage 233
entry summary 234
format of 218
I/O control blocks 232
macro trace control area 229
manual 217
monitor interface area 232
monitor work areas 232
MVS system diagnostic work area 227
operational (OPR) 217
pool file control tables 230
producing 217
program control tables 230
registers 221
resource hold table 228
SLC link and channel keypoints 236
storage blocks associated with an entry 226
storage unit block list descriptor 222
system macro trace block 227
user storage list items 227
user-defined areas 236
VFA buffer headers 235
VFA buffers 236
VFA control areas 235
system error macros
SERRC 43
SYSRA 43
system error options 218
Index
226
475
system errors
catastrophic 218
system events
See events
system macro trace block 162
displaying contents 164
system error dump example 227
system problems
diagnosing 204
system sequential files 99
system test compiler
test unit data sets 241
system test vehicle
general description 240
system tests 240
T
table-based addressing
file addresses 31
tables
CRET 228
pool file control 230
program control 230
resource hold 228
VFA control 235
TAS 43
tasnc C function 147
TASNC macro 147
TCP/IP 130
terminal hold 193
terminal hold facility 4
test a storage level 383
test database facility 36
test databases
sharing 38
test entries 240
test facilities
dynamic program load 240
STC 240
STV 240
test programs
altering 196
threads, SQL 52
tightly coupled systems 105
time and date functions 337
time available supervisor
See TAS
TIMEC 426
timeout
application loop
See application loop timeout
tokens
allocating 94
allocating resources to 95
defining 95
476
tpf_decb_create C function 138
tpf_decb_create function 394
tpf_decb_locate C function 139
tpf_decb_locate function 396
tpf_decb_release C function 138
tpf_decb_release function 398
tpf_decb_swapblk function 400
tpf_decb_validate function 402
tpf_fa4x4c C function 82
tpf_fa4x4c function 406
tpf_fac8c C function 82
tpf_fac8c function 404
tpf_rcrfc function 408
TPF_regs 348
TPFDF 113, 114
application portability 8
extended record header 33
TPFDF macro trace
activating 170
trace
asynchronous 181
trace control parameters 165, 172
tracing 162
address stop locations 182
branching past instruction 199
branching to address 184
conversational 163, 171
create-type macros 178
display internal tpfdf macro 186
displaying help information 192
displaying storage areas 187
events 204
EXITC 179
exiting current entry 190
flushing current entry 191
general description of 162
GTF 168
high level languages 179
processing message during 193
reference-stop locations 194
register-stop locations 195
remote terminal 180
remote terminals 171
restricting scope of 165
setting register contents 196
setting storage contents 196
skipping next instruction 199
starting instruction stepping 200
stopping instruction stepping 200
swapping current entry 203
system errors 178
to a terminal 237
to the ALCS diagnostic file 163, 165
to the system macro trace block 164
TPFDF macro trace 170
tracing control options 183
ALCS 2.2.1 Documentation Changes for Data Event Control Block (DECB) Support
tracing (continued)
workstation 169
transaction log 118
transaction programs
CPI-C and APPC 52
MQI 52
TCP/IP 53
transferring control to another program
trap pages 58
two-phase commit 117
virtual file access (VFA) 80
VSAM control interval 7
W
72
U
UCNTINC 428
UCOMCHG 429
UCOMGET 429
UDISP 434
UDLEVGET 432
UDLEVREL 433
UDLEVVAL 433
UNFRC 319
unfrc_ext function 410
unit of recovery
SQL 52
unprotected storage
application global area 49, 90
UNSTEP command 177, 200
updating DASD
recommanded technique 118, 119
usage errors 214
user data collection area 132
user exits
See installation-wide exits
user storage list items
system error dump example 227
using globals – attention 104
using information from previous messages 73
USRFAR exit, user file-address format 27
Utility programs 121
wait mechanism 148
wait service 47
See also no-wait wait service
wait-completion errors
recovery from 158
work areas for application programs
working storage
block sizes 74
obtaining 74
workstation trace, activating 169
write
check completion of 265
WTOPC 426
124, 125
X
XCL parameter
Z
Z messages
routing messages starting with Z 1
ZAACV 245
ZDASD, allocating and deallocating data sets
ZDASD, load the configuration data set 41
ZDCLR 244
ZDRIV 236
ZLKTR 237
ZTRAC 162
22
V
VFA 16
general description 34
VFA buffer headers
system error dump example 235
VFA buffers
performance benefits 34
system error dump example 236
VFA control areas
system error dump example 235
VFA options
description of 35
VFAOPT, VFA options parameter 35
virtual file access
See VFA
Index
477
IBM
Program Number: 5695-068
Printed in Denmark by IBM Danmark A/S
SH19-6742-6