INFO: IBM i System Debugger not stopping on breakpoints
=======================================================
This is a post inspired by two past posts which did not find a correct solution:
"ACS System Debugger doesn't want to work"
https://archive.midrange.com/midrange-l/202210/msg00244.html
and
"System Debugger"
https://archive.midrange.com/midrange-l/202306/msg00321.html
Both posts describe the problem that System Debugger wouldn't stop on breakpoints (with the breakpoints briefly flashing in yellow).
I also observed this, on a local V7.2 system and on PUB400 V7.5
Quick Answer:
-------------
The debugging user needs *JOBCTL special rights for this to work.
This applies to debugging option "Submit and debug program in batch job"
N.B.:
PUB400 won't allow *JOBCTL - for a good reason, see below - so this won't work until (hopefully) IBM fixes this.
Analysis and Details:
---------------------
- System Debugger starts a server job QTESDBGSVR for each debug connection, running under
the user profile specified by the client.
- When debug for a particular program is started (in SUBMIT mode), QTESDBGSVR submits another
job which in turn calls the debugged program.
- To analyse this, I created a user profile similar to that on PUB400 on my local system,
which is a user profile without any special rights, and with the documented debug
requirements, which are *USE rights to the STRDBG, ENDDBG STRSRVJOB, ENDSRVJOB commands.
- Starting a System Debugger debug session, setting breakpoints and starting debug immediately exhibited the problem:
Break points were not obeyed; program runs to completion.
- Checking the QTESDBGSVR job log, I discovered two messages for each and every breakpoint skipped:
MCH1004 Thread is not authorized to perform instruction requiring a special authority.
folowed by
CEE9901 Application error. MCH1004 unmonitored by QC2UTIL1 at statement 0000000004, instruction X'0000'.
The application ended abnormally because an exception occurred and was not handled.
The name of the program to which the unhandled exception is sent is QC2UTIL1 QC2MI2 matpratr.
The "matpratr" in the second message represents the MI instruction MATPRATR - Materialize Process Attributes
(very probably hidden underneath the equivalent C MI API function)
There is no documented mapping from MCH messages to MI exceptions I know of,
but there is one single post by Junlei Li with an important clue:
https://www.mcpressonline.com/programming/rpg/the-transfer-ownership-xfro-mi-instruction
"... MCH1004 (i.e., the Special Authorization Required (hex 0A04)) exception. "
So, we are getting a 0A04 MI exception during MATPRATR.
IBM document "Machine Interface Exceptions" describes 0A04 as:
0A04 Special Authorization Required
An attempt has been made to execute an instruction requiring special
authorization. The user profiles that provide authorization for the
thread do not have the proper authorization.
I suspected a missing *JOBCTL special authority (although somewhat odd, because a user
normally does have rights to his own jobs anyways).
- CHGUSRPRF SPCAUT(*JOBCTL) immediately fixed the problem - breakpoins were obeyed.
Further thoughts and findings
-----------------------------
1a) Don't be misled by statements in other APR/PTFs
Other APAR/PTF texts say "MCH1004 is correctly issued in the joblog...", but that is misleading.
Those APARs/PTFs are really only about unnecessary problem log entries, not about the cause of MCH1004 itself.
1b) It has nothing to do with VPN connection.
The statement that a VPN connection is required to use System Debugger successfully (for systems
hooked up directly to the internet) is not true.
System Debugger client does not open any server ports, nor uses random ports, so there can't be
much technical justification for that. (I used MS SysInternals TcpView to check).
2) MATPRATR requires *JOBCTL special authority even for jobs submitted by the same user
The documentation about the MATPRATR MI instruction says;
Authorization Required
Process control special authorization
For materializing a process other than the one containing the thread issuing this instruction
Execute
Contexts referenced for address resolution
This is remarkable -
MATPRATR without *JOBCTL special authority works only for threads in the same job,
not from a different job - not even when the user profile is the same.
3) Debugger principles of operation
It seems like QTESDBGSVR tries to control the execution of the job it submitted to run the
debugged program and make it stop at breakpoints, using MATPRATR during the course of this.
MATPRATR without *JOBCTL special authority will fail with MCH1004.
*** Was the debugger originally designed to use threads to start the debugged program?
That way, everything would work properly.
The question also arises, what for QTESDBGSVR needs to do MATPTRADR in the first place;
STRSRVJOB + STRDBG don't seem to need it either - it is no problem to issue STRSRVJOB and STRDBG
without *JOBCTL special authority (for jobs under the same user); and what else but STRSRVJOB
(for a job that it itself submitted!), TRDBG, DSPMODSRC and ADDBKP etc would QTESDBGSVR need to do?
4) Documentation errors
IBM's Document "Development tools - IBM i Debugger"
https://www.ibm.com/docs/en/ssw_ibm_i_72/rzamq/rzamqpdf.pdf
(V7.2 net five pages and never updated) is worthless.
IBM's Documentation about System Debugger (an RDi document)
https://www.ibm.com/docs/en/rdfi/9.6.0?topic=debugger-authorities-required-debugging
states:
"
Authorities required for debugging
The IBM® i user profile that you use to sign on in the workbench IBM i logon dialog must have the following authorities:
*USE authority to the Start Debug (STRDBG) command.
*USE authority to the End Debug (ENDDBG) command.
*USE authority to the Start Service Job (STRSRVJOB) command.
*USE authority to the End Service Job (ENDSRVJOB) command.
Either *CHANGE authority to the program or Java class being debugged,
or *USE authority to the program being debugged and *SERVICE special authority.
If the job that you are debugging is running under a different user profile than
the user profile you use to sign on to the IBM i computer from the debugger,
the user profile that you use to sign on to the IBM i computer from the debugger
must have the following authorities:
*USE authority to the user profile that the job you are debugging is running under.
*JOBCTL special authority if you do not explicitly use fully qualified program names (library/program).
In other words, if you use *CURLIB or *LIBL or you do not specify a library name, you need to have *JOBCTL
special authority.
The group profile QPGMR gives you the correct authority to the STRDBG, ENDDBG, STRSRVJOB, and ENDSRVJOB commands
and *JOBCTL special authority.
"
USRPRF QPGMR does have *JOBCTL (and *SAVSYS) special authority indeed.
(By today's standards a bit generous, but that's beside the point currently; Nore or
less a carry-over from S/38 that couldn't be dropped because of QPGMR often being used as a group profile)
There is no mention of any *JOBCTL requirement for the case of "Submit and debug program in batch job".
The part about *JOBCTL special authority is misleading / incomplete / incorrect -
Why should *JOBCTL be required to find then execute a program through the library list?
I believe whoever outlined this documentation got confused over the documentation of the MATPRATR
MI instruction, which reqires Execute rights for "Contexts referenced for address resolution":
A Context in MI terminology is - in practice - a library.
GRTOBJAUT help text reads:
"Execute authority provides the authority needed to run a program or locate an object in a library."
which is correct. The confusion happened by mis-reading the doc about MATPRATR (see my point 2) above)
5) Is there justification to issue a PMR?
I think there would be. It is not acceptable to require *JOBCTL special rights for a programmer to be able to
use System Debugger. *JOBCTL special right would enable him to - even inadvertantly - cancel a job other
than his own on the system. It is not necessary either - STRSRVJOB + STRDBG don't need it either.
I can't be asking to change the beahaviour of MATPRATR of course, but nonetheless, the requirement for *JOBCTL
special authority for debugging seems overdrawn to me.
I am, however, pessimistic about IBM to be willing to alter the debugger to use threads internally
(which would be the best solution, satisfying MATPRATR requirements; and I personally can't see any technical hindrances to that);
But then again, what does QTESDBGSVR need MATPRATR for in the first place? Maybe QTESDBGSVR's internal requirement for
MATPRATR can be avoided?
The way I know IBM these days, I believe they would staunchly promise to correct documentation for System Debugger
to require *JOBCTL special authority. Oh well ...
Concluding with mixed feelings -
Wilhelm Stanzl
---
midrange.com
