Document revision date: 19 July 1999

Displays the contents of the shared logical name tables in the system.

Format

CLUE SYSTEM /LOGICAL

Parameters

None.

Qualifier

/LOGICAL

Displays all the shared logical names.

Description

The CLUE SYSTEM/LOGICAL command displays the contents of the shared logical name tables in the system.

Example

SDA>CLUE SYSTEM/LOGICAL
Shareable Logical Names: 
------------------------ 
   "XMICONBMSEARCHPATH" = "CDE$HOME_DEFAULTS:[ICONS]%B%M.BM" 
   "MTHRTL_TV" = "MTHRTL_D53_TV" 
   "SMGSHR_TV" = "SMGSHR" 
   "DECW$DEFAULT_KEYBOARD_MAP" = "NORTH_AMERICAN_LK401AA" 
   "CONVSHR_TV" = "CONVSHR" 
   "XDPS$INCLUDE" = "SYS$SYSROOT:[XDPS$INCLUDE]" 
   "DECW$SYSTEM_DEFAULTS" = "SYS$SYSROOT:[DECW$DEFAULTS.USER]" 
   "SYS$PS_FONT_METRICS" = "SYS$SYSROOT:[SYSFONT.PS_FONT_METRICS.USER]" 
   "SYS$TIMEZONE_NAME" = "???" 
   "STARTUP$STARTUP_VMS" = "SYS$STARTUP:VMS$VMS.DAT" 
   "PASMSG" = "PAS$MSG" 
   "UCX$HOST" = "SYS$COMMON:[SYSEXE]UCX$HOST.DAT;1" 
   "SYS$SYLOGIN" = "SYS$MANAGER:SYLOGIN" 
   "DNS$SYSTEM" = "DNS$SYSTEM_TABLE" 
   "IPC$ACP_ERRMBX" = "d.Ú." 
   "CDE$DETACHED_LOGICALS" = "DECW$DISPLAY,LANG" 
   "DECW$SERVER_SCREENS" = "GXA0" 
   "DNS$_COTOAD_MBX" = "ä<â." 
   "DNS$LOGICAL" = "DNS$SYSTEM" 
   "OSIT$MAILBOX" = "äAë." 
   "XNL$SHR_TV" = "XNL$SHR_TV_SUPPORT.EXE" 
   "MOM$SYSTEM" = "SYS$SYSROOT:[MOM$SYSTEM]" 
   "MOP$LOAD" = "SYS$SYSROOT:<MOM$SYSTEM>" 
   .
   .
   .
      

Displays virtual I/O cache-related information.

Format

CLUE VCC [/qualifier[,...]]

Parameters

None.

Qualifiers

/CACHE

Decodes and displays the cache lines that are used to correlate the file virtual block numbers (VBNs) with the memory used for caching. Note that the cache itself is not dumped in a selective dump. Use of this qualifier with a selective dump produces the following message:

%CLUE-I-VCCNOCAC, Cache space not dumped because DUMPSTYLE is selective

/LIMBO

Walks through the limbo queue (LRU order) and displays information for the cached file header control blocks (FCBs).

/STATISTIC

Displays statistical and performance information related to the virtual I/O cache.

/VOLUME

Decodes and displays the cache volume control blocks (CVCB).

Examples

SDA> CLUE VCC/STATISTIC
Virtual I/O Cache Statistics:
-----------------------------
Cache State       pak,on,img,data,enabled
Cache Flags       on,protocol_only
Cache Data Area   80855200
Total Size (pages)              400     Total Size (MBytes)               3.1 MB
Free Size (pages)                 0     Free Size (MBytes)                0.0 MB
Read I/O Count                34243     Read I/O Bypassing Cache       3149
Read Hit Count                15910     Read Hit Rate                    46.4%
Write I/O Count                4040     Write I/O Bypassing Cache       856
IOpost PID Action Rtns        40829     IOpost Physical I/O Count        28
IOpost Virtual I/O Count          0     IOpost Logical I/O Count          7
Read I/O past File HWM          124     Cache Id Mismatches              44
Count of Cache Block Hits       170     Files Retained                  100
Cache Line LRU    82B11220 82B11620     Oldest Cache Line Time     00001B6E
Limbo LRU Queue   80A97E3C 80A98B3C     Oldest Limbo Queue Time    00001B6F
Cache VCB Queue   8094DE80 809AA000     System Uptime (seconds)    00001BB0
 
      

