Question & Answer
Question
What is the IBM® Rational® ClearCase® string_report utility used for and where can it be found on Microsoft® Windows®, Linux® and UNIX®?
Answer
Where String report is located
Introduction to string_report
The string_report utility is a read only tool that reports the count of the various records in the VOB database string file.
The string file contains records such as
- Config records (from clearmake, omake or clearaudit builds)
- UCM stream config specs
- All streams pre- ClearCase 7.0
- ClearCase 7.0 - shared streams only.
- MultiSite Oplogs
Other objects stored in the string file depending on its size:
- Any object that has a name greater than 89 characters long.
- Any comment greater than 89 characters long.
- Event information such as comments, host, user and group etc...
- View information such as host, local path, uuid
- Attribute string values.
- Trigger information
- Trigger lock -nusers information.
- Trigger restriction and action (-exec, -execwin, -execunix) information.
- Symbolic link paths.
- UCM information
- Which view is set to an activity
- Which views use a stream
- UCM Activity timeline information.
- UCM Baseline information.
- UCM Process Variables (PVARs)
- Host information for MultiSite replicas.
Note: This is not a complete list of where ClearCase uses string objects or directly stores information in the string file.
The string_report utility is useful for analyzing the VOB database string file to determine how space is being used within it. The string_report utility is often used in conjunction with the countdb utility.
The output is really useful for schema 53 VOBs which have a limitation imposed on the maximum string file length (2GB).
Depending on what is filling up the database, there are various actions you can take to make space.
Examples:
- High number of CONFIG_REC objects:
** Remove derived objects and run scrubber -e
Location of string_report
The string_report utility comes installed with ClearCase. The string_report utility is stored in the etc utils directory.
UNIX® and Linux®:
2003.06 and later:
/opt/rational/clearcase/etc/utils
2002.05.00 and earlier
/usr/atria/etc/utils
Microsoft® Windows®
C:\Program Files\Rational\ClearCase\etc\utils
Instructions
Note: You must be logged in as root, administrator or ClearCase privileged from within the db directory.
1. Change to the db directory of the VOB to be checked.
2. Run the command string_report.
Example:
UNIX (schema 53 VOB):
/vobstore/myvob-vob.vbs:-> cd db
/vobstore/myvob-vob.vbs/db:-> /usr/atria/etc/utils/string_report
String File Statistics
======================================================
record type # records string file bytes
-------------------- --------- -----------------
STRING (no overflow) 444 0
STRING (overflow) 245 26571
CONFIG_REC 2 2
------------------------------------------------------
Bytes in use 26571
STR_FREE 10 75
------------------------------------------------------
Total string file size (DB) 26646
Total string file size (OS) 29871
------------------------------------------------------
Max possible string file size 2147483647
Longest free string length 2147457001
Note the string file size and length cannot exceed 2GB with Schema 53.
Windows (schema 54 VOB):
C:\ClearCase_Storage\VOBs\test_vob.vbs\db>string_report
***WARNING: No CONFIG_REC records found!!
String File Statistics
======================================================
record type # records string file bytes
-------------------- --------- -----------------
STRING (no overflow) 122 0
STRING (overflow) 4 61
CONFIG_REC 0 0
------------------------------------------------------
Bytes in use 61
STR_FREE 0 0
------------------------------------------------------
Total string file size (DB) 61
Total string file size (OS) 969
------------------------------------------------------
Max possible string file size 9223372036854775807
Longest free string length 9223372036854775746
Note the increased string file size and length is over 2GB with Schema 54.
About string_report output
The string_report output reports the output for particular sections in the string file:
| STRING (no overflow) | String records that are stored in the VOB database files vob_db.d0* |
| STRING (overflow) | Strings that are stored in the string file (vob_db.str_file) and their size in bytes. |
| CONFIG_REC | The number of configuration records (created from clearmake, omake or clearaudit) and their related size in bytes stored in the string file (vob_db.str_file). |
| Bytes in use | The amount of space in bytes that is in use and not on the free list (STR_FREE) as represented in the database. |
| STR_FREE | The amount of free space or gaps in the *CURRENT* string size as represented in the database. |
| Total string file size (DB) | The size of the string file (sum of the Bytes in use and STR_FREE) as represented by the VOB database |
| Total string file size (OS) | The size of the string file (vob_db.str_file) in bytes as represented by the operating system. |
| Max possible string file size | The maximum possible size (in bytes) the string file (vob_db.str_file) can grow:
|
| Longest free string length | The maximum size a single string length can be recorded in the string file:
|
The STR_FREE value represents the open gaps in the string file that can be filled with data before the file becomes full; much the same way disk fragmentation is represented. As the STR_FREE value reaches 0, it will create a larger string as needed.
The following example output shows there are 491 records on the STR_FREE list with gaps that can be filled up to 3897720 bytes of space.
record type # records string file bytes
-------------------- --------- -----------------
STRING (no overflow) 645291 0
STRING (overflow) 155794 337278641
CONFIG_REC 153517 1828301489
------------------------------------------------------
Bytes in use 2165580130
STR_FREE 491 3897720
------------------------------------------------------
Total string file size (DB) 2169477850
Total string file size (OS) 2169490634
------------------------------------------------------
Max possible string file size 9223372036854775807
Longest free string length 9223372034685285173
When the STR_FREE value reaches 0, the string file will become larger (as needed).
Note: In some cases the string file can grow before the STR_FREE value becomes 0. This can occur where the free gaps on the STR_FREE list are smaller than the information needing to be written to the string file.
Warnings & Errors
Below is a list of known warnings or errors that may be encountered either within the output or when executing the string_report utility.
***WARNING: No CONFIG_REC records found!!
The output of string_report may produce a waning that reports No CONFIG_REC records found (as seen in the example above). This warning is merely stating there are no config records found in the string file. Config records are only stored in the string file as a result of clearmake, omake or clearaudit builds.
If you are not using these utilities, there will never be config records stored in your string file, this the warning can be ignored.
If you are using one or more of these utilities
- The VOB may have been recently created and no config records have been created yet (ignore if applicable)
- There may not be any stored config records in that VOB (ignore if applicable)
- All of the config records may have been removed and or scrubbed (investigate and ignore if applicable)
*** Can't find schema version file! ***
Attempts to run the string_report utility results in the error:
C:\ClearCase_Storage\VOBs\test_vob.vbs>string_report
*** Can't find schema version file! ***
This error occurs because the utility was not executed from within the db directory of the VOB.
Make sure you are set into the db directory of the VOB.
Related Information
Was this topic helpful?
Document Information
Modified date:
16 June 2018
UID
swg21146552