The general format of DSE commands is:

command [-qualifier[...]] [object[,...]]

DSE interprets all numeric input as hexadecimal, except for time values, the values for the following qualifiers when used with CHANGE -FILEHEADER: -BLK_SIZE=, DECLOCATION=, -KEY_MAX_SIZE=, -RECORD_MAX_SIZE, -REFERENCE_COUNT=, -TIMERS_PENDING and -WRITES_PER_FLUSH, and the value for -VERSION= when used with the REMOVE and RESTORE commands. These conventions correspond to the displays provided by DSE and by MUPIP INTEG.

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] {-OFFSET=offset|-RECORD=record} -STAR -POINTER=block

or

ADD [-B[LOCK]=[block] {-OFFSET=offset|-RECORD=record} -KEY=key -POINTER=pointer

The format of the ADD command for level 0 blocks is:

ADD [-B[LOCK]=[block] {-OFFSET=offset|-RECORD=record} -KEY=key -DATA=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.

-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 \a\b, where "a" and "b" are hexadecimal digits representing non-printing characters. \\ translates to a single backslash. \'\' translates to a NULL value.

Incompatible with: -STAR,-POINTER

-K[EY]=key

Specifies the key of the new record. Enclose M-style global references, including the leading caret symbol (^), in quotation marks (" ").

Incompatible with: -STAR

-O[FFSET]=offset

Adds the new record at the next record boundary after the specified offset.

Incompatible with: -RECORD, -STAR

-P[OINTER]=pointer

Specifies the block pointer field for records added to an index block. The -POINTER qualifier cannot be used at level 0. Note this means that to add pointers at level 0 of the Directory Tree you must specify a string of bytes or temporarily change the block level.

Incompatible with: -DATA

-R[ECORD]=record-number

Specifies a record number of the new record.

Incompatible with: -OFFSET,-STAR

-S[TAR]

Adds a star record (that is, a record that identifies the last record in an indexed block) at the end of the specified block. The -STAR qualifier cannot be used at level 0.

Incompatible with: -DATA,-KEY,-OFFSET,-RECORD

DSE>add -block=6F -record=57 -key="^Capital(""Mongolia"")" -data="Ulan Bator"

This command adds a new record with key ^Capital("Mongolia") at the specified location. Note that this command is applicable to level 0 blocks only.

Example:

DSE>add -star -bl=59A3 -pointer=2

This command adds a star record in block 59A3. Note that this command is applicable to blocks > level 0.

Example:

DSE>add -block=3 -record=4 -key="^Fruits(4)" -data="Grapes"

Suppose your database has 3 global nodes -- ^Fruits(1)="Apple", ^Fruits(2)="Banana", and ^Fruits(3)="Cherry", then the above command adds a new node ^Fruits(4)="Grapes" at record 4. Note that this command is applicable to level 0 blocks only. The interpreted output as a result of the above command looks like the following:

Block 3   Size 4B   Level 0   TN 4 V6
Rec:1  Blk 3  Off 10  Size 14  Cmpc 0  Key ^Fruits(1)
      10 : | 14  0  0  0 46 72 75 69 74 73  0 BF 11  0  0 41 70 70 6C 65|
           |  .  .  .  .  F  r  u  i  t  s  .  .  .  .  .  A  p  p  l  e|
Rec:2  Blk 3  Off 24  Size D  Cmpc 8  Key ^Fruits(2)
      24 : |  D  0  8  0 21  0  0 42 61 6E 61 6E 61                     |
           |  .  .  .  .  !  .  .  B  a  n  a  n  a                     |
Rec:3  Blk 3  Off 31  Size D  Cmpc 8  Key ^Fruits(3)
      31 : |  D  0  8  0 31  0  0 43 68 65 72 72 79                     |
           |  .  .  .  .  1  .  .  C  h  e  r  r  y                     |
Rec:4  Blk 3  Off 3E  Size D  Cmpc 8  Key ^Fruits(4)
      3E : |  D  0  8  0 41  0  0 47 72 61 70 65 73                     |
           |  .  .  .  .  A  .  .  G  r  a  p  e  s                     |

Example:

$dse add -star -bl=1 -pointer=2

This command adds a star record in block 1. Note that this command is applicable to blocks > Level 0.

Example:

$ dse add -block=4 -key="^Vegetables" -pointer=7 -offset=10

This command creates a block with key ^Vegetables pointing to block 7.

Example:

DSE> add -record=2 -key="^foo" -data=\'\' 

This example adds a new node (set ^foo="") as the second record of the current database block.

Applies action(s) specified by a qualifier to all GDS regions defined by the current global directory.

The format of the ALL command is:

AL[L]
[
-B[UFFER_FLUSH]
-C[RITINIT]
-D[UMP] -A[LL] 
-[NO]F[REEZE]
-O[VERRIDE]]
-REF[ERENCE]
-REL[EASE]
-REN[EW]
-S[EIZE]
-W[CINIT]           
]

-ALL

Displays additional information on the database most of which is useful for FIS in diagnosing issues.

Meaningful only with: -D[UMP]

-BUFFER_FLUSH

Flushes to disk the file header and all pooled buffers for all regions of the current global directory.

Incompatible with: -RENEW

-C[RITINIT]

Initializes critical sections for all regions of the current directory.

Incompatible with: -RENEW, -RELEASE, -SIEZE

[Caution]Caution

Never use CRITINIT while concurrent updates are in progress as doing so may damage the database.

-[D]UMP

Displays fileheader information.

Compatible with: -A[LL]

-[NO]F[REEZE]

Freezes or prevents updates all regions of the current global directory.

Incompatible with: -RENEW

-O[VERRIDE]

Overrides the ALL -FREEZE or ALL -NOFREEZE operation.

When used with -NOFREEZE, -OVERRIDE unfreezes all GDS regions, including those frozen by other users.

When used with -FREEZE, -OVERRIDE freezes all GDS regions, including those frozen by other processes associating all such freezes with the current process. The current process must then use -NOFREEZE to unfreeze the database; any other process attempting a -NOFREEZE should also have to include the -OVERRIDE qualifier.

Meaningful only with: [NO]FREEZE

-REF[ERENCE]

Resets the reference count field to 1 for all regions of the current global directory.

Incompatible with: -RENEW

-REL[EASE]

Releases critical sections for all regions of the current global directory.

Incompatible with: -CRITINIT, -RENEW, -SEIZE

-REN[EW]

Reinitializes the critical sections (-CRITICAL) and buffers (-WCINIT), resets reference counts (-REFERENCE_COUNT) to 1, and clears freeze (-NOFREEZE) for all regions of the current global directory .

-S[EIZE]

Seizes the critical section for all regions of the current global directory. The -SEIZE qualifier is useful when you encounter a DSEBLKRDFAIL error, generated when DSE is unable to read a block from the database.

Incompatible with: -RENEW, -RELEASE, -CRITINIT

-W[CINIT]

Reinitializes the buffers for all regions of the current global directory.

-WCINIT requires confirmation.

[Caution]Caution

This operation is likely to cause database damage when used while concurrent updates are in progress.

Incompatible with: -RENEW

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:

-AB[ANDONED_KILLS]=value
-AVG_BLKS_READ=Average-blocks-read
-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
-BLK_SIZE=block-size
-BLO[CKS_FREE]=free-blocks
-CU[RRENT_TN]=transaction-number
-COM[MITWAIT_SPIN_COUNT]=boolean
-DATA[_RESERVED_BYTES]=reserved-bytes
-DEC[LOCATION]=value
-DEF[_COLLATION]=value
-ENCRYPTION_HASH
-FL[USH_TIME][=delta-time]
-FR[EEZE]=value
-FU[LLY_UPGRADED]=boolean
-GV[STATSRESET]
-HA[RD_SPIN_COUNT]=Mutex-hard-spin-count
-HE[XLOCATION]=value
-INDEX[_RESERVED_BYTES]=reserved-bytes
-INT[ERRUPTED_RECOV]=boolean
-JNL_YIELD_LIMIT=journal-yeild-limit
-KE[Y_MAX_SIZE]=key-max-size
-KI[LL_IN_PROG]=value
-M[ACHINE_NAM]=value
-N[ULL_SUBSCRIPTS]=value
-NO[CRIT]
-OV[ERRIDE]
-Q[DBRUNDOWN]
-RC_SRV_COUNT
-RE_READ_TRIGGER=read-trigger
-REC[ORD_MAX_SIZE]=record-max-size
-REF[ERENCE_COUNT]=reference-count
-REG[_SEQNO]=sequence-number
-RESERVED_BYTES=reserved-bytes
-SLEE[P_SPIN_COUNT]=mutex-sleep-spin-count
-SPIN[_SLEEP_MASK]=mutex-spin-sleep-mask
-STRM_NUM=stream-number STRM_REG_SEQNO=hexa
-TIM[ERS_PENDING]=integer
-TO[TAL_BLKS]=total-blocks
-TR[IGGER_FLUSH]=trigger-flus
-UPD_RESERVED_AREA=reserved-area
-UPD_WRITER_TRIGGER_FACTOR=trigger-factor
-W[RITES_PER_FLUSH]=writes-per-flush
-WAIT_DISK=wait-disk
-Zqgblmod_S[EQNO]=sequence-number
-Zqgblmod_TN=sequence-number

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).

