Skip to main content

Troubleshooting - Locked QSS

Problem: When you need to modify quotas but the Quota Screen (QSS) is locked or inaccessible, this guide will help you diagnose the problem and resolve it.

Accessing the QSS

There are three ways to access the QSS:

  1. Survox Console - Web interface under Manage > Manage Quotas > Named
  2. Super/Boss Command Line - Type qss <jobname> from a super or boss session
  3. QuotaMod - Direct access via the QuotaMod application in putty, by typing quotamod <enter> and providing the jobname

Why the QSS Gets Locked

The QSS becomes locked or inaccessible for three main reasons:

  1. Another user has it open - Someone is viewing/editing the quota file in QuotaMod in Read/Write mode
  2. Server load failure - Programming changes affecting quotas prevented the study server from loading the file properly
  3. Active or hung surveys - Interviewer sessions or stuck processes are keeping the quota file open on the study server

Diagnosing the Lock

Follow these steps to determine what's causing the lock:

Step 1: Check File Ownership

From Survox CLI (PuTTY), run:

whylock <jobname>

This shows which processes or users have all study files open. 

Step 2: Test Loading from Super/Boss

Open a super or boss session and try:

qss <jobname>

Look for specific error messages that indicate programming issues or file conflicts.

Step 3: Check QuotaMod Access

Try opening the job in QuotaMod. Check if it opens in:

  • Read/Write mode (rw) - You can edit (no lock)
  • Read-Only mode (ro) - File is locked by another process

Fixing the Lock

Based on your diagnosis, use the appropriate fix:

If QuotaMod Has the File Open

  1. Email the team to ask if anyone is actively using QuotaMod for this job
  2. If no one is using it, the process is likely hung
  3. Contact IT to issue a kill command to terminate the stuck QuotaMod process

If Study Server (stdysrvr) Owns the Lock

  1. Confirm no active interviewing is happening on the study
  2. From super/boss, run:
   server:clear <jobname>
  1. This releases the study server's hold on the quota file

If Load Errors Appear

Programming changes may have created a mismatch between the quota file and the survey logic. Contact the programmer or IT to investigate and resolve the mismatch.

Retesting After Fix

After attempting a fix, verify the QSS is now accessible:

  1. From super/boss, activate the job:
   activate <jobname>
   qss <jobname>
  1. If the QSS loads successfully, the problem is resolved
  2. If it still fails to load, repeat the diagnosis and fix steps

Alternative: Modify Quotas While Locked

If the QSS is locked by the study server but the job must remain active (interviewing cannot stop), you can modify quotas directly from the command line:

  1. From super/boss, type:
   mq <jobname>
  1. When prompted, enter the quota you want to change (example: completes.t)
  2. Enter the adjustment using + or - followed by the amount:
    • +5 adds 5 to the current value
    • -10 subtracts 10 from the current value
  3. The server will confirm the change was applied

Note: This method only works for adjusting existing quotas. You cannot add new quota cells or make structural changes using mq.

Back to top