DSE Commands and Qualifiers

The following sections describe DSE commands and their qualifiers. DSE allows abbreviations of commands. The section explaining each command provides the minimal abbreviation for that command.

[Note]

The abbreviations designated for each command and qualifier represent the minimum distinguishable subset of letters.

The DSE commands work on the last region specified. If no other region has been selected during this DSE session, DSE works on the default region, which is the region mapping to the name-space *. Use the FIND /REGION=region command to initially specify or change the region.

Using DSE to modify your database is a very delicate operation. DSE should only be used by or under the supervision of someone who understands the GDS structure.

[Note]

To specify a null data value to DSE, use a backslash (\).

Example:

DSE> ADD /block=3 /record=1 /key="x(1)" /data="

To help the new DSE user, the following lists categorize the DSE commands by their potential level of impact on the database.

General Purpose Commands

The following commands do not affect the database:

Non-invasive Commands

The following commands use, but do not change, the database:

Invasive Commands

The following commands modify the database .

[Caution]

Use these commands only if you are completely sure that you know what you are doing, or under the direction of FIS technical support. Inappropriate use of these commands can result in improper operation of the application including hangs, crashes, and unrecoverable damage to the database. Under normal operation, there should be no need to use these commands:

DSE Command Syntax

The format for DSE commands is:

DSE> command [/qualifier[...]] [object[,...]]

DSE interprets all numeric input as hexadecimal, except for time values, the /BLK_SIZE=, /KEY_MAX_SIZE=, /RECORD_MAX_SIZE, /REFERENCE_COUNT=, /TIMERS PENDING, and /WRITES_PER_FLUSH on CHANGE /FILEHEADER, and /VERSION=, on the REMOVE and RESTORE commands. This convention corresponds to the displays provided by DSE and by MUPIP INTEG.

ADD

The ADD command adds a record to a block.

The format of the ADD command for blocks with a level greater than zero (0) is:

