IN FOCUSEnterprise Server Dumps: A/B Datasets, and casdump /d for a Region That Will Not Respond
Enterprise Server writes system and transaction dumps to a toggleable A or B dataset, but a hung region with locked shared memory needs the external casdump /d command, which skips the lock and writes to a separate X dataset. [1] [4]
Read the full briefing
Scope and reading taken: Rocket Enterprise Developer / Enterprise Server 12.0 for Linux/UNIX (documentation bundle enterprisedevelopereclux_ug_120). This is an unattended scheduled run, so I picked the Diagnostics angle of dump handling that the recent editions have not covered (they covered PLIDUMP, CTF and security tracing, not region dumps).
Four kinds of dump, and where they land
Enterprise Server can produce several kinds of dump, and the Dumps page separates them by where the failure originates:
- System dump: created when the failure originates with Enterprise Server itself.
- Transaction dump: created when the failure originates in a program running on the region.
- Core dump: created when either a system or a transaction failure occurs, and usable to debug the application.
- casdump: a dump created externally with the
casdumpcommand, for when a dump cannot be obtained normally.
System and transaction dumps can be written to either an A or a B dataset. The default is A, and you can toggle between the two. With the exception of core dumps, the output files go to the Enterprise Server system directory:
casdumpa.rec: output for the A dataset.casdumpb.rec: output for the B dataset.casdumx.rec: output for thecasdump /dexternal command.
Core dump files are different. You choose their filename and directory when you configure the region to produce core dumps.
A small documentation wrinkle is worth knowing. The Dumps page names the external-command file casdumx.rec, while the ESCWA dump-viewing page (below) names it casdumpx.rec. If you go looking for it, check the system directory for both spellings.
Dump on stop, and switching datasets in ESCWA
You can ask for a system dump as you stop a region. According to To initiate a system dump on stop server, while the region is in Start mode you open ESCWA, select the region, go to Monitor > Control, check Dump, and click STOP. The files are written to the system directory as casdumpn.rec, where n is a or b depending on the dataset currently selected. The same page documents SWITCH DUMP SET: if the dataset is A it switches to B, and if it is B it switches to A. Using it before a new capture is a way to avoid mixing a fresh dump into the dataset that holds an earlier one.
Reading dumps in ESCWA
To view a dump file in ESCWA goes through Monitor > Logs > Dumps while the region is in Start mode. The optional LEVEL control sets how much is displayed, and each level includes all lower levels:
0: service start, module start, module end, service end.1: Enterprise Server API entries and exits.2: subsystem trace entries.3: all entries where some formatting of the data is possible.4: all trace entries. This is the default.
The page adds that local trace tables (traces for SEPs) only have levels 0 and 1. It also notes that the X dataset holds dumps triggered by casdump /d.
When the region will not answer: casdump
The casdump command "forces a system dump" from outside the region. Its syntax is:
casdump [/res-name]
[/d]
[/f]
[/i]
[/b]
[/udump-code]The parameters are:
/res-name: the name of the enterprise server to dump. It defaults to ESDEMO./d: do not lock shared memory./f: dump the FAQE chain./i: trigger an IMS TM dump./b: dump shared memory as a block./udump-code: set the dump code for the dump.
On UNIX you can use a dash (-) before a parameter instead of a forward slash.
The /d flag is the one that matters for a hung region. The Dumps page gives the scenario directly: use casdump when a dump cannot be obtained normally, for example when the region is not responding and shared memory is locked. Telling casdump not to lock shared memory lets it proceed in that situation, and the result goes to the separate X dataset so it does not collide with the A/B files.
An example for a region named MYREGION (the name is a placeholder, and the invocation follows the documented syntax; I did not run it):
casdump -rMYREGION -dPrerequisites and limits
- The enterprise server named with
/rmust have been started first. - You must run
casdumpunder the same user ID as the enterprise server. The casdump page warns that if the Directory Server was started as a system service and the region was started from the Administration interface, the region is probably running under the LOCAL_SYSTEM user ID, and the command will not work. /dand/icannot be used at the same time, so you cannot combine a no-lock dump with an IMS TM dump in one command.
Make sure there is something to read
The Minimum Diagnostic Configuration Recommendations for Production Systems page recommends configuring each region, development or production, with Dump on System Abend (so a dump is produced if one of its own processes, such as a SEP, terminates abnormally), Auxiliary Trace Active, and core dumps. Both of the first two are set in ESCWA under Operation > Directory Servers > Default, then the region, then General > Diagnostics. The page warns that auxiliary tracing can grow very large very quickly and can affect performance, and suggests combining it with Maximum Diagnostics File Size on busy systems.
Takeaway
Decide your dump path before the incident. Turn on Dump on System Abend, know whether A or B is current, and remember that for a hung region the documented route is casdump with /d run as the region's own user, with the output in the X dataset.