Advanced Troubleshooting in WebDocs iSeries

Posted on July 28, 2016

As a WebDocs iSeries administrator, if something goes wrong your users will look to you to find, and fix, the matter. Simply knowing where to look when an initial error message is unclear can resolve a huge percentage of difficulties. I will cover the most common situations in this article. These instructions are designed to help an administrator clarify the issues at hand, but they may not always be sufficient to correct the issue. In the event of escalating an issue to RJS Software Support, simply having the details from the logs listed below will help speed the resolution of any support tickets immensely.

1. Problems with the default web interface.

WebDocs iSeries ships with a web interface, and in most situations, meaningful errors will display within the interface. In the cases where the message is a generic “Error occurred”, you can look at the Apache instance job logs for more information. On the iSeries, at a command line, run:

WRKSBSJOB QHTTPSVR

Your results should look something like this:

Opt  Job         User        Type     Status  Function
_    ADMIN       QTMHHTTP    BATCH    ACTIVE  PGM-QZHBMAIN
_    ADMIN       QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRLOG
_    ADMIN       QTMHHTTP    BATCH    ACTIVE  PGM-QLWISVR
_    ADMIN       QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRHTTP
_    ADMIN       QTMHHTTP    BATCHI   ACTIVE  PGM-QYUNLANG
_    WEBDOCS     QTMHHTTP    BATCH    ACTIVE  PGM-QZHBMAIN
_    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRLOG
_    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRHTTP
5    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRCGI
_    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRHTTP
5    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRCGI
5    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRCGI

Please note that your job names may vary. The jobs whose Function ends in CGI are the jobs you want to look at. Put a 5 in front of the job (or jobs) to work with it, and choose option 10 to look at it’s job log. Press F10 to get more details, and F18 (Shift+F6) to go to the bottom of the job log, which should show you the error message in full detail. If you place your cursor on the error message, you can press F1 for additional details, and then F9 to see which program the message came from. If you need to send the job log to RJS Software Support, note the job name, user and number across the top of any of these three screens.

Job:   RJSIMAGE      User:   QTMHHTTP       Number:   131940

Enter them into a DSPJOBLOG command, with the output set to *PRINT. A WRKSPLF command will find the newly created spool file for you, which can then be emailed to our support team.

DSPJOBLOG JOB(131940/QTMHHTTP/WEBDOCS) OUTPUT(*PRINT)             

If it appears to be an Apache error, rather than an application error, you can look at Apache’s logs on the IFS using the command:

WRKLNK OBJ('/www/<your server name>/logs')

For debugging or to better understand what database queries are being made, you can set the DEBUGSQL data area in RJSIMAGE to *YES.

CHGDTAARA DTAARA(RJSIMAGE/DEBUGSQL) VALUE(*YES)

This will display the SELECT statement on the top of the page in the WebDocs browser session. On recent versions of WebDocs iSeries, this view is restricted to WebDocs iSeries users that have the Administrator flag set to ‘Y’ in their user profile. On older versions the SQL statements appeared for all users.

2. Problems with folder or document access

WebDocs iSeries uses sessions to manage user security. A session is a static snapshot of a given user’s rights at the time of the session’s creation. As an administrator, changes you make to user or group securities (revocation of rights to a document type, adding a folder, etc.) will not appear to users who are active with sessions that were created prior to the change. An option 6 on the user or group account from the Work with Users and Groups screen will purge any active sessions, forcing users to log in again in order to see current security (for things that need to take effect immediately). As an administrator, it is recommended that you run DOCRMVSESU to clear out all sessions on a nightly or weekly basis.

DOCRMVSESU USER(*ALL)

Alternately, you can submit DOCSESPRG as a job.

                    Purge sessions periodically (DOCSESPRG)                

Minutes between purges . . . . . DELAY          60               

Minutes not used . . . . . . . . INACTVTIME     120              

Time to end job  . . . . . . . . ENDTIME        ___

Every 60 minutes, the job will ‘wake up,’ and purge all sessions that have been inactive for more than two hours. These are configurable, according to your needs.

3. Troubleshooting the .NET API

Many of the ancillary products connect and check-in to WebDocs iSeries using our .NET API. If a problem occurs, with an unclear message from the PC application, you can run the following command to view a list of active jobs – remember to leave the error message up on the PC application, or there is a chance that the job will end.

WRKACTJOB JOB(QZRCSRVS)

There may be a number of jobs that appear – put a 5 on all that appear and peruse each to determine which is the job associated with the troubled application. Alternately, you can look up the job by the current user (the original job user will always be QUSER).

WRKOBJLCK <USERNAME> *USRPRF

This can restrict the number of jobs you have to dig through to find the problem job.

4. Debugging Exit Programs

If you have developed WebDocs iSeries exit programs in-house, an elegant way of troubleshooting or debugging the programs is using Service Entry Points. This allows a breakpoint to be triggered, without knowing in advance what job it will come from. This is ideal when testing check-ins from applications that connect via the .NET API, although there are a number of other equally valuable use cases. 

5. After IPL

Finally, please ensure that all WebDocs iSeries related jobs are being started after an IPL. These include, but are not limited to:

- The Apache web server itself
- DOCMOUNT (if you are using NFS shares)
- DOCSESPRG (if applicable)