SDA> CLUE VCC/VOLUME
Virtual I/O Cache - Cache VCB Queue:
------------------------------------
CacheVCB RealVCB   LockID      IRP Queue     CID  LKSB Ocnt State
-------- -------- -------- ----------------- ---- ---- ---- ---------------
8094DE80 80A7E440 020007B2 8094DEBC 8094DEBC 0000 0001 0002 on
809F3FC0 809F97C0 0100022D 809F3FFC 809F3FFC 0000 0001 0002 on 
809D0240 809F7A40 01000227 809D027C 809D027C 0000 0001 0002 on
80978B80 809F6C00 01000221 80978BBC 80978BBC 0000 0001 0002 on
809AA000 809A9780 01000005 809AA83C 809AA03C 0007 0001 0002 on 
 
      

SDA> CLUE VCC/LIMBO
Virtual I/O Cache - Limbo Queue:
--------------------------------
  CFCB     CVCB     FCB      CFCB   IOerrors   FID (hex)
-------- -------- -------- -Status- -------- --------------
80A97DC0 809AA000 80A45100 00000200 00000000 (076B,0001,00)
80A4E440 809AA000 809CD040 00000200 00000000 (0767,0001,00)
80A63640 809AA000 809FAE80 00000200 00000000 (0138,0001,00)
80AA2540 80978B80 80A48140 00000200 00000000 (0AA5,0014,00)
80A45600 809AA000 80A3AC00 00000200 00000000 (0C50,0001,00)
80A085C0 809AA000 809FA140 00000200 00000000 (0C51,0001,00)
80A69800 809AA000 809FBA00 00000200 00000000 (0C52,0001,00)
80951000 809AA000 80A3F140 00000200 00000000 (0C53,0001,00)
80A3E580 809AA000 80A11A40 00000200 00000000 (0C54,0001,00)
80A67F80 809AA000 80978F00 00000200 00000000 (0C55,0001,00)
809D30C0 809AA000 809F4CC0 00000200 00000000 (0C56,0001,00)
809D4B80 809AA000 8093E540 00000200 00000000 (0C57,0001,00)
[......]
80A81600 809AA000 8094B2C0 00000200 00000000 (0C5D,0001,00)
80AA3FC0 809AA000 80A2DEC0 00000200 00000000 (07EA,000A,00)
80A98AC0 809AA000 8093C640 00000200 00000000 (0C63,0001,00)
 
      

SDA> CLUE VCC/CACHE
 
Virtual I/O Cache - Cache Lines: 
-------------------------------- 
   CL       VA      CVCB     CFCB     FCB      CFCB   IOerrors   FID (hex) 