Incompatible with: -FILEHEADER and qualifiers used with -FILEHEADER

The following qualifiers operate on a block header.

-BS[IZ]=block_size

Changes the block size field of the specified block.

[Note]Note

The block size must always be less than or equal to the block size in the file header.

Use only with: -BLOCK, -LEVEL, -TN

-L[EVEL]=level

Changes the level field for the specified block.

[Note]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 you should specify -1 in hexadecimal form, that is, FF.

Use only with: -BLOCK, -BSIZ, -TN

Example:

DSE >change -level=FF

-TN[=transaction_number]

Changes the transaction number for the current block.

Use only with: -BLOCK, -BSIZ, -LEVEL

-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).

Use only with: -BLOCK, -CMPC, and -RSIZ.

-RE[CORD]=record_number

Specifies the record number of the target record.

Use only with: -BLOCK, -CMPC, and -RSIZ.

-CM[PC]=compression_count

Change the compression count field of the specified record.

  • The compression count specifies the number of bytes at the beginning of a key that are common to the previous key in the same block.

  • 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.

Use only with: -BLOCK, -RECORD, -OFFSET, -RSIZE

-RS[IZ]=record_size

Changes the record size field of the specified record.

[Caution]Caution

Changing -RSIZ impacts all records following it in the block.

Use only with: -BLOCK, -RECORD, -CMPC, -OFFSET

