cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

undocumented commands & options

tketz
4-Participant

undocumented commands & options

Hi,

i want to make a list for undocumented (hidden) commands. There are many options for the diag command which are not documented like

im/si diag --diag=restart (restarts server)

im diag --diag=fixcpservers --hostname=<aktueller Rechner> --param=<alter Rechner>:<alte Portnummer> --param=<neuer Rechner>:<neue Portnummer> (Change CP servername after changing hostname)

im/si diag --diag=licenses (get an overview about used licenses)

im/si mm -g (display Memory Monitor for client and/or server)

im/si diag --diag=runsql (to direct run sql commands)

im diag --diag=slowqueries (to find slow queries for SQL tuning)

im diag --diag=querieplan (for SQL tuning)

--import option for many commands (to set field-values without transition check)

Also the "gateway" command is undocumented. i know the following options:

gateway retrieve --documentID="id" (or --query="query") --map="mapping exporter" --iif=outpufile.xml

i think that there are many other commands which are very useful for administrators bot not documented.

one command i'm searching for is to open the server log and tail it. In the Admin-GUI i can view the server log without open the log file on the server. I think there must be a diag-option to do the same from the CLI. When i have the command maybe i can tail it.

it would be nice to have a list of other undocumented commands and options 🙂

1 ACCEPTED SOLUTION

Accepted Solutions
JoeBartlett
20-Turquoise
(To:tketz)

This is where things start to get dangerous. Most of the commands mentioned above are fairly harmless and in fact, PTC support provides them to customers all the time. Many actually are documented, just not all in the same place, though undocumented commands are not tested in any official capacity and the results of the commands are not guaranteed to be consistent or safe. I will add my comments about each to hopefully give a better understanding of them:

im/si diag --diag=restart

Even I was not aware of this command! Never tested, but this one is probably harrmless unless run by accident. Then users will complain until the server comes back online.

im diag --diag=fixcpservers

This command can be found in this article for moving Integrity to new hardware or making some hardware changes. This can cause an admin staging lock to break and you could lose data if you have to restore the Staging database from a copy of Prod in order to re-establish the link.

im/si diag --diag=licenses

This one is harmless and has long been recommended by Support as a way for customers to get a view of their license usage. Now that we provide PSM for monitoring the Integrity Server, you can see nice charts for license usage instead of relying on the CLI or GUI output.

im/si mm -g

This one is mostly harmless except it has a button labeled "Reclaim". This sounds like it would clean-up unused Heap memory and it does... by triggering a Full Garbage Collection! Any of our customers with a heavily used server will know how bad a FullGC is when it becomes too frequent as Java Garbage Collections (in Integrity 10.4 and previous) cause all threads to pause and no operations complete until the clean-up finishes. This is sometimes a useful memory monitoring tool, but make sure not to hit Reclaim!!!

im/si diag --diag=runsql

This is extremely dangerous and should not be used without the direct supervision of PTC Support! Using this on your own violates the Terms of Service agreed upon with PTC! From the Customer Support Guide:

"Integrity configurations which have had any manipulation to the data or schema of the database used by the Integrity Server which were not done through documented product commands or were not provided or approved by PTC Technical Support, or PTC Development will not be supported."

This allows direct manipulation of the Integrity database and even a well-intentioned typo can cause data loss or corrption. This cannot be stressed enough!

im diag --diag=slowqueries

This is a very helpful diagnostic tool for finding which queries are reported to be slow. No harm in running this.

im diag --diag=queryplan

im diag --diag=chartplan

im diag --diag=sqlplan

These 3 commands do roughly the same thing - allow you to get a query execution plan from the database for a given query. Queryplan allows you to provide the name of a query (ie "UserX:My Defects"). Chartplan allows you to get the plan for the query which a given chart uses. Sqlplan is a bit more powerful in that you can provide the raw SQL query to get the plan (ie --param="SELECT ID,Name FROM Fields"). Mostly usd when PTC Support is diagnosing slow operations like queries, item edits, etc.