-------- -------- -------- -------- -------- -Status- -------- ------------ 
82B11200 82880000 809D0240 809D7000 80A01100 00000200 00000000 (006E,0003,00) 
82B15740 82AAA000 809AA000 80A07A00 80A24240 00000000 00000000 (0765,0001,00) 
82B14EC0 82A66000 809AA000 80A45600 80A3AC00 00000200 00000000 (0C50,0001,00) 
82B12640 82922000 809D0240 809D7000 80A01100 00000200 00000000 (006E,0003,00) 
82B123C0 8290E000 809AA000 80A45600 80A3AC00 00000200 00000000 (0C50,0001,00) 
82B13380 8298C000 809D0240 809D7000 80A01100 00000200 00000000 (006E,0003,00) 
82B15A40 82AC2000 809AA000 80A45600 80A3AC00 00000200 00000000 (0C50,0001,00) 
82B15F40 82AEA000 809D0240 809D7000 80A01100 00000200 00000000 (006E,0003,00) 
82B12AC0 82946000 809D0240 809D7000 80A01100 00000200 00000000 (006E,0003,00) 
82B12900 82938000 809D0240 809D7000 80A01100 00000200 00000000 (006E,0003,00) 
82B10280 82804000 809AA000 80A45600 80A3AC00 00000200 00000000 (0C50,0001,00) 
82B122C0 82906000 809AA000 80A1AC00 80A48000 00000000 00000000 (0164,0001,00) 
82B14700 82A28000 809AA000 809FFEC0 809F8DC0 00000004 00000000 (07B8,0001,00) 
82B11400 82890000 809AA000 80A113C0 80A11840 00000000 00000000 (00AF,0001,00) 
[......] 
82B11380 8288C000 809AA000 809DA0C0 809C99C0 00002000 00000000 (00AB,0001,00) 
82B130C0 82976000 809AA000 809DA0C0 809C99C0 00002000 00000000 (00AB,0001,00) 
82B11600 828A0000 809AA000 809DA0C0 809C99C0 00002000 00000000 (00AB,0001,00) 
 
 
 
      

Displays XQP-related information.

Format

CLUE XQP [/qualifier[,...]]

Parameters

None.

Qualifiers

/ACTIVE [/FULL]

Displays all active XQP processes.

/AQB

Displays any current I/O request packets (IRPs) waiting at the interlocked queue.

/BFRD=index

Displays the buffer descriptor (BFRD) referenced by the index specified. The index is identical to the hash value.

/BFRL=index

Displays the buffer lock block descriptor (BFRL) referenced by the index specified. The index is identical to the hash value.

/BUFFER=(n,m) [/FULL]

Displays the BFRDs for a given pool. Specify either 0, 1, 2 or 3, or a combination of these in the parameter list.

/CACHE_HEADER

Displays the block buffer cache header.

/FCB=address [/FULL]

Displays all file header control blocks (FCBs) with a nonzero DIRINDX for a given volume. If no address is specified, the current volume of the current process is used.

The address specified can also be either a valid volume control block (VCB), unit control block (UCB), or window control block (WCB) address.

/FILE=address

Decodes and displays file header (FCB), window (WCB), and cache information for a given file. The file can be identified by either its FCB or WCB address.

/GLOBAL

Displays the global XQP area for a given process.

/LBN_HASH=lbn

Calculates and displays the hash value for a given logical block number (LBN).

/LIMBO

Searches through the limbo queue and displays FCB information from available, but unused file headers.

/LOCK

Displays all file system serialization, arbitration, and cache locks found for the specified lockbasis.

Format

/LOCK=lockbasis

/THREAD=n

/VALIDATE=(n,m)

Description

The CLUE XQP command displays XQP information. XQP is part of the I/O subsystem.

Examples

SDA> CLUE XQP/CACHE_HEADER
Block Buffer Cache Header: 
-------------------------- 
Cache_Header   8437DF90    BFRcnt         000005D2    FreeBFRL       843916A0 
Bufbase        8439B400    BFRDbase       8437E080    BFRLbase       8438F7E0 
Bufsize        000BA400    LBNhashtbl     84398390    BFRLhashtbl    84399BC8 
Realsize       000D78A0    LBNhashcnt     0000060E    BFRLhashcnt    0000060E 
 
Pool           #0          #1          #2          #3 
Pool_LRU       8437E5C0    84385F40    84387E90    8438EEB0 
               8437F400    84385D60    8438AC80    8438EE20 
Pool_WAITQ     8437DFE0    8437DFE8    8437DFF0    8437DFF8 
               8437DFE0    8437DFE8    8437DFF0    8437DFF8 
