tk5-c90-projects/HERCULES_READER_COMMANDS.md

Hercules Card Reader Device Commands

This document contains the Hercules console commands used to manage the card reader device (00C/3505).

View Device Status

devlist 00c

Example Output:

HHC02279I 0:000C 3505 3505 sockdev ascii trunc eof IO[2]
HHC02279I      (no one currently connected)

Key Information:

• IO[n] - Shows the I/O state number
• (no one currently connected) - Socket is free
• (client IP (<unknown>) connected) - Socket is in use

Reset Card Reader (When Stuck)

Method 1: Detach and Reattach (Recommended)

detach 00c
attach 00c 3505 3505 sockdev ascii trunc eof

This completely removes and recreates the device, clearing any stuck connections.

Method 2: Devinit (May Not Work if Socket is Wedged)

devinit 00c 3505 3505 sockdev ascii trunc eof

Note: devinit may fail with "Address already in use" if the socket is stuck. Use Method 1 instead.

Common Issues

Device Stuck in "IO[n] open" State

Symptoms:

• devlist 00c shows IO[5] open or similar
• Client shown as connected even after jobs complete
• New connections rejected with "device busy or interrupt pending"

Solution:

detach 00c
attach 00c 3505 3505 sockdev ascii trunc eof

Connection Refused from Workflow

Symptoms:

• Workflow logs show: Connection refused from netcat
• Device shows: localhost:3505 in devlist

Problem: Device bound to localhost only, not accepting external connections.

Solution: Use port number only (binds to all interfaces):

detach 00c
attach 00c 3505 3505 sockdev ascii trunc eof

DO NOT USE:

attach 00c 3505 localhost:3505 sockdev ascii trunc eof  # Wrong - localhost only
attach 00c 3505 0.0.0.0:3505 sockdev ascii trunc eof    # Also fails on some systems

Device Configuration for Workflow

For the Gitea workflow to connect successfully, the card reader must be configured to accept connections from any interface:

attach 00c 3505 3505 sockdev ascii trunc eof

Verify with:

devlist 00c

Should show:

HHC02279I 0:000C 3505 3505 sockdev ascii trunc eof IO[n]

Not:

HHC02279I 0:000C 3505 localhost:3505 sockdev ascii trunc eof IO[n]  # Wrong

Troubleshooting Workflow Socket Issues

If workflows are failing with socket errors:

1. Check device status:

   devlist 00c
   

2. Look for stuck connections:

   • IO[5] open with client connected = stuck

3. Reset the device:

   detach 00c
   attach 00c 3505 3505 sockdev ascii trunc eof
   

4. Verify it's ready:

   devlist 00c
   

   Should show (no one currently connected)

Prevention

The submit_job.py script now includes a 10-second delay between submissions to prevent socket conflicts:

• Upload job submits
• Wait 10 seconds for JES to process
• Compile job submits

This gives Hercules time to fully close the socket between connections.