#18 Reblocking Collections in JADE 7.0

[Jade Support]

Reblocking Collections in JADE 7.0

The bulk of what follows is available in the JADE 7.0.04 Release Info document. The difference being that this article covers the reasons behind why it’s recommended to reblock collections following database migration to JADE 7.0.

Background
JADE collections are composite objects comprised of a collection header and one or more collection blocks that may vary in size. For all collection types, the first block is instantiated with a size sufficient to contain exactly four entries [1]. As entries are added to the collection, the collection block grows in increments up to a system determined size limit. This size limit can be influenced by user specified tuning parameters: “Entries Per Block” or “Expected Population”.

In JADE 7, database files are organized as a sequence of 8K byte disk blocks, which is the basic unit of I/O and free-space management. As a consequence of this, the rules for determining the default maximum size for collection blocks have been changed to provide better alignment with the new database block structure.

When a 6.3 database is migrated to the new JADE 7 structure, collection blocks are not restructured to conform to the new alignment rules. This may result in sub-optimal space utilisation or performance characteristics in some cases.

[1] In the 6.3 release, where a user has specified an “Entries Per Block” value for a collection type, it’s collection blocks are allocated to this size up front.

Reblocking Collections
To optimise this and improve access efficiency and space utilisation of the JADE map files you can reblock all collections in one or more map files by using the JadeCollectionReblocker application. This is executed via the non-GUI client (jadclient.exe) program in single user or multiuser mode, e.g.

Code: Select all

jadclient.exe path=database-path ini=jade-initialization-file server=SingleUser|MultiUser schema=user-schema-name app=JadeCollectionReblocker File=file-name|mask [File2=file-name [File3=file-name]...] [workers=number-of-worker-threads]

The file-name value is a complete map file name or a partial map file name with a trailing asterisk; for example, cust* means all map files that begin with the letters cust. Specify the file-name mask * (a single asterisk) to indicate reblocking of all user files, including rootdef. Specify the mask _* (underscore asterisk) to indicate the reblocking of all system files such as _userscm.

The user-schema-name parameter is any user schema, e.g. CardSchema.

The following are examples of the reblocking action.

jadclient path=d:\jadeuser ini=d:\salesdb\jade.ini schema=Sales server=singleUser app=JadeCollectionReblocker File=*

jadclient path=d:\jadeuser ini=d:\salesdb\jade.ini schema=Sales server=singleUser app=JadeCollectionReblocker File1=testdb File2=banking File3=_userdev workers=5

The optional workers parameter enables you to specify the number of multiple concurrent worker threads that are used. The default value of 1 is used if you do not specify the workers parameter. You can specify a value in the range 1 through 16. If you specify a value greater than 16, the maximum number of 16 worker threads is used.

Reblocking is done in normal update transactions, which are committed every 1,000 collections or 30 seconds.

Reblocking skips collections that do not require reblocking. The JadeCollectionReblocker application can be terminated part way through a file, in which case only uncommitted changes are discarded. When reblocking is restarted for the same file, collections that have already been reblocked are skipped.

Note: collection reorganisation will also reblock the affected collection(s). If you intend on reorging specific collections their map files could be omitted from the collection reblocking process to reduce it's work load.