There is an open source package (opensc) which provides access to smart cards and external keystores. It provides some good tools for diagnosing problems.
There is a wiki with good information.
Opensc return codes are here, and the printable text is here
Monitor traffic to and from the device.
You can monitor the traffic to and from the device by using an intermediate “spy” module which displays the traffic.
In your configuration (for example a CCDT), where you specified the name of the module /usr/lib64/pkcs11/opensc-pkcs11.so, replace this with /usr/lib64/pkcs11/pkcs11-spy.so. Specify the environment variable
The spy module is invoked, prints out the parameters, and then invokes the module specified in the environment variable.
The output is like
[in] hSession = 0x21fc030
[in] userType = CKU_USER
[in] pPin[ulPinLen] 00000000021fb2a0 / 8
00000000 5B C7 E7 BB E5 FC 6A BE […..j.
Returned: 160 CKR_PIN_INCORRECT
Detailed internal trace
You can specify the environment variable OPENSC_DEBUG to give a very detailed trace. The higher the number the more detailed the trac.
and use unset OPENSC_DEBUG to reset it.
You can use OPENSC_CONF to specify a configuration file with more parameters, such as file name for the output.
The output from this trace (showing a logon with pin number 12345678) is like
0x7f96e2dca740 14:13:16.756 [opensc-pkcs11] framework-pkcs15.c:1494:pkcs15_login: pkcs15-login: userType 0x1, PIN length 8
0x7f96e2dca740 14:13:16.756 [opensc-pkcs11] pkcs15-pin.c:301:sc_pkcs15_verify_pin: called
0x7f96e2dca740 14:13:16.757 [opensc-pkcs11] reader-pcsc.c:283:pcsc_transmit: reader ‘Nitrokey Nitrokey HSM (DENK01051600000 ) 00 00’
0x7f96e2dca740 14:13:16.757 [opensc-pkcs11] reader-pcsc.c:284:pcsc_transmit:
Outgoing APDU (13 bytes):
00 20 00 81 08 31 32 33 34 35 36 37 38 . …12345678
GSKIT return codes
If you are using the MQ C Client interface, this uses GSKIT. There is documentation for the z/OS version, and the return codes are here.