ADD [ /B[LOCK]=[block] /STAR /POINTER=block
or
ADD /[/B[LOCK]=[block]/OFFSET=offset|/RECORD=record /KEY=key /POINTER=pointer

For level 0 blocks, it is:

ADD/[/B[LOCK]=[block]/OFFSET=offset|/RECORD=record/KEY=key/D ATA=string 

The ADD command requires either the /OFFSET or /RECORD qualifier to position the record in the block, and either the /KEY or the /STAR qualifier to define the key for the block.

The /STAR qualifier is invalid at level 0 (a data block). The ADD command requires the /DATA qualifier at level 0 or the /POINTER qualifier at any other level to provide record content.

Qualifiers

/B[LOCK]=block-number

Specifies the block to receive the new record.

On commands with no /BLOCK= qualifier, DSE uses the last block handled by a DSE operation. When no block has been accessed, that is, on the first block-oriented command, DSE uses block one (1).

/D[ATA]=string

Specifies the data field for records added to a data block. Use quotation marks around the string and escape codes of the form or b, where "a" and "b" are hexadecimal digits representing non-printing characters. translates to a single backslash. The /DATA qualifier only applies at level 0 and is incompatible with the /STAR and /POINTER qualifiers.

/K[EY]=key

Specifies the key of the new record. Enclose M-style global references, including the leading caret symbol (^), in quotation marks (" "). The /KEY qualifier is incompatible with the /STAR qualifier.

/O[FFSET]=offset

Adds the new record at the next record boundary after the specified offset. The /OFFSET qualifier is incompatible with the /RECORD and /STAR qualifiers.

/P[OINTER]=pointer

Specifies the block pointer field for records added to an index block. The /POINTER qualifier is incompatible with the /DATA qualifier and cannot be used at level 0.

/R[ECORD]=record-number

Specifies a record number of the new record. The /RECORD qualifier is incompatible with the /OFFSET and /STAR qualifiers.

/S[TAR]

Adds a star record (i.e., a record that identifies the last record in an indexed block) at the end of the specified block. The /STAR qualifier is incompatible with all qualifiers except /BLOCK and /POINTER and cannot be used at level 0.

ALL

The ALL command applies action(s) specified by a qualifier to all GDS regions defined by the current Global Directory. This is a very powerful command; use it with caution. Be especially careful if you have an overlapping database structure (e.g., overlapping regions accessed from separate application Global Directories). If you use this type of database structure, you may need to construct special Global Directories to use with DSE that exclude overlapped regions. Do not use this command unless you understand how GT.M uses global directories.

The format of the ALL command is:

AL[L]  /B[UFFER_FLUSH]
/C[RITINIT]
/[NO]F[REEZE]
/O[VERRIDE]]
/REF[ERENCE]
/REL[EASE]
/REN[EW]
/S[EIZE]
/W[CINIT]           

Qualifiers

/BUFFER_FLUSH

Flushes to disk the file header and all cache buffers for all regions specified by the current Global Directory. The /BUFFER_FLUSH qualifier is incompatible with the /RENEW qualifier.

Just before breaking database on shadowed disks, it is important to freeze updates and then flush all regions. Failure to do so will result in a database with integrity errors on the shadowed copy. If you are doing this to backup your database without bringing down your application, FIS recommends MUPIP BACKUP/ONLINE as the preferred alternative.

/C[RITINIT]

Initializes critical sections for all regions specified by the current Global Directory. The /CRITINIT qualifier is incompatible with the /RENEW, /RELEASE, and /SEIZE qualifiers.

This causes all processes currently accessing the databases specified by the current Global Directory to terminate with an error.

[Caution]

Such action may cause database damages when used while concurrent updates are in progress.

/[NO]F[REEZE]

Allows a user to freeze, or prevent updates to, GDS regions specified by the current Global Directory. The /FREEZE qualifier freezes all such GDS regions except those previously frozen by another user. Regions frozen by a particular user are associated with that user. A frozen region may be updated in one of two ways: The user who froze the region may unfreeze it with the /NOFREEZE qualifier; or another user may override the freeze in conjunction with the /OVERRIDE qualifier.

For information about a preferred method of manipulating FREEZE, refer to the MUPIP FREEZE section of the "MUPIP" chapter.

By default, the /NOFREEZE qualifier unfreezes only those GDS regions that were previously frozen by the user the process. Once a region is unfrozen, it may be updated by any user. To unfreeze all GDS regions of the Global Directory, use the /OVERRIDE qualifier.

The /FREEZE qualifier is incompatible with the /RENEW qualifier.

DSE releases /FREEZE when it EXITs. To hold all databases, enter ALL FREEZE and then SPAWN to perform operations such as breaking a shadow.

/O[VERRIDE]

The /OVERRIDE qualifier is meaningful only with the /FREEZE or /NOFREEZE qualifiers. When used with /NOFREEZE it unfreezes all GDS regions, including those frozen by other users. When used with /FREEZE, the /OVERRIDE qualifier freezes all GDS regions, including those frozen by other users, associating all such freezes with the current user. The current user must then use the /NOFREEZE qualifier to unfreeze the database; any other user attempting a /NOFREEZE would also have to include the /OVERRIDE qualifier.

/REF[ERENCE]

Resets reference counts to 1 for all regions specified by the current Global Directory. The /REFERENCE qualifier is incompatible with the /RENEW qualifier.

/REL[EASE]

Releases critical sections for all regions specified by the current Global Directory. The /RELEASE qualifier is incompatible with the /CRITINIT, /RENEW, and /SEIZE qualifiers.

/REN[EW]

Reinitializes critical sections (/CRITICAL) and buffers (/WCINIT), resets reference counts (/REFERENCE_COUNT) to 1, and clears freeze flags for all regions specified by the current Global Directory (/NOFREEZE). /RENEW requires confirmation. The /RENEW qualifier is incompatible with all other qualifiers.

/S[EIZE]

Seizes the critical section for all regions specified by the current Global Directory. The /SEIZE qualifier is incompatible with the /CRITINIT, /RELEASE, and /RENEW qualifiers.

The /SEIZE qualifier can be useful when you encounter a DSEBLKRDFAIL error, generated when DSE is unable to read a block from the database.

/W[CINIT]

Reinitializes buffers for all regions specified by the current Global Directory. /WCINIT requires confirmation. The /WCINIT qualifier is incompatible with the /RENEW qualifier.

Buffer_flush

The BUFFER_FLUSH command flushes the file header and the current region's buffers to disk. This command is required immediately prior to breaking a disk mirror shadow set where the database resides.

The format of the BUFFER_FLUSH command is:

B[UFFER_FLUSH]

The BUFFER_FLUSH command has no qualifiers.

CHange

The CHANGE command changes fields of a block, file, or record header.

The format of the CHANGE command is:

CH[ANGE]

The CHANGE command either has a /FILEHEADER qualifier or an implicit or explicit /BLOCK qualifier, plus one or more of their associated qualifiers, to define the target of the change.

/BL[OCK]=block-number and one or more of the following qualifiers:

/BS[IZ]=block-size
/L[EVEL]=level
/TN[=transaction-number]
/OF[FSET]=offset
/RE[CORD]=record-number
/CM[PC]=compression-count
/RS[IZ]=record-size
or
/F[ILEHEADER] and one or more of the following qualifiers:
/BLK[_SIZE ]=block-size
/BLO[CKS_FREE]=free-blocks
/B_B[YTESTREAM]=transaction-number
/B_C[OMPREHENSIVE]=transaction-number
/B_D[ATABASE]=transaction-number
/B_I[NCREMENTAL]=transaction-number
/B_R[ECORD]=transaction-number
/CU[RRENT_TN]=transaction-number
/DEF[_COLLATION]=value
/FL[USH_TIME][=delta-time]
/FR[EEZE]=value
/K[EY_MAX_SIZE]=key-max-size
/M[ACHINE_NAM]=value
/NO[CRIT]
/N[ULL_SUBSCRIPTS]=value
/OV[ERRIDE]
/REC[ORD_MAX_SIZE]=record-max-size
/REF[ERENCE_COUNT]=reference-count
/REG[_SEQNO]=sequence-number
/RESYNC_S[EQNO]=sequence-number
/RESYNC-T[N]=sequence-number
/TIM[ERS_PENDING]=integer
/TO[TAL_BLKS]=total-blocks
/TR[IGGER_FLUSH]=trigger-flus
/W[RITES_PER_FLUSH]=writes-per-flush

Change / BLOCK Qualifiers

This section describes /BLOCK and all of its qualifiers.

/BL[OCK]=block_number

Specifies the block to modify. The /BLOCK qualifier is incompatible with the /FILEHEADER qualifier and all qualifiers related to /FILEHEADER.

/BLOCK is the default qualifier. On commands with neither a /BLOCK nor a /FILEHEADER qualifier, DSE uses the last block handled by a DSE operation. When no block has been accessed, that is, on the first block-oriented command, DSE uses block one (1).

The following qualifiers operate on a block header.

/BS[IZ]=block_size

Changes the block size field of the specified block. Decreasing the block size can result in loss of existing data. The /BSIZ qualifier is incompatible with all qualifiers except /BLOCK, /LEVEL and /TN.

[Note]

DSE does not allow you to change the block size to an arbitrary number. It always rounds the block size to the next higher multiple of 512, because database block sizes must always be a multiple of 512. Also, the block size must always be less than or equal to the block size in the file header.

/L[EVEL]=level

Changes the level field for the specified block. The /LEVEL qualifier is incompatible with all qualifiers except /BLOCK, /BSIZ, and /TN.

[Note]

DSE lets you change the level of a bitmap block to -1 (the value of the level for a bitmap block) when the bitmap level gets corrupted and takes on an arbitrary value. Note that -1 must be specified in hexadecimal, FF.

Example:

DSE >CHANGE /LEVEL=FF

/TN[=transaction_number]

Changes the transaction number for the current block. When a CHANGE command does not include a /TN=, DSE sets the transaction number to the current transaction number. Manipulation of the block transaction number affects MUPIP BACKUP /BYTESTREAM, and /ONLINE. The /TN qualifier is incompatible with all qualifiers except /BLOCK, /BSIZ, and /LEVEL.

The following /BLOCK qualifiers operate on a record header.

/OF[FSET]=offset

Specifies the offset, in bytes, of the target record within the block. If the offset does not point to the beginning of a record, DSE rounds down to the last valid record start (for example, CHANGE /OFFSET=10 starts at /OFFSET=A, if that was the last record). The /OFFSET qualifier is incompatible with all qualifiers except /BLOCK, /CMPC, and /RSIZ.

/RE[CORD]=record_number

Specifies the record number of the target record. The /RECORD qualifier is incompatible with all qualifiers except /BLOCK, /CMPC, and /RSIZ.

/CM[PC]=compression_count

Changes the compression count field of the specified record. Because compression counts propagate from the "front" of the block, this can potentially change the keys of all records following it in the block. If the goal is to change only a single record, it may be preferable to add a new record and remove the old one. The /CMPC qualifier is incompatible with all qualifiers except /BLOCK, /OFFSET, /RECORD, and /RSIZ.

/RS[IZ]=record_size

Changes the record size field of the specified record. The /RSIZ qualifier is incompatible with all qualifiers except /CMPC, /OFFSET, and /RECORD.

[Caution]

Changing this number impacts all records following it in the block.

Change / FILEHEADER Qualifiers

This section describes the /FILEHEADER qualifier and the other qualifiers that operate on a file header.

/FI[LEHEADER]

Enables modification of specific fields in the file header. The /FILEHEADER qualifier is incompatible with the /BLOCK and all qualifiers related to /BLOCK (that is /BSIZ, /CMPC, /LEVEL, /OFFSET, /RECORD, /RSIZ, and /TN qualifiers).

/BLK[_SIZE]=block_size

Changes the decimal block size field of the current file.

The block size cannot be changed to an arbitrary value. It always rounds the block size to the next higher multiple of 512, because database block sizes must always be a multiple of 512.

It is not possible to change the block size of a database file once it is created. The intent of the command is only to correct the value in the file header in case it is damaged.

/BLO[CKS_FREE]=free blocks

Changes the free blocks field of the current file. Use the /BLOCK_FREE qualifier only in conjunction with the /FILEHEADER qualifier.

/B_C[OMPREHENSIVE]=transaction-number

This deprecated command has been replaced by /B_D[ATABASE] and is temporarily supported for backward compatibility.

/B[YTESTREAM]=transaction_number

Changes the transaction number in the file header field that maintains this information about the last /BYTESTREAM backup.

/B_D[ATABASE]=transaction_number

Changes the transaction number in the file header field that maintains this information about the last /DATABASE backup.

/B_I[NCREMENTAL]=transaction_number

This deprecated command has been replaced by the /B_BYTESTREAM command, and is temporaily supported for backward compatibility.

/B_R[ECORD]=transaction_number

Changes the transaction number in the file header field that maintains this information about the last /RECORD backup.

/CU[RRENT_TN]=transaction_number

Changes the current transaction number for the current region. It also places a transaction number in a block header. This qualifier has implications only for MUPIP BACKUP /INCREMENTAL. Raising the /CURRENT_TN can correct "block transaction number too large" errors resulting from system crashes.

/FL[USH_TIME][=delta_time]

Changes the flush_time default interval (in delta_time). The time entered must be between zero and one hour. Input is interpreted as decimal. A /FLUSH_TIME with no value resets the /FLUSH_TIME to the default value (one second for BG and 30 seconds for MM).

The units of delta_time is centi-seconds (hundredths of a second). For example, to change the flush time interval to a second, delta_time would be 100. To change it to 30 minutes, delta_time would be 180,000 (30*60*100). Valid values for the qualifier are one to 360,000 (an hour).

/FR[EEZE]=value

Sets availability of the region for update. Possible values are: T[RUE] or F[ALSE]. Use to "freeze" (disable database writes) or "unfreeze" the database. FREEZE normally bypasses freezes by other processes. Use /OVERRIDE with /FREEZE to override a freeze by another process.

For information about a preferred method of manipulating FREEZE, refer to the MUPIP FREEZE section of the "MUPIP" chapter.

DSE releases /FREEZE when it EXITs. To hold the database(s), CHANGE /FILEHEADER /FREEZE=TRUE and then SPAWN to perform other operations.

/K[EY_MAX_SIZE]=key_max_size

Changes the decimal value for the maximum allowable key size. Reducing KEY_MAX_SIZE can restrict access to existing data and cause GT.M to report errors. Do not create incompatible key and record sizes.

Before permanently changing the key size using DSE, use GDE to check that the appropriate Global Directory contains the same key size for the region. This prepares for future MUPIP CREATEs and performs a consistency check on the key and record size values. For more information on key and record sizes, refer to the "Global Directory Editor" chapter.

M[ACHINE_NAM]=value

Sets the name of the machine of the open database to that of the current machine, or it cleans it. Values are CURRENT and CLEAR. You do not have to set the machine name.

MUPIP RUNDOWN is a better way to clean the machine after a crash or other abnormal event.

NO[CRIT]

Allows DSE DUMP to work even if another process is holding a critical section. Since results in this mode may be inconsistent, it should only be used if the critical section mechanism is not operating normally.

/N[ULL_SUBSCRIPTS]=value

Sets the acceptability of null subscripts in database keys. Possible values are: T[RUE] or F[ALSE]. Prohibiting null subscripts can restrict access to existing data and cause GT.M to report errors.

DSE rejects null subscripts for the /KEY qualifier for various commands if they are disabled by the NULLSUBSCRIPTS flag in the file header.

/OVERRIDE

The /OVERRIDE qualifier is meaningful only with the /FREEZE or /NOFREEZE qualifiers. When used with /NOFREEZE it unfreezes all GDS regions, including those frozen by other users. When used with /FREEZE, the /OVERRIDE qualifier freezes all GDS regions, including those frozen by other users, associating all such freezes with the current user. The current user must then use the /NOFREEZE qualifier to unfreeze the database; any other user attempting a /NOFREEZE would also have to include the /OVERRIDE qualifier.

/REF[ERENCE_COUNT]=reference_count

Sets a field that tracks how many processes are accessing the database with read/write permissions. MUPIP INTEG and DSE use decimal numbers for /REFERENCE_COUNT. To accurately determine the proper reference count, restrict CHANGE /FILEHEADER /REFERENCE_COUNT to the case where the process running DSE has exclusive (standalone) access to the database file. When DSE has sole access to a database file the /REFERENCE_COUNT should be one (1). This is an informational field and does not have any effect on processing.

/REG[_SEQNO]=sequence-number

In a replicated environment, this sets the "Region Seqno" field. Refer to the "Database Replication" chapter for more details.

/RESYNC_S[EQNO]=sequence-number

In a replicated environment, this sets the "Resync Seqno" field. Refer to the "Database Replication" chapter for more details.

/RESYNC_T[N]=sequence-number

In a replicated environment, this sets the "Resync transaction" field. Refer to the "Database Replication" chapter for more details.

/TI[MERS_PENDING]=timers_pending

Sets a field that tracks the number of processes considering a timed flush. Proper values are 0, 1, and 2.

/TO[TAL_BLKS]=total_blocks

Changes the total blocks field of the current file.

This command only changes the value saved in the file header. It does not affect the size of the database file. Do not change it to a value that does not match the actual size of the file.

/TR[IGGER_FLUSH]=trigger_flush

Sets the decimal value for the triggering threshold, in buffers, for flushing the cache-modified queue.

GT.M will dynamically adjust this value for optimal performance.

/WR[ITES_PER_FLUSH]=writes_per_flush

Sets the decimal number of blocks to write in each flush.

CLose

The CLOSE command closes the currently open output file.

The format of the CLOSE command is:

CL[OSE]

The CLOSE command has no qualifiers.

CRitical

The CRITICAL command, along with its qualifiers, displays and/or modifies the status and contents of the critical section for the current region. The critical section provides a control mechanism. This field identifies, by its process identification number (PID), the process presently managing updates to database.

The format of the CRITICAL command is:

CR[ITICAL] /I[NIT]
/O[WNER]
/REL[EASE]
/REM[OVE]
/S[EIZE]

By default, the CRITICAL command assumes the /OWNER qualifier, which displays the status of the critical section.

Qualifiers

/I[NIT]

Reinitializes the critical section. The /INIT RESET qualifiers together cause all GT.M processes actively accessing that database file to signal an error. Do not use /INIT without the /RESET parameter when other processes are accessing the region.

/O[WNER]

Displays the ID of the process at the head of the critical section. When the current process owns the critical section, DSE displays a warning message. The /OWNER qualifier is incompatible with other qualifiers.

Example:

DSE> critical /OWNER
Write critical section is currently unowned

/REL[EASE]

Releases the critical section if the process running DSE owns the section. The /RELEASE qualifier is incompatible with other qualifiers.

/REM[OVE]

Terminates any write ownership of the critical section. Use this when the critical section is owned by a process that is nonexistent or is known to no longer be running a GT.M image. The /REMOVE qualifier is incompatible with other qualifiers.

/RES[ET]

When used without /INIT, this qualifier displays the number of times that the critical section /RESET /INIT has been executed.

Using /RESET with /INIT causes an error for processes that are attempting to get the critical section of the region. Under the guidance of FIS, use /RESET /INIT as a way to clear certain types of hangs. The /RESET qualifier is only compatible with the /INIT qualifier.

/S[EIZE]

Seizes the critical section if the section is available. The /SEIZE qualifier is incompatible with other qualifiers.

Dump

The DUMP command displays blocks, records, or file headers. DUMP is one of the primary DSE examination commands. Use the error messages reported by MUPIP INTEG to determine what to DUMP and examine from the database. DUMP also transfers records to a sequential file for future study and/or for input to MUPIP LOAD.

The format of the DUMP command is:

D[UMP]  /A[LL]
/B[LOCK]=block_number
/C[OUNT]=count
/F[ILEHEADER]
/G[LO]
/[NO]C[RIT]
/[NO]H[EADER]
/O[FFSET]=offset
/R[ECORD]=record-number

The DUMP command requires specification of an object using either /BLOCK, /HEADER, /RECORD, or /FILEHEADER.

Qualifiers

/A[LL]

When used with /FILEHEADER, the /A[LL] qualifier displays additional information valuable to FIS technical support when troubleshooting GT.M problems.

/B[LOCK]=block-number

Specifies the starting block of the dump. The /BLOCK qualifier is incompatible with the /FILEHEADER qualifier.

For commands without an object qualifier, DSE uses the last block handled by a DSE operation. When no block has been accessed, (i.e., on the first block-oriented command), DSE uses block one (1).

Example:

DSE> DUMP /BLOCK=2
        
Block 2 Size 1B Level 0 TN 2
Rec:1 Blk 2 Off 7 Size A Cmpc 0 Ptr 8 Key ^a
7 : | A 0 0 61 0 0 8 0 0 0 
| . . . a . . . . . .
Rec:2 Blk 2 Off 11 Size A Cmpc 0 Ptr B Key ^b
11 : | A 0 0 62 0 0 B 0 0 0
| . . . b . . . . . .

/C[OUNT]=count

Specifies the number of blocks, block headers, or records to DUMP. The /COUNT qualifier is incompatible with the /FILEHEADER qualifier.

/F[ILEHEADER]

Dumps file header information. The /FILEHEADER qualifier is incompatible with all other qualifiers except /ALL. A DSE dump of a database file header prints a 0x prefix for all fields printed in hexadecimal format.

Example:

DSE> DUMP /FILEHEADER

Access method                 BG     Global Buffers           1024
Reserved Bytes                 0     Block size (in bytes)    8192
Maximum record size          510     Starting VBN               49
Maximum key size             128     Total blocks       0x00000386
Null subscripts            FALSE     Free blocks        0x00000032
Last Record Backup    0x00000001     Extension Count           100
Last Database Bckup   0x00000001     Number of local maps        2
Last Bytestream Bckup 0x00000001     Lock space         0x00000028
In critical section   0x00000000     Timers pending              0
Cache freeze id       0x00000000     Flush timer       00:00:01.00
Freeze match          0x00000000     Flush trigger             960
Current transaction   0x000A9689     No. of writes/flush         7
Create in progress         FALSE     Modified cache blocks       0
Reference count                1     Journaling         DISALLOWED
KILLs in progress              0
Replication State         CLOSED     Region Seqno              0x1
Resync Seqno                 0x1     Resync transaction 0x00000001

Refer to the "Greystone Database Structure" chapter for a description of the file header fields.

/G[LO]

Dumps the specified record or blocks into the current output file in Global Output (GO) format. The /GLO qualifier is incompatible with the /HEADER and /FILEHEADER qualifiers. Once you choose the /GLO format, you must exit DSE and reenter to choose the /ZWR format.

/NO[CRIT]

Allows DSE DUMP to work even if another process is holding a critical section. Since results in this mode may be inconsistent, it should only be used if the critical section mechanism is not operating normally.

/[NO]H[EADER]

Specifies whether the dump of the specified blocks or records is restricted to, or excludes, headers. /HEADER displays only the header, /NOHEADER displays the block or record with the header suppressed. DUMP without the /[NO]HEADER qualifier dumps both the block/record and the header. The /HEADER qualifier is incompatible with the /ZWR, /GLO, and /FILEHEADER qualifiers.

By default, DUMP displays all information in a block or record.

/O[FFSET]=offset

Specifies the offset, in bytes, of the starting record for the dump. If the offset does not point to the beginning of a record, DSE rounds down to the last valid record start (e.g., DUMP /OFF=10 starts at /OFF=A if that was the last record). The /OFFSET qualifier is incompatible with the /RECORD and /FILEHEADER qualifiers.

/R[ECORD]=record_number

Specifies the record number of the starting record of the dump. The /RECORD qualifier is incompatible with the /OFFSET and /FILEHEADER qualifiers.

If you try to dump a record number that is larger than the last actual record in the block, a DSE error message provides the number of the last record in the block.

/ZWR

Dumps the specified record or blocks into the current output file in ZWRITE (ZWR) format. The /ZWR qualifier is incompatible with the /HEADER and /FILEHEADER qualifiers. Once you choose the /ZWR format, you must exit DSE and reenter to choose the /GLO format.

EValuate

The EVALUATE command displays a number in both hexadecimal and decimal. Use it to translate a hexadecimal number to decimal, and vice versa. The /DECIMAL and /HEXADECIMAL qualifiers specify the input base for the number.

The format of the EVALUATE command is:

EV[ALUATE]  /D[ECIMAL]
/H[EXADECIMAL]
/N[UMBER]=number

The /NUMBER qualifier is required.

By default, EVALUATE treats the number as having a hexadecimal base.

Qualifiers

/D[ECIMAL]

Specifies that the input number has a decimal base. The /DECIMAL qualifier is incompatible with the /HEXADECIMAL qualifier.

/H[EXADECIMAL]

Specifies that the input number has a hexadecimal base. The /HEXADECIMAL qualifier is incompatible with /DECIMAL.

/N[UMBER]=number

Specifies the number to evaluate. This qualifier is required.

Example:

DSE> EVALUATE /NUMBER=61
Hex: 61 Dec: 97

EXit

The EXIT command ends a DSE session.

The format of the EXIT command is:

EX[IT]

The EXIT command has no qualifiers.

Find

The FIND command directs DSE to a given block or region. At the beginning of a DSE session, use the FIND /REGION command to select the target region.

The format of the FIND command is:

        
F[IND]  /B[LOCK]=block-number 
/E[XHAUSTIVE] 
/F[REEBLOCK] /H[INT]
/K[EY]=key 
/[NO]C[RIT]
/R[EGION][=region] 
/S[IBLINGS]

The FIND command, except when used with the /FREEBLOCK and /REGION qualifiers, uses the index tree to locate blocks. FIND can locate blocks only within the index tree structure. If you need to locate keys independent of their attachment to the tree, use the RANGE command.

Qualifiers

/B[LOCK]=block_number

Specifies the block to find. This qualifier is incompatible with the /KEY and /REGION qualifiers.

On commands without the /BLOCK= qualifier, DSE uses the last block handled by a DSE operation. When no block has been accessed, that is, on the first block-oriented command, DSE uses block one (1).

/E[XHAUSTIVE]

Instructs DSE to search the entire index structure for the desired path or siblings. FIND /EXHAUSTIVE is useful in locating blocks that are in the tree but not indexed correctly. The /EXHAUSTIVE qualifier is incompatible with the /FREEBLOCK, /KEY, and /REGION qualifiers.

/F[REEBLOCK]

Finds the nearest free block to the block specified by /HINT. The /FREEBLOCK qualifier is incompatible with all other qualifiers except /BLOCK and /HINT. The /HINT qualifier is required with the /FREEBLOCK qualifier.

/H[INT]=block_number

Designates the starting point of a /FREEBLOCK search. The /HINT qualifier must be used only in conjunction with the /FREEBLOCK qualifier.

/K[EY]=key

Searches the database for the block containing the specified key or if the key does not exist, the block that would contain it, if it existed. Enclose an M-style key in quotation marks (" "). FIND /KEY is useful in locating properly indexed keys. The /KEY qualifier is incompatible with all other qualifiers.

/[NO]C[RIT]

Allows DSE FIND to work even if another process is holding a critical section. Since results in this mode may be inconsistent, it should only be used if the critical section mechanism is not operating normally.

/R[EGION][=region]

Switches to the named Global Directory region. The /REGION qualifier is incompatible with all other qualifiers.

/REGION without a specified region, or /REGION="*", displays all existing regions in the database.

/S[IBLINGS]

Displays the block numbers of the logical siblings of the specified block. The logical siblings are the blocks that logically exist to the right and left of the given block in the database tree structure. The /SIBLINGS qualifier is incompatible with the /FREEBLOCK, /HINT, /KEY, and /REGION qualifiers.

Help

The HELP command explains DSE commands. The HELP command uses similar conventions to the OpenVMS help facility. The format of the HELP command is:

/H[ELP] [help topic]

Enter the DSE command (item) after the HELP command or at the Topic prompt. The command (item) tells HELP which information to display. Press <RETURN> or <CTRL Z> to return to the DSE prompt.

Integrit

The INTEGRIT command checks the internal consistency of a single non-bitmap block. INTEGRIT reports errors in hexadecimal notation.

[Note]

Unlike MUPIP INTEG, this command only detects errors internal to a block and cannot detect errors such as indices incorrectly pointing to another block.

The format of the INTEGRIT command is:

I[NTEGRIT] /B[LOCK]=block-number

For information on the utility that checks multiple blocks, refer to the MUPIP INTEG section of the "MUPIP" chapter.

Qualifiers

/B[LOCK]=block_number

Specifies the block for DSE to check. On commands with no /BLOCK qualifier, DSE uses the last block handled by a DSE operation. When no block has been accessed, that is, on the first block-oriented command, DSE uses block one (1).

/NO[CRIT]

Allows DSE INTEG to work even if another process is holding a critical section. Since results in this mode may be inconsistent, it should only be used if the critical section mechanism is not operating normally.

Maps

The MAPS command examines or updates bitmaps. The format of the MAPS command is:

M[APS] /BL[OCK]=block-number
/BU[SY]
/F[REE]
/M[ASTER]
/R[ESTORE_ALL]

MAPS can flag blocks as being either /BUSY or /FREE. The /MASTER qualifier reflects the current status of a local bitmap back into the master map. The /RESTORE_ALL qualifier rebuilds all maps and should be used with caution since it can destroy important information.

By default, MAPS shows the status of the bitmap for the specified block.

Qualifiers

/BL[OCK]=block_number

Specifies the target block for MAPS. The /BLOCK qualifier is incompatible with the /RESTORE_ALL qualifier.

On commands with no /BLOCK= or /RESTORE_ALL qualifier, DSE uses the last block handled by a DSE operation. When no block has been accessed, that is, on the first block-oriented command, DSE uses block one (1).

/BU[SY]

Marks the current block busy in the block's local map and appropriately updates the master bitmap. The /BUSY qualifier is incompatible with all qualifiers except /BLOCK.

/F[REE]

Marks the current block free in the block's local map and appropriately updates the master bitmap. The /FREE qualifier is incompatible with all qualifiers except /BLOCK.

/M[ASTER]

Sets the bit in the master bitmap associated with the current block's local map according to whether or not that local map is full. The /MASTER qualifier is incompatible with all qualifiers except /BLOCK.

/R[ESTORE_ALL]

Sets all local bitmaps and the master bitmap to reflect the blocks used in the database file. Use /RESTORE_ALL only if the database contents are known to be correct, but a large number of the bitmaps require correction. The /RESTORE_ALL qualifier is incompatible with all other qualifiers.

[Caution]

The /RESTORE_ALL qualifier rebuilds all maps and should be used with a great deal of caution as it can destroy important information.

OPen

The OPEN command opens a file for sequential output of global variable data. OPEN a file to which you want to "dump" information.

The format of the OPEN command is:

OP[EN] F[ILE]=file

If an OPEN command does not have a /FILE qualifier, DSE reports the name of the current output file.

Qualifiers

/F[ILE]= file-specification

Specifies the file to open.

OVerwrite

The OVERWRITE command overwrites the specified string onto the given offset in the current block. Use extreme caution when using this command.

The format of the OVERWRITE command is:

OV[ERWRITE] /D[ATA]=string
/O[FFSET]=offset

Qualifiers

/B[LOCK]=block number

Directs DSE to OVERWRITE a specific block. If no block number is specified, the default is the current block.

/D[ATA]=string

Specifies the data to be written. Use quotation marks around string and escape codes of the form or b, where a and b are hexadecimal digits, for non-printing characters. translates to a single backslash.

/O[FFSET]=offset

Specifies the offset in the current block where the overwrite should begin.

Page

The PAGE command sends one form feed to the output device. Use PAGE to add form feeds to a dump file, making the hard copy file easier to read. If you plan to use the dump file with MUPIP LOAD, do not use PAGE.

The format of the PAGE command is:

P[AGE]

The PAGE command has no qualifiers.

RAnge

The RANGE command finds all blocks in the database whose first key falls in the specified range of keys. The RANGE command may take a very long time unless the range specified by /FROM and /TO is small. Use FIND /KEY and/or FIND /KEY /EXHAUSTIVE first to quickly determine whether the key appears in the index tree.

The format of the RANGE command is:

RA[NGE] /F[ROM]=block-number
/T[O]=block-number
/I[NDEX]
/LOS[T]
/[NO]C[RIT]
/[NO]BU[SY]
/S[TAR]
/LOW[ER]=key
/U[PPER]=key                

Qualifiers

/F[ROM]=block_number

Specifies a starting block number for the range search.

By default, RANGE starts processing at the beginning of the file.

/T[O]=block-number

Specifies an ending block number for the range search. By default, RANGE stops processing at the end of the file.

/I[NDEX]=block-number

Restricts a search to index blocks.

/LOS[T]=block_number

Restricts a search to blocks not found by a FIND /BLOCK.

/LOW[ER]=key

Specifies the lower bound for the key range.

/[NO]BU[SY]=busy/free

Restricts a search to either BUSY or FREE blocks.

/[NO]C[RIT]

Allows DSE RANGE to work even if another process is holding a critical section. Since results in this mode may be inconsistent, it should only be used if the critical section mechanism is not operating normally.

/S[TAR]=block-number

Includes index blocks that contain a single star key.

/U[PPER]=key

Specifies the upper bound for the key range.

REMove

The REMOVE command removes one or more records or a save buffer.

The format of the REMOVE command is:

REM[OVE]    /B[LOCK]=block-number
/C[OUNT]=count
/O[FFSET]=offset
/R[ECORD]=record-number
/V[ERSION]=version-number

The version number is specified in decimal.

Qualifiers

/B[LOCK]=block_number

Specifies the block associated with the record or buffer being deleted.

On commands with no /BLOCK= qualifier, DSE uses the last block handled by a DSE operation. When no block has been accessed, that is, on the first block-oriented command, DSE uses block one (1).

/C[OUNT]=count

Specifies the number of records to remove. The /COUNT qualifier is incompatible with the /VERSION qualifier.

By default, REMOVE deletes a single record.

/O[FFSET]=offset

Specifies the offset (in bytes) of the record to be removed. If the offset does not point to the beginning of a record, DSE rounds down to the last valid record start (for example, REMOVE /OFF=10 starts at OFF=A if that was the last record). The /OFFSET qualifier is incompatible with the /RECORD and /VERSION qualifiers.

/R[ECORD]=record_number

Specifies the number that identifies the record to remove. The /RECORD qualifier is incompatible with the /OFFSET and /VERSION qualifiers.

/V[ERSION]=version_number

Specifies the version number, in decimal, of the save buffer to remove. /VERSION is required to REMOVE a SAVE buffer. /VERSION is incompatible with all qualifiers except /BLOCK.

REStore

The RESTORE command restores saved versions of blocks.

RES[TORE]   B[LOCK]=block-number
F[ROM]=from
R[EGION]=region
V[ERSION]=version-number                    

The version number is specified in decimal.

Qualifiers

/B[LOCK]=block_number

Specifies the block to restore.

For commands with no /BLOCK= qualifier, DSE uses the last block handled by a DSE operation. When no block has been accessed, (i.e., on the first block-oriented command), DSE uses block one (1).

/F[ROM]=block_number

Specifies the block number of the save buffer to restore.

DSE restores the block specified with /BLOCK qualifier with the block specified by the /FROM qualifier.

By default, RESTORE uses the target block number as the /FROM block number.

The default block number is 1.

/R[EGION]=region

Specifies the region of the saved buffer to restore.

By default, RESTORE uses SAVE buffers from the current region.

/V[ERSION]=version_number

Specifies the decimal version number of the block to restore. The version number is required.

SAve

The SAVE command preserves versions of blocks, or displays a listing of saved versions for the current DSE session. Saved information is lost when DSE EXITs.

Use with the RESTORE command to move SAVEd blocks to a permanent location, and as a safety feature use SAVE to retain copies of database blocks before changing them.

The format of the SAVE command is:

SA[VE] /B[LOCK]=block-number
/C[OMMENT]=string
/L[IST]
/[NO]C[RIT]

Qualifiers

/B[LOCK]=block_number

Specifies the block to restore.

On commands with no /BLOCK= qualifier, DSE uses the last block handled by a DSE operation. When no block has been accessed, that is, on the first block-oriented command, DSE uses block one (1).

/C[OMMENT]=string

Specifies a comment to save with the block. Enclose the comment in quotation marks (" "). The /COMMENT qualifier is incompatible with the /LIST qualifier.

/L[IST]

Lists saved versions of specified blocks. The /LIST qualifier is incompatible with the /COMMENT qualifier.

By default, SAVE /LIST provides a directory of all SAVEd blocks.

/NO[CRIT]

Allows DSE SAVE to work even if another process is holding a critical section. Since results in this mode may be inconsistent, it should only be used if the critical section mechanism is not operating normally.

SHift

The SHIFT command shifts data in a block, filling the block with zeros, or shortening the block.

DSE SHIFT in the backward direction is restricted to the maximum of OFFSET number of bytes.

In the following command, m must be less than or equal to n:

DSE >SHIFT /BACKWARD=m /OFFSET=n

This ensures that the shift will not cross block boundaries, either intentionally or unintentionally.

Use extreme caution with this command. The format of the SHIFT command is:

SH[IFT]  B[ACKWARD]=shift
F[ORWARD]=shift
O[FFSET]=offset                

Qualifiers

/B[ACKWARD]=shift

Specifies the number of bytes to shift data in the direction of the block header. The /BACKWARD qualifier is incompatible with the /FORWARD qualifier.

/F[ORWARD]=shift

Specifies the number of bytes to shift data toward the end of the block. The /FORWARD qualifier is incompatible with the /BACKWARD qualifier.

/O[FFSET]=offset

Specifies the starting offset, in bytes, of the portion of the block to shift.

/SPawn

The SPAWN command creates a subprocess for access to the OpenVMS Command Language Interpreter (CLI), usually DCL, without terminating the current DSE environment. Use the SPAWN command to suspend a session and issue DCL commands such as MUPIP INTEG /REGION or GDE. The SPAWN command accepts an optional command string for execution by the spawned sub-process. If the SPAWN has no command string parameter, the created subprocess issues a DCL prompt and accepts any legal CLI command. To terminate the subprocess, use the LOGOUT DCL command.

The format of the SPAWN command is:

SP[AWN] [command]

The SPAWN command has no qualifiers.

Wcinit

The WCINIT command reinitializes the global buffers of the current region. Because it cleans out the cache, the WCINIT command should not be used except under the guidance of FIS.

[Warning]

A WCINIT command issued while normal database operations are in progress can cause catastrophic damage to the database.

The format of the WCINIT command is:

W[CINIT]

The WCINIT command has no qualifiers.

When you issue the WCINIT command, DSE issues the CONFIRMATION: prompt. You must verify the WCINIT command by responding with "YES."

If you do not confirm the WCINIT, DSE issues the message:

No action taken, enter yes at the CONFIRMATION prompt to initialize global buffers.

WCINIT operations are more safely performed by MUPIP RUNDOWN. Use this command only under instructions from FIS.