Waitcnt        00000000    00000000    00000000    00000000 
Poolavail      00000094    00000252    00000251    00000094 
Poolcnt        00000095    00000254    00000254    00000095 
 
AmbigQFL       00000000    Process_Hits   00000000    Cache_Serial   00000000 
AmbigQBL       00000000    Valid_Hits     00000000    Cache_Stalls   00000000 
Disk_Reads     00000000    Invalid_Hits   00000000    Buffer_Stalls  00000000 
Disk_Writes    00000000    Misses         00000000 
 
      

The SDA command CLUE XQP/CACHE_HEADER displays the block buffer cache header.

SDA> CLUE XQP/VALIDATE=(1,4)
Searching BFRD Array for possible Corruption... 
Searching Lock Basis Hashtable for possible Corruption... 
 
      

In this example, executing the CLUE XQP/VALIDATE=1,4 command indicated that no corruption was detected in either the BFRD Array or the Lock Basis Hashtable.

This chapter describes how to write, debug, and invoke an SDA Extension. This chapter also describes the routines available to an SDA Extension.

6.1 Introduction

When analysis of a dump file or a running system requires intimate knowledge of data structures that are not known to the System Dump Analyzer, the functionality of SDA can be extended by the addition of new commands into which the necessary knowledge has been built. Note that in this description, whenever a reference is made to accessing a dump file (ANALYZE/CRASH_DUMP), this also includes accessing memory in the running system (ANALYZE/SYSTEM).

For example, a user-written device driver allocates nonpaged pool and records additional data about the device there (logging different types of I/O, perhaps), and a pointer to the new structure is saved in the device-specific extension of the UCB. After a system crash, the only way to look at the data from SDA is:

• Invoke the SDA command DEFINE to define a new symbol (for example, UCB$L_FOOBAR) whose value is the offset in the UCB of the pointer to the new structure.
• Invoke the SDA commands "SHOW DEVICE <device>" and "FORMAT UCB" to obtain the address of the nonpaged pool structure.
• Invoke the SDA command "EXAMINE <address>;<length>" to display the contents of the data in the new nonpaged pool structure as a series of hexadecimal longwords.
• Decode manually the contents of the data structure from this hexadecimal dump.

An extension to SDA that knows the layout of the nonpaged pool structure, and where to find the pointer to it in the UCB, could output the data in a formatted display that alerts the user to unexpected data patterns.

6.2 General Description

The following discussion uses an example of an SDA extension that provides the MBX command to output a formatted display of the status of the mailbox devices in the system. The source file, MBX$SDA.C, is provided in SYS$EXAMPLES.

An SDA extension consists of a shareable image, in our case MBX$SDA.EXE, either located in the directory SYS$LIBRARY or found by translating the logical name MBX$SDA. It contains two universal symbols: SDA$EXTEND, the entry point; and SDA$EXTEND_VERSION, the address of a longword that contains the version of the interface used (in the format of major/minor ident), which allows SDA to confirm it has activated a compatible extension. The image contains at least two modules: MBX$SDA, the user-written module that defines the two symbols and provides the code and data necessary to produce the desired formatted output; and SDA_EXTEND_VECTOR, which provides jackets for all of the callable SDA routines, and is found in SYS$LIBRARY:VMS$VOLATILE_PRIVATE_INTERFACES.OLB. The user-written portion can of course be split into multiple modules.

Whenever SDA receives an unrecognized command, like "SDA> MBX", it attempts to activate the shareable image MBX$SDA at the SDA$EXTEND entry point. If you choose a command name that matches the abbreviation of an existing command, SDA can be forced to activate the extension using the "DO" command. For example, if you had an SDA extension called VAL$SDA, you could not activate it with a command like "SDA> VAL" as SDA would interpret that as an abbreviation of its VALIDATE command. But VAL$SDA can be activated by issuing "SDA> DO VAL".