Example:

DSE> change -record=3 -rsiz=3B -block=2

This command changes the record size of record 3 block 2 to 59 (Hex: 3B) bytes.

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

-FI[LEHEADER]

Modifies a file header element that you specify with an associated qualifier.

Incompatible with: -BSIZ, -CMPC, -TN, -LEVEL, -OFFSET, -RECORD, -RSIZ

-AB[ANDONED_KILLS]=value

Changes the value of the Abandoned Kills field. The value can be "NONE" or a decimal positive integer.

Use only with: -FILEHEADER

-BLK[_SIZE]=block_size

Changes the decimal block size field of the current file.

Use only with: -FILEHEADER

-BLO[CKS_FREE]=free blocks

Changes the hexadecimal free blocks field of the current file.

Use this to correct a value that MUPIP INTEG reports as needing a correction, but note that the "correct" value reported by INTEG may go out-of-date with the next update. It may be necessary to calculate a delta value from the INTEG report, FREEZE the region with DSE, DUMP the current -FILEHEADER value, then apply the delta and CHANGE the -BLOCKS_FREE, and finally turn -OFF the FREEZE.

Use only with: -FILEHEADER

-B[YTESTREAM]=transaction_number

Changes the transaction number in the file header of the last incremental backup to the value specified. Use this qualifier only in conjunction with the -FILEHEADER qualifier. For compatibility issues with priot versions, this can still be specified as -B_COMPREHENSIVE.

-D[ATABASE]=transaction_number

Changes the hexadecimal transaction number in the file header of the last comprehensive backup to the value specified. Use this qualifier only in conjunction with the -FILEHEADER qualifier. For compatibility issues with prior versions, this can still be specified as -B_COMPREHENSIVE.

-B_R[ECORD]=transaction_number

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

-CO[RRUPT_FILE]=boolean

Indicates whether or not a region completed a successful recovery with the MUPIP JOURNAL -RECOVER command. Possible values are: T[RUE] or F[ALSE].

Changing this flag does not correct or cause database damage. When CORRUPT_FILE is set to TRUE, the DSE DUMP command displays a message like the following:

%GTM-W-DBFLCORRP, /home/gtmnode1/mumps.dat Header indicates database file is corrupt
[Caution]Caution
After a CHANGE -FILEHEADER -CORRUPT=TRUE, the file is unavailable to future GT.M access other than DSE. Under normal conditions, there should never be a need to change this flag manually. A MUPIP SET -PARTIAL_BYPASS_RECOV sets this flag to false.

Use only with: -FILEHEADER

-COM[MITWAIT_SPIN_COUNT]=value

Specifies the decimal number of times a GT.M process waiting for control of a block to complete a block update should spin before yielding the CPU when GT.M runs on SMP machines. When run on a uniprocessor system, GT.M ignores this parameter. On SMP systems, when a process needs a critical section that another process has, if critical sections are short (as they are by design in GT.M), spinning a little with the expectation that the process with the critical section will release it shortly provides a way to enhance performance at the cost of increased CPU usage. Eventually, a process awaiting a critical section yields the CPU if spinning for a little does not get it the needed critical section. Note that on heavily loaded systems, increasing COMMITWAIT_SPIN_COUNT may not trade off CPU for throughput, but may instead degrade both. If you set the COMMITWAIT_SPIN_COUNT to 0, the waiting process performs a sequence of small sleeps instead of the spins or yields.

The default value is 16.