--import option

This is another VERY dangerous command option since it can appear to create corruption in the data set. Do not use this!

gateway retrieve --documentID="id" (or --query="query") --map="mapping exporter" --iif=outpufile.xml

The gateway command is document in the Gateway User Guide (see pages 23-26 in the 10.5 version).

In summary, most undocumented commands may not be harmful but are not tested in any way and cannot be relied upon to return accurate or consistent results. In the worst cases, they can cause data corruption, data loss, or unintended consequences. Please check with PTC Support before attempting to run any undocumented command.

View solution in original post

1 REPLY 1
JoeBartlett
20-Turquoise
(To:tketz)

This is where things start to get dangerous. Most of the commands mentioned above are fairly harmless and in fact, PTC support provides them to customers all the time. Many actually are documented, just not all in the same place, though undocumented commands are not tested in any official capacity and the results of the commands are not guaranteed to be consistent or safe. I will add my comments about each to hopefully give a better understanding of them:

im/si diag --diag=restart

Even I was not aware of this command! Never tested, but this one is probably harrmless unless run by accident. Then users will complain until the server comes back online.

im diag --diag=fixcpservers

This command can be found in this article for moving Integrity to new hardware or making some hardware changes. This can cause an admin staging lock to break and you could lose data if you have to restore the Staging database from a copy of Prod in order to re-establish the link.

im/si diag --diag=licenses

This one is harmless and has long been recommended by Support as a way for customers to get a view of their license usage. Now that we provide PSM for monitoring the Integrity Server, you can see nice charts for license usage instead of relying on the CLI or GUI output.

im/si mm -g

This one is mostly harmless except it has a button labeled "Reclaim". This sounds like it would clean-up unused Heap memory and it does... by triggering a Full Garbage Collection! Any of our customers with a heavily used server will know how bad a FullGC is when it becomes too frequent as Java Garbage Collections (in Integrity 10.4 and previous) cause all threads to pause and no operations complete until the clean-up finishes. This is sometimes a useful memory monitoring tool, but make sure not to hit Reclaim!!!

im/si diag --diag=runsql

This is extremely dangerous and should not be used without the direct supervision of PTC Support! Using this on your own violates the Terms of Service agreed upon with PTC! From the Customer Support Guide:

"Integrity configurations which have had any manipulation to the data or schema of the database used by the Integrity Server which were not done through documented product commands or were not provided or approved by PTC Technical Support, or PTC Development will not be supported."

This allows direct manipulation of the Integrity database and even a well-intentioned typo can cause data loss or corrption. This cannot be stressed enough!

im diag --diag=slowqueries

This is a very helpful diagnostic tool for finding which queries are reported to be slow. No harm in running this.

im diag --diag=queryplan

im diag --diag=chartplan

im diag --diag=sqlplan

These 3 commands do roughly the same thing - allow you to get a query execution plan from the database for a given query. Queryplan allows you to provide the name of a query (ie "UserX:My Defects"). Chartplan allows you to get the plan for the query which a given chart uses. Sqlplan is a bit more powerful in that you can provide the raw SQL query to get the plan (ie --param="SELECT ID,Name FROM Fields"). Mostly usd when PTC Support is diagnosing slow operations like queries, item edits, etc.

--import option

This is another VERY dangerous command option since it can appear to create corruption in the data set. Do not use this!

gateway retrieve --documentID="id" (or --query="query") --map="mapping exporter" --iif=outpufile.xml

The gateway command is document in the Gateway User Guide (see pages 23-26 in the 10.5 version).

In summary, most undocumented commands may not be harmful but are not tested in any way and cannot be relied upon to return accurate or consistent results. In the worst cases, they can cause data corruption, data loss, or unintended consequences. Please check with PTC Support before attempting to run any undocumented command.

Announcements