What Are the Xi-Batch Diagnostic Helpers?
The Xi-Batch Diagnostic Helpers are a collection of bash functions that simplify common diagnostic and monitoring tasks for Xi-Batch administrators. Implemented as a sourceable shell library, these helpers provide quick, read-only access to job information, logs, and system state without modifying anything.
Key characteristics:
- Read-only operations (never modify jobs or variables)
- Simple, memorable function names (all prefixed with xib-)
- No installation required beyond sourcing the script
- Work alongside existing Xi-Batch commands
Why Use the Helpers?
Simplify common tasks:
Instead of remembering complex btjlist format strings or parsing log files manually, use simple helper functions:
# Without helpers btjlist -F "%N %H %U %T %P" | grep -E "Run|Strt|Init" # With helpers xib-list-running
Quick diagnostics:
Rapidly find problem jobs, check schedules, and review logs:
xib-list-errors # What's broken? xib-check-repeat # Any suspicious repeat specs? xib-log-errors 50 # What went wrong recently?
Named job access:
Work with jobs by name rather than numeric IDs:
xib-info backup_daily # Get details on a job xib-script backup_daily # View the script xib-history backup_daily # See recent runs
Ad-hoc monitoring:
Watch job status without launching btq:
xib-watch backup_daily # Live updates every 5 seconds xib-compare-times report_weekly # Schedule vs actual history
Installation
Download the script from the GitHub repository and source it:
# One-time use source /path/to/xib-helpers.sh # Make available on every login echo "source /path/to/xib-helpers.sh" >> ~/.bashrc # System-wide (requires root) sudo cp xib-helpers.sh /etc/profile.d/
No configuration needed. Once sourced, all functions are immediately available.
Running with Elevated Privileges
Xi-Batch commands typically require running as the batch user or root. The helpers work seamlessly with sudo:
Single command:
sudo -E bash -c 'source /path/to/xib-helpers.sh && xib-list-all'
The -E flag preserves environment variables like XIB_SPOOLDIR or XIB_LOGFILE.
Interactive session:
sudo -E bash source /path/to/xib-helpers.sh xib-list-all xib-list-errors # ... continue using helpers
Run as specific user:
# Run as batch service account sudo -u batch -E bash -c 'source /path/to/xib-helpers.sh && xib-env'
With environment overrides:
# Set overrides, then run with sudo -E export XIB_SPOOLDIR=/custom/spool export XIB_LOGFILE=/custom/joblog sudo -E bash -c 'source /path/to/xib-helpers.sh && xib-list-all'
The -E flag ensures your custom paths are preserved when elevating privileges.
Quick Start Examples
Find what's running:
xib-list-running
Check for problems:
xib-list-errors # Jobs in error/abort state xib-log-errors # Recent error log entries
Inspect a specific job:
xib-info backup_daily # Detailed information xib-script backup_daily # View the script xib-history backup_daily # Recent log entries
Find jobs by criteria:
xib-list-by-time 07:30 # Jobs scheduled at 7:30 AM xib-list-by-user jsmith # All jobs owned by jsmith xib-list-by-queue live # Jobs in 'live' queue xib-list-repeat # All repeating jobs
Review logs:
xib-log-today # Today's log entries xib-log-on 12/02/26 # Entries for specific date xib-log-for-job backup_daily # All entries for one job
Work with variables:
xib-vars # List all variables xib-var LOADLEVEL # Show specific variable
Common Scenarios
Morning System Check
xib-list-running # What's currently active? xib-list-errors # Any failures overnight? xib-log-errors 20 # Recent error details
Investigating a Problem Job
xib-info problem_job # Get full job details xib-history problem_job 50 # Review recent run history xib-script problem_job # Check the script
Finding Schedule Issues
xib-check-repeat # Flag suspicious repeat specs xib-compare-times monthly_report # Schedule vs actual runs
Monitoring During Maintenance
xib-watch critical_job 10 # Watch status every 10 seconds
Available Functions
The helpers provide functions in several categories:
Lookup functions : Translate between job names and IDs
Listing functions : Find jobs by status, user, time, queue, or pattern
Job information : View details, scripts, and history for specific jobs
Analysis functions : Check for common problems and suspicious configurations
Log functions : Review system logs by date, job, or error type
Variable functions : List and inspect Xi-Batch variables
Monitoring functions : Watch job status and compare schedules
Environment functions : Check detected paths and settings
Environment Variables
The helpers auto-detect spool directories and log files. Override if needed:
export XIB_SPOOLDIR=/custom/spool/path export XIB_LOGFILE=/custom/log/path source xib-helpers.sh
Check detected settings:
xib-env
Getting Help
Function listing:
xib-help
Usage for specific function:
xib-list-by-time # Usage: xib-list-by-time <HH:MM>
Full documentation:
See the README on GitHub for complete usage examples and reference.
Integration with Workflows
Export data for analysis:
xib-list-all > jobs-snapshot.txt xib-list-repeat | grep Days > daily-jobs.txt
Pipe to standard tools:
xib-list-by-user jsmith | wc -l # Count jobs
xib-log-errors 100 | awk -F'|' '{print $5}' # Extract field
Script automation:
#!/bin/bash
source /path/to/xib-helpers.sh
if xib-list-errors | grep -q "critical"; then
echo "Critical job failed!" | mail -s "Alert" ops@example.com
fi
What the Helpers Don't Do
Read-only operations:
The helpers never modify jobs, variables, or system state. They're purely diagnostic.
Not a replacement for btq:
For interactive job management, use btq. The helpers complement it for quick command-line diagnostics.
No job control:
To start, stop, or modify jobs, use standard Xi-Batch commands (btjchange, btjdel, etc.).
When to Use the Helpers
Use helpers for:
- Quick status checks during troubleshooting
- Reviewing logs without opening files manually
- Finding jobs by name or criteria
- Ad-hoc monitoring during maintenance
- Scripted health checks
- Learning what's running on an unfamiliar system
Use standard commands for:
- Interactive job management (use btq)
- Modifying jobs or variables
- Detailed job editing
- Complex filtering or formatting
Best Practices
Make helpers available globally:
Add to system profile for all administrators:
sudo cp xib-helpers.sh /etc/profile.d/
Use in combination with btq:
Run helpers in one terminal while managing jobs in btq in another.
Pipe output when needed:
Helpers write to stdout - redirect or pipe freely:
xib-list-all | grep pattern xib-log-errors > errors.log
Check environment after sourcing:
source xib-helpers.sh xib-env # Verify paths detected correctly
Troubleshooting
Functions not found:
Ensure script is sourced, not executed:
source xib-helpers.sh # Correct ./xib-helpers.sh # Wrong
Permission denied errors:
Xi-Batch commands typically require batch user or root privileges:
# Run with sudo sudo -E bash -c 'source /path/to/xib-helpers.sh && xib-list-all' # Or start privileged session sudo -E bash source /path/to/xib-helpers.sh
Commands not found:
Check Xi-Batch commands are in PATH:
which btjlist xib-env # Shows detected commands
Wrong paths detected:
Override with environment variables:
export XIB_SPOOLDIR=/correct/path export XIB_LOGFILE=/correct/logfile source xib-helpers.sh
Environment variables lost with sudo:
Use -E flag to preserve environment:
export XIB_SPOOLDIR=/custom/path sudo -E bash -c 'source xib-helpers.sh && xib-env' # Preserves XIB_SPOOLDIR
Getting the Helpers
Download from GitHub:
wget https://raw.githubusercontent.com/xisl/Helpers/main/xib-helpers.sh # or curl -O https://raw.githubusercontent.com/xisl/Helpers/main/xib-helpers.sh
Repository: https://github.com/xisl/Helpers
Example Session
# Start privileged session sudo -E bash # Source the helpers source xib-helpers.sh # Quick system check xib-list-running xib-list-errors # Investigate a specific job xib-info backup_daily xib-history backup_daily # Check logs xib-log-today | grep backup xib-log-errors 20 # Find all morning jobs xib-list-by-time 07:00 xib-list-by-time 07:30 # Check repeat configurations xib-check-repeat # Monitor a job xib-watch backup_daily
Or run individual commands:
sudo -E bash -c 'source /path/to/xib-helpers.sh && xib-list-running' sudo -E bash -c 'source /path/to/xib-helpers.sh && xib-log-errors 20'
The Xi-Batch Diagnostic Helpers make routine administration tasks faster and more convenient. For complete documentation and usage examples, see the README on GitHub.