With or without the "DO" prefix, the rest of the command line is passed to the extension; it is up to the extension to parse it. The example extension MBX$SDA includes support for commands of the form "SDA> MBX SUMMARY" and "SDA> MBX <address>" to demonstrate this. It is recommended that if the extension is invoked with no arguments, it should do no more than display a simple announcement message, or prompt for input. This assists in the debugging of the extension, as described in Section 6.4.

6.3 Detailed Description

This section describes the compiling and linking, invoking, and the contents of an SDA extension.

6.3.1 Compiling and Linking an SDA Extension

$cc mbx$sda + alpha$library:sys$lib_c /library $link /share - mbx$sda.obj, - alpha$library:vms$volatile_private_interfaces /library, - sys$input /option symbol_vector = (sda$extend=procedure) symbol_vector = (sda$extend_version=data)

The SDA extension can then be invoked as follows:

$define mbx$sda sys$disk:[]mbx$sda $analyze /system SDA>mbx summary SDA>mbx <address>

6.3.3 Contents of an SDA Extension

At a minimum, the user-written module must contain:

• #include statements for DESCRIP.H and SDA_ROUTINES.H
• the global variable SDA$EXTEND_VERSION, initialized as follows:

  int sda$extend_version = SDA_FLAGS$K_VERSION;

• the routine SDA$EXTEND (prototype follows)

Optionally, the user-written module may also contain the statement:

#define __NEW_STARLET

This option is recommended, as it provides type checking of function arguments and gives consistency in casing and naming conventions.

The entry point in the user-written module, SDA$EXTEND, is called as a routine with three arguments and no return value. The declaration is as follows:

void sda$extend ( int *transfer_table, struct dsc$descriptor_s *cmd_line, SDA_FLAGS sda_flags)

The arguments in this code example have the following meanings:

Line of Code	Meaning
transfer_table	Address of the vector table in the base image. The user-written routine SDA$EXTEND must copy this to SDA$EXTEND_VECTOR_TABLE_ADDR before any SDA routines can be called.
cmd_line	Address of the descriptor of the command line as entered by the user, less the name of the extension. So, if "SDA> MBX" or "SDA> DO MBX" is entered, the command line is a zero length string. If the command "SDA> MBX 80102030" is entered, the command line is " 80102030" (the separating space is not stripped).
sda_flags	Defines only the following two bits in this structure: Bit Meaning sda_flags.sda_flags$v_override Indicates SDA has been activated with the ANALYZE/CRASH_DUMP/OVERRIDE command. sda_flags.sda_flags$v_current Indicates SDA has been activated with the ANALYZE/SYSTEM command. Neither bit set Indicates SDA was activated with the ANALYZE/CRASH_DUMP command.

The first executable statement of the routine must be to copy TRANSFER_TABLE to SDA$VECTOR_TABLE (which is declared in SDA_ROUTINES.H):

sda$vector_table = transfer_table;

If this is not done, it is not possible to call any of the routines described below. Any attempts to call the routines receives a status return of SDA$_VECNOTINIT. (For routines defined not to return a status, this value can be found only by examining R0.)

It is recommended that the next statement be one to establish a condition handler, as it is often difficult to track down errors in extensions such as access violations because the extension is activated dynamically with LIB$FIND_IMAGE_SYMBOL. A default condition handler, SDA$COND_HANDLER, is provided that outputs the following information in the event of an error:

• The error condition
• The VMS version
• A list of activated images, with start and end virtual addresses
• The signal array and register dump
• The current call frame chain

This condition handler can be established as follows:

lib$establish (sda$cond_handler);

Thus, a minimal extension would be:

#define __NEW_STARLET 1 #include <descrip.h> #include <sda_routines.h> int sda$extend_version = SDA_FLAGS$K_VERSION; void sda$extend (int *transfer_table, struct dsc$descriptor_s *cmd_line, SDA_FLAGS sda_flags) { sda$vector_table = transfer_table; lib$establish (sda$cond_handler); sda$print ("hello, world"); return; }

	privacy and legal statement
6549PRO_021.HTML