Use only with: -FILEHEADER

-CU[RRENT_TN]=transaction_number

Changes the hexadecimal current transaction number for the current region.

Use only with: -FILEHEADER

-DATA[_RESERVED_BYTES]=data_reserved_bytes

Sets data reserved bytes. GT.M will not utilize whatever space is reserved in performing updates on data blocks in the database.

Use only with: -FILEHEADER

-DECLOCATION

Specifies an offset with the file header. If -VALUE is specified (in decimal), GT.M puts it at that location.

Use only with: -FILEHEADER

-E[NCRYPTION_HASH]

Changes the hash of the password stored in the database file header if and when you change the hash library. For more information on key management and reference implementation, refer to ChapterA 12: a??Database Encryptiona??.

[Caution]Caution

An incorrect hash renders the database useless.

Use only with: -FILEHEADER

-[NO]EPOCHTAPER

Sets a flag that indicates whether or not epoch tapering should be done. The default value is -EPOCHTAPER.

For more information, refer to a??Region Qualifiersa??.

-FL[USH_TIME][=delta_time]

Changes the flush_time default interval (in delta_time).

Use only with: -FILEHEADER

-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.

Use only with: -FILEHEADER

For information about a preferred method of manipulating FREEZE, refer to a??FREEZE a?? of the General Database Management chapter.

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

-FU[LLY_UPGRADED]=boolean

Sets a flag that indicates whether or not the database was fully upgraded from a prior version to the current database format. The value is either T[RUE] or F[ALSE].

Use only with: -FILEHEADER

-GV[STATSRESET]

Resets all the database file header global access statistics to 0. Note that this erases all statistics previously accumulated in the database file header.

Use only with: -FILEHEADER

-HEXLOCATION

Specifies a hexadecimal offset with the file header. If -VALUE is specified, GT.M puts it at that location.

Use only with: -FILEHEADER

-INDEX[_RESERVED_BYTES]=index_reserved_bytes

Sets index reserved bytes. GT.M will not utilize whatever space is reserved in performing updates on index blocks in the database.

Use only with: -FILEHEADER

-INT[ERRUPTED_RECOV]=boolean

Sets a flag that indicates whether or not a recovery with the MUPIP JOURNAL -RECOVER command was interrupted. The value is either T[RUE] or F[ALSE].

Use only with: -FILEHEADER

-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 ChapterA 4: a??Global Directory Editora??.

Use only with: -FILEHEADER

-KI[LL_IN_PROG]=value

Changes the value of the KILLs in progress field. The value can be "NONE" or a positive decimal integer.

Use only with: -FILEHEADER

-N[ULL_SUBSCRIPTS]=value

Controls whether GT.M accepts null subscripts in database keys.

Use only with: -FILEHEADER

-OV[ERRIDE]

Releases or "steals" a FREEZE owned by another process.

Use only with: -FREEZE

-[NO]Q[DBRUNDOWN]

Sets a flag that indicates whether or not the database is enabled for quick rundown. The default value is -NOQDBRUNDOWN.

For more information, refer to a??Region Qualifiersa??.

-REC[ORD_MAX_SIZE]=record_max_size

Changes the decimal value for the maximum allowable record size. Use the -RECORD_MAX_SIZE qualifier only in conjunction with the -FILEHEADER qualifier. Reducing RECORD_MAX_SIZE can restrict access to existing data and cause GT.M to report errors. Do not create incompatible key and record sizes.

Before making a permanent change to the records size using DSE, use GDE to check that the appropriate Global Directory contains the same record 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 ChapterA 4: a??Global Directory Editora??.

-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 an LMS environment, this sets the "Region Seqno" field. For more information, refer to ChapterA 7: a??Database Replicationa??.

-RESERVED_BYTES=reserved_bytes

Sets both data and index reserved bytes. GT.M will not utilize whatever space is reserved in a block.

Use only with: -FILEHEADER

-RESYNC_S[EQNO]=sequence-number

In an LMS environment, this sets the hexadecimal value of the "Resync Seqno" field. For more information, refer to ChapterA 7: a??Database Replicationa??.

-RESYNC_T[N]=sequence-number

In an LMS environment, this sets the hexadecimal value ofthe "Resync transaction" field. For more information, refer to ChapterA 7: a??Database Replicationa??.

-SPIN_SLEEP_MASK]=hexadecimal-mask

Changes the hexadecimal Spin sleep time mask that controls the maximum time in nanoseconds the process sleeps on a sleep spin; zero (0), the default causes the process to just yield to the OS scheduler.

Use only with: -FILEHEADER

-SLEE[P_SPIN_COUNT]=integer

Changes the hexadecimal Mutex Sleep Spin Count that controls the number of times a process waiting on a shared resource (usually a database) suspends its activity after exhausting its Mutex Hard Spin Count and before enquing itself to be awakened by a process releasing the resource

Use only with: -FILEHEADER

-[NO]STD[NULLCOL]

Changes the collation of empty string ("NULL") subscripts for the database file. Although it is not the default, STDNULLCOLL is required with certain other characteristics, and highly recommended in any case. If you change this when there are existing "NULL" subscripts the results may be problematic. FIS recommends you establish this characteristic with GDE and load data with a consistent setting.

Use only with: -FILEHEADER

-STRM_NUM=stream-number -STRM_R[EG_SEQNO]=str_num's_region_sequence_number

Changes the hexadecimal values of Stream and its Reg Seqno. Use -STRM_NUM and -STRM_REG_SEQNO together as part of the same CHANGE -FILEHEADER command.

Use only with: -FILEHEADER

-TI[MERS_PENDING]=timers_pending

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

Use the CHANGE -TIMERS_PENDING qualifier only upon receiving instructions from FIS.

Use only with: -FILEHEADER

-TO[TAL_BLKS]=total_blocks

Changes the hexadecimal total blocks field of the current file. Use only with: -FILEHEADER

[Caution]Caution

The total blocks field should always reflect the actual size of the database. Change this field only if it no longer reflects the database size.

-TR[IGGER_FLUSH]=trigger_flush

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

Use the CHANGE -TRIGGER_FLUSH qualifier only upon receiving instructions from FIS, and only in conjunction with the -FILEHEADER qualifier.

-WR[ITES_PER_FLUSH]=writes_per_flush

Set the decimal number of block to write in each flush. The default value is 7.

Use only with -FILEHEADER

Example:

DSE> change -block=3 -bsiz=400

This command changes the size of block 3 to 1024 bytes.

Example:

DSE> change -block=4 -tn=10000

This command changes sets the transaction number to 65536 (Hex: 10000) for block 4.

Example:

DSE> change -block=2 -record=4 -CMPC=10 -key="^CUS(""Jones,Vic"")"

This command changes the compression count of the key ^CUS(Jones,Vic) to 10. It is assumed that the key CUS(Jones,Tom) already exists. The following table illustrates how GT.M calculates the value of CMPC in this case.

Example:

DSE> dump -fileheader

This command displays fields of the file header.

Example:

DSE> change -fileheader -blk_siz=2048

This command changes the block size field of the fileheader to 2048 bytes. The block field must always be a multiples of 512 bytes.

Example:

DSE> change -fileheader -blocks_free=5B

This command changes the blocks free fields of the file header to 91 (Hex: 5B). Example:

Example:

DSE> change -fileheader -b_record=FF

This command sets the RECORD backup transaction to FF.

Example:

DSE> change -fileheader corrupt_file=FALSE

This command sets the CORRUPT_FILE field to false.

Example:

DSE> change -fileheader -current_tn=1001D1BF817

This command changes the current transaction number to 1100000000023 (Hex: 1001D1BF817). After you execute this command, subsequent transaction numbers will be greater than 1001D1BF817.

Example:

DSE> change -fileheader -flush_time=00:00:02:00
This command changes the flush time field of the file header to 2 seconds.

Example:

DSE> change -fileheader -freeze=true

This command makes the default region unavailable for updates.

Example:

DSE> change -fileheader -key_max_size=20

This command changes the maximum key size to 20. Note that the default max key size is 64.

Example:

DSE> CHANGE -FILEHEADER -NULL_SUBSCRIPTS="EXISTING"

This command changes the Null Subscripts field of the file header to EXISTING. Note that DSE cannot change the null subscript collation order. See GDE chapter for more information on changing the null subscript collation.

Example:

DSE> change -fileheader -record_max_size=496

This command sets the maximum record size as 496 for the default region.

Example:

DSE> change -fileheader -reference_count=5

This command sets the reference count field of the file header to 5.

Example:

DSE> change -fileheader -timers_pending=2

This command sets the timers pending field of the file header to 2.

Example:

DSE> change -fileheader -TOTAL_BLKS=64

This command sets the total size of the database to 100 (Hex: 64) blocks.

Example:

DSE> change -fileheader -trigger_flush=1000

This command sets the Flush Trigger field of the file header to 1000. Note the default value of Flush Trigger is 960.

Example:

DSE> change -fileheader -writes_per_flush=10

This command changes the number of writes/flush field of the file header to 10. Note that the default value for the number of writes/flush is 7.

Example:

DSE> change -fileheader -zqgblmod_seqno=FF

This command changes the ZGBLMOD_SEQNO field to 255(Hex: FF).

Operates on the cache of a database having BG access method. The format of the CACHE command is:

CA[CHE] 
[
-ALL
-RE[COVER]
-SH[OW]
-VE[RIFY]
] 

Example:

DSE> CACHE -VERIFY

This command checks the integrity of the cache data structures as well as the internal consistency of GDS blocks in the global buffers of the current region.

Example:

DSE> CACHE -VERIFY -ALL
Time 26-FEB-2011 14:31:30 : Region DEFAULT : Cache verification is clean
Execute CACHE recover command if Cache verification is "NOT" clean.

This command reports the state of database cache for all regions.

Example:

DSE> CACHE -RECOVER

This command reinitializes the cache data structures of the current region and reverts the cache of a database having BG access to "clean" state.

Example:

DSE> CACHE -SHOW
File    /home/jdoe/node1/areg.dat
Region  AREG
Region AREG : Shared_memory       = 0x00002B6845040000
Region AREG :  node_local         = 0x0000000000000000
Region AREG :  critical           = 0x0000000000010000
Region AREG :  shmpool_buffer     = 0x0000000000023000
Region AREG :  lock_space         = 0x0000000000125000
Region AREG :  cache_queues_state = 0x000000000012A000
Region AREG :  cache_que_header   = 0x000000000012A030 : Numelems = 0x00000407 : Elemsize = 0x00000098
Region AREG :  cache_record       = 0x0000000000150458 : Numelems = 0x00000400 : Elemsize = 0x00000098
Region AREG :  global_buffer      = 0x0000000000177000 : Numelems = 0x00000400 : Elemsize = 0x00000400
Region AREG :  db_file_header     = 0x0000000000277000
Region AREG :  bt_que_header      = 0x00000000002B7000 : Numelems = 0x00000407 : Elemsize = 0x00000040
Region AREG :  th_base            = 0x00000000002C71D0
Region AREG :  bt_record          = 0x00000000002C7200 : Numelems = 0x00000400 : Elemsize = 0x00000040
Region AREG :  shared_memory_size = 0x00000000002D8000
DSE>

Displays and/or modifies the status and contents of the critical section for the current region. The format of the CRITICAL command is:

CR[ITICAL] 
[
-A[LL] 
-I[NIT]
-O[WNER]
-REL[EASE]
-REM[OVE]
-RES[ET]
-S[EIZE]
]

-A[LL]

Display all ids of processes owning critical section from all regions. If there are no processes owning critical section in a region, ALL displays "the CRIT is currently unowned" message for each region.

-I[NIT]

Reinitializes the critical section.

Use only with: -RESET

-O[WNER]

Displays the ID of the process at the head of the critical section. DSE displays a warning message when the current process owns the critical section.

Use alone

Example:

DSE> critical -OWNER
Write critical section is currently unowned

-REL[EASE]

Releases the critical section if the process running DSE owns the section.

Use alone.

-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.

Use alone.

[Caution]Caution

Using CRITICAL -REMOVE when the write owner of a critical section is an active GT.M process may cause structural database damage.

-RES[ET]

Displays the number of times the critical section has been through an online reinitialization.

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.

Use only with: -INIT

-S[EIZE]

Seizes the critical section (if available).

Displays blocks, records, or file headers. DUMP is one of the primary DSE examination commands.

The format of the DUMP command is:

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

Use the error messages reported by MUPIP INTEG to determine what to DUMP and examine in the database. DUMP also can transfer records to a sequential file for future study and/or for input to MUPIP LOAD (see the section on OPEN). The DUMP command requires specification of an object using either -BLOCK, -HEADER, -RECORD, or -FILEHEADER.

-A[LL]

When used with -FILEHEADER, the -A[LL] qualifier displays additional information on the database most of which is useful for FIS in diagnosing issues. A complete description of all the elements that show up with the DSE DUMP -FILEHEADER -ALL command are beyond the scope of this book.

Meaningful only with: -FILEHEADER

-B[LOCK]=block-number

Specifies the starting block of the dump. For commands without an object 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).

Incompatible with: -ALL, -FILEHEADER and -UPDPROC.

-C[OUNT]=count

Specifies the number of blocks, block headers, or records to DUMP.

Incompatible with: -ALL, -FILEHEADER and -UPDPROC.

-F[ILEHEADER]

Dumps file header information. A DSE dump of a database file header prints a 0x prefix for all fields printed in hexadecimal format. Refer to the "Introduction" section for a description of the file header fields.

Use only with -ALL or -UPDPROC

-G[LO]

Dumps the specified record or blocks into the current output file in Global Output (GO) format. FIS strongly suggests using -ZWR rather than -GLO as the ZWR format handles all possible content values, including some that are problematic with -GLO.[The GLO format is not supported for UTF-8 mode - use the ZWR format with UTF-8 mode.

Incompatible with: -ALL, -FILEHEADER, -UPDPROC and -ZWR.

-G[VSTATS]

Displays the access statistics for global variables and database file(s).

-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.

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

Incompatible with: -ALL, -FILEHEADER, -GLO, -UPDPROC and -ZWR.

-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 beginning of the record containing offset 10).

Incompatible with: -ALL, -FILEHEADER, and -RECORD.

-R[ECORD]=record_number

Specifies the record number of the starting record of the dump. 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.

Incompatible with: -ALL, -FILEHEADER, and -OFFSET.

-U[PDPROC]

Displays the helper process parameters with the fileheader elements.

Use only with -FILEHEADER.

-Z[WR]

Dumps the specified record or blocks into the current output file in ZWRITE (ZWR) format.

Incompatible with: -ALL, -GLO, -HEADER and -FILEHEADER.

Example:

DSE> DUMP -FILEHEADER

This command displays an output like the following:

File    /home/jdoe/.fis-gtm/V7.1-002_x86_64/g/gtm.dat
Region  DEFAULT
File            /home/jdoe/.fis-gtm/V7.1-002_x86_64/g/gtm.dat
Region          DEFAULT
Date/Time       12-SEP-2023 17:31:20 [$H = 66729,63080]
  Access method                           BG  Global Buffers                  1024
                                              Block size (in bytes)           4096
  Maximum record size                    256  Starting VBN                    8193
  Maximum key size                        64  Total blocks      0x0000000000000065
  Null subscripts                      NEVER  Free blocks       0x0000000000000062
  Standard Null Collation              FALSE  Free space                0x00000000
  Last Record Backup      0x0000000000000001  Extension Count                  100
  Last Database Backup    0x0000000000000001  Number of local maps               1
  Last Bytestream Backup  0x0000000000000001  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
  Freeze online                        FALSE  Freeze online autorelease      FALSE
  Current transaction     0x0000000000000001  No. of writes/flush                7
  Maximum TN              0xFFFFFFF803FFFFFF  Certified for Upgrade to          V7
  Maximum TN Warn         0xFFFFFFD813FFFFFF  Desired DB Format                 V7
  Master Bitmap Size                    8176  Blocks to Upgrade 0x0000000000000000
  Create in progress                   FALSE  Modified cache blocks              0
  Reference count                          1  Wait Disk                          0
  Journal State                [inactive] ON  Journal Before imaging          TRUE
  Journal Allocation                    2048  Journal Extension               2048
  Journal Buffer Size                   2312  Journal Alignsize               4096
  Journal AutoSwitchLimit            8386560  Journal Epoch Interval           300
  Journal Yield Limit                      8  Journal Sync IO                FALSE
  Journal File: /home/jdoe/.fis-gtm/V7.0-002_x86_64/g/gtm.mjl
  Mutex Hard Spin Count                  128  Mutex Sleep Spin Count           128
  Mutex Queue Slots                     1024  KILLs in progress                  0
  Replication State                      OFF  Region Seqno      0x0000000000000001
  Zqgblmod Seqno          0x0000000000000000  Zqgblmod Trans    0x0000000000000000
  Endian Format                       LITTLE  Commit Wait Spin Count            16
  Database file encrypted              FALSE  Inst Freeze on Error           FALSE
  Spanning Node Absent                  TRUE  Maximum Key Size Assured        TRUE
  Defer allocation                      TRUE  Spin sleep time mask      0x00000000
  Async IO                               OFF  WIP queue cache blocks             0
  DB is auto-created                   FALSE  DB shares gvstats               TRUE
  LOCK shares DB critical section      FALSE  Read Only                        OFF
  Recover interrupted                  FALSE  Full Block Write                   0
  StatsDB Allocation                    2050
  Data Reserved Bytes                      0  Index Reserved Bytes               0

Note that the certain fileheader elements appear depending on the current state of database. For example, if Journaling is not enabled in the database, DSE does not display Journal data element fields.

Example:

$ dse dump -fileheader -updproc

This command displays the fileheader elements along with the following helper process parameters:

Upd reserved area [% global buffers]     50  Avg blks read per 100 records          200
Pre read trigger factor [% upd rsrvd]    50  Upd writer trigger [%flshTrgr]          33

For more information, refer to the fileheader elements section in a??GT.M Database Structure(GDS)a??.

Locates a given block or 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]
-SI[BLINGS]
-ST[ATS]
]

-B[LOCK]=block_number

Specifies the block to find.

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).

Incompatible with: -KEY, -REGION

-E[XHAUSTIVE]

Searches the entire index structure for the desired path or siblings.

[Note]Note

A doubly allocated block may cause inappropriate mingling of data. As long as no KILLs occur, double allocation may not cause permanent loss of additional data. However, it may cause the application programs to generate errors and/or inappropriate results. When a block is doubly allocated, a KILL may remove data outside its proper scope. See "Maintaining Database Integrity Chapter" for more information on repairing doubly allocated blocks.

Incompatible with: -KEY, -REGION, -FREEBLOCK

-F[REEBLOCK]

Finds the nearest free block to the block specified by -HINT. FREEBLOCK accepts bit maps as starting or ending points.

Required with -HINT; compatible with -BLOCK and [NO]CRIT.

-H[INT]=block_number

Designates the starting point of a -FREEBLOCK search.

FIND -FREE -HINT locates the "closest" free block to the hint. This provides a tool for locating blocks to add to the B-tree, or to hold block copies created with SAVE that would otherwise be lost when DSE exits. FIND -FREE relies on the bitmaps to locate its target, so be sure to fix any blocks incorrectly marked "FREE" before using this command.

Required with: -FREEBLOCK; compatible with -BLOCK and [NO]CRIT.

-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.

Compatible only with [NO]CRIT.

-[NO]C[RIT]

Allows FIND to work even if another process is holding a critical section.

As 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.

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

Use Alone.

-SI[BLINGS]

Displays the block number of the specified block and its logical siblings in hexadecimal format.

The logical siblings are the blocks, if any, that logically exist to the right and left of the given block in the database tree structure.

Incompatible with: -FREEBLOCK, -HINT, -KEY, -REGION

-ST[ATS]

Switches to the named Global Directory shadow for the region's shared gvstats.

Compatible only with R[EGION].

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.

Example:

DSE> MAPS -BLOCK=20 -FREE

This command flags block 20 as free. A sample DSE DUMP output block 0 is as follows:

Block 0  Size 90  Level -1  TN 10B76A V7   Master Status: Free Space
                Low order                         High order
Block        0: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block       20: |  :XXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block       40: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block       60: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block       80: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block       A0: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block       C0: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block       E0: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block      100: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block      120: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block      140: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block      160: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block      180: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block      1A0: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block      1C0: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
Block      1E0: |  XXXXXXXX  XXXXXXXX  XXXXXXXX  XXXXXXXX  |
'X' == BUSY  '.' == FREE  ':' == REUSABLE  '?' == CORRUPT

Note that BLOCK 20 is marked as REUSABLE, which means FREE but in need of a before-image journal record.

Example:

DSE> maps -block=20 -busy

This command marks block 20 as busy. A sample DSE DUMP output of block 0 is as follows:

Block 0  Size 90  Level -1  TN 1 V7   Master Status: Free Space
                Low order                         High order
Block        0: |  XXX.....  ........  ........  ........  |
Block       20: |  X.......  ........  ........  ........  |
Block       40: |  ........  ........  ........  ........  |
Block       60: |  ........  ........  ........  ........  |
Block       80: |  ........  ........  ........  ........  |
Block       A0: |  ........  ........  ........  ........  |
Block       C0: |  ........  ........  ........  ........  |
Block       E0: |  ........  ........  ........  ........  |
Block      100: |  ........  ........  ........  ........  |
Block      120: |  ........  ........  ........  ........  |
Block      140: |  ........  ........  ........  ........  |
Block      160: |  ........  ........  ........  ........  |
Block      180: |  ........  ........  ........  ........  |
Block      1A0: |  ........  ........  ........  ........  |
Block      1C0: |  ........  ........  ........  ........  |
Block      1E0: |  ........  ........  ........  ........  |
'X' == BUSY  '.' == FREE  ':' == REUSABLE  '?' == CORRUPT

Note that the BLOCK 20 is marked as BUSY.

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                
]

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.

-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).

BLOCK accepts blocks higher than the current database size because they deal with set of saved block copies rather than the database and there are situations where a saved block may be outside the current database size (for example, due to a concurrent MUPIP REORG -TRUNCATE).

-C[OUNT]=count

Specifies the number of records to remove.

By default, REMOVE deletes a single record.

Incompatible with: -VERSION

-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 beginning of the record containing the offset (for example, REMOVE -OFF=10 starts at OFF=A if that was the last prior record boundry).

Incompatible with: -VERSION, -RECORD

-R[ECORD]=record_number

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

Incompatible with: -VERSION, -OFFSET

-V[ERSION]=version_number

Specifies the version number, in decimal, of the save buffer to remove. If there are more than one version of a block, -VERSION is required; otherwise REMOVE works on that sole version. -VERSION is incompatible with all qualifiers except -BLOCK.

If there is only one version of the specified -BLOCK= block in the current region, DSE REMOVE defaults to that version.

Use only with: -BLOCK; decimal

The SAVE command preserves versions of blocks, or displays a listing of saved versions for the current DSE session. SAVE can preserve 128 versions. 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]
]
loading table of contents...