The Xi-Batch Diagnostic Helper Functions

What Are the Xi-Batch Diagnostic Helpers?

The Xi-Batch Diagnostic Helpers are a collection of bash functions that shorten common diagnostic and monitoring tasks for Xi-Batch administrators. They are a sourceable shell library that wraps btjlist, btvlist and the job log, giving quick read-only access to job information, logs and system state.

Key characteristics:

• Read-only: every function is a btjlist, btvlist, grep or awk invocation. Nothing modifies a job, a variable or any system state.
• All function names are prefixed with xib-
• Sourcing the file is the whole installation
• They work alongside the standard Xi-Batch commands rather than replacing them
• They require bash. The functions use [[ ]] tests, the =~ match operator, local variables and the &> redirection, so a Bourne, Korn or C shell will reject the file

They are a convenience layer and carry their own limitations. Two of them bite on a normal installation and are covered in detail below: the spool directory is looked for in two places that no current release uses, and the log-date functions build a two-digit year where the log writes four.

Obtaining the Helpers

The helper library is not part of any Xi-Batch distribution. It is absent from the RPM, the Debian package and the tarball, it is not offered by the customer portal, and it is not described in the Xi-Batch manuals. Ask Xi Software support for a copy, and confirm at the same time whether the version you are given is supported for your release.

The library needs bash. Its function names contain hyphens, which a POSIX shell rejects outright with a syntax error on the first line, so it cannot be sourced into sh, dash or the Korn shell that AIX and HP-UX default to. Where bash is absent, run the underlying btjlist and btvlist commands directly - each function is a wrapper around one of them.

Once you have the file, source it:

# One-time use
source /path/to/xib-helpers.sh

# Make available on every login
echo "source /path/to/xib-helpers.sh" >> ~/.bashrc

Run xib-help for the function list and xib-env to see what the library detected.

Set XIB_SPOOLDIR Before You Source It

This is the first thing to do on a current installation, and skipping it disables every log function.

The library looks for the spool directory in this order: the XIB_SPOOLDIR environment variable, then a SPOOLDIR environment variable, then two fixed paths - /usr/spool/batch and /var/spool/batch. The spool directory on a packaged installation is /var/spool/xi/batch, and the tarball installer uses the same value unless the operator changes it during installation. The two fixed paths are therefore wrong on every default installation of every distribution format, and the automatic detection fails.

Set the variable before sourcing:

export XIB_SPOOLDIR=/var/spool/xi/batch
source /path/to/xib-helpers.sh
xib-env

Confirm the real path first rather than assuming the default. It is the SPOOLDIR setting in the master configuration file /etc/xi/batchconfig:

grep SPOOLDIR /etc/xi/batchconfig

If your site uses the XIBATCH_ENV environment variable to run more than one Xi-Batch environment on a host, the spool directory in use is the configured path with that name appended, so read the value from the environment you are diagnosing.

SPOOLDIR is a configuration-file setting rather than an environment variable. Xi-Batch reads it from /etc/xi/batchconfig and never places it in the environment, so the library's SPOOLDIR fallback only helps if an administrator has exported it by hand.

What the failure looks like and what it costs. When the spool directory cannot be found, xib-env prints NOT FOUND and every log function prints "Error: spool directory not found. Set XIB_SPOOLDIR." and returns 1. The affected functions are xib-history, xib-log-today, xib-log-errors, xib-log-on, xib-log-for-job and the second half of xib-compare-times.

The job and variable functions are unaffected. Everything built on btjlist and btvlist - the listing functions, xib-info, xib-script, xib-watch, xib-vars and xib-var - finds the spool directory through Xi-Batch itself and works whether or not XIB_SPOOLDIR is set.

Pointing at the Job Log

Xi-Batch writes a job log only when the LOGJOBS system variable holds a file name; it is empty on a new installation and there is no default log file. The library finds the log in this order: the XIB_LOGFILE environment variable; then the value of LOGJOBS read back with btvlist, resolved against the spool directory if it is a relative path; then the names joblog and logjob in the spool directory.

The two fallback names are guesses - Xi-Batch defines no default log file name - so the reliable routes are the first two. Check what your site uses:

btvlist -F "%N %V" | grep LOGJOBS

Then either rely on that value or set the path explicitly:

export XIB_LOGFILE=/var/spool/xi/batch/joblog
source /path/to/xib-helpers.sh

Log Dates Are Four-Digit Years

The job log line begins with the date in the form DD/MM/YYYY, followed by the time:

04/08/2026|07:30:12|1471|backup_daily|started|jsmith|users|150|1

Two helper functions anchor a date at the start of the line, and both build or document a two-digit year, so as shipped they match nothing:

• xib-log-today builds the pattern with a two-digit year and returns no output on any release that writes four.
• xib-log-on documents its argument as DD/MM/YY. Pass the four-digit form instead - xib-log-on 12/02/2026 works, because the function passes the argument straight through to grep.

Until the library is corrected, use grep directly for today's entries:

grep "^$(date +%d/%m/%Y)" /var/spool/xi/batch/joblog | tail -50

The date order carries one further wrinkle. In time zones four or more hours west of UTC the product writes the day and month transposed, giving MM/DD/YYYY. Sites in the Americas should check one known line in their own log before writing any date pattern.

Why Use the Helpers?

Shorter than the equivalent command:

# Without helpers
btjlist -F "%N %H %U %T %P" | grep -E "Run|Strt|Init"

# With helpers
xib-list-running

Quick diagnostics:

xib-list-errors              # Jobs in error or abort state
xib-log-errors 50            # Last 50 error or abort log entries

Access by job title:

xib-info backup_daily        # Job details
xib-script backup_daily      # The job script
xib-history backup_daily     # Recent log entries

Ad-hoc monitoring:

xib-watch backup_daily       # Refreshes every 5 seconds
xib-compare-times report_weekly  # Schedule alongside recent history

Job Titles Are Not Identifiers

The functions that take a "job name" match against the job's title - the text set with btr -h or btjchange -h, shown by btjlist as %H. Three properties of a title affect how these functions behave:

• Titles need not be unique. Where two jobs share one, the lookup returns the first match in queue order.
• Titles may contain spaces. The lookups compare the second whitespace-separated column, so a title of "backup daily" cannot be found, and the field-position filters in xib-list-by-user and xib-list-by-queue select the wrong column whenever any listed job has a multi-word title.
• A title may be empty, and a job the caller has no permission to read shows an empty title as well.

Where a job matters, work from its number. Every function that accepts a title also accepts the numeric job number and uses it directly:

xib-info 1471
xib-script 1471

Privileges

btjlist and btvlist are installed set-user-id to the batch account, so any user can run them and the listing functions need no elevation. What a given user sees is decided by the Xi-Batch privilege model and by each job's read permission: a job the caller may not read is listed with its variable fields blank rather than refused.

The log functions are the exception. The job log is created owned by the batch account and, with the default permissions, readable by that account and its group alone. Reading it therefore needs the batch account, membership of its group, or root:

sudo -u batch -E bash -c 'source /path/to/xib-helpers.sh && xib-log-errors 20'

The -E flag preserves XIB_SPOOLDIR and XIB_LOGFILE across the elevation. Without it those overrides are dropped and the detection failure described above returns.

For a session of several commands:

sudo -u batch -E bash
source /path/to/xib-helpers.sh
xib-log-errors
xib-log-for-job backup_daily

The Functions

The library defines twenty-seven functions. xib-help prints the same list at the terminal.

Lookup

• xib-name-to-id <title> - job number for a title
• xib-id-to-name <number> - title for a job number

Listing

• xib-list-all - every job, with a header
• xib-list-running - jobs whose progress code is Run, Strt or Init
• xib-list-errors - progress code Err or Abrt
• xib-list-cancelled - progress code Canc
• xib-list-done - progress code Done
• xib-list-by-user [user] - defaults to the current user
• xib-list-by-time <HH:MM> - jobs whose next run time contains that text
• xib-list-repeat - jobs with a repeat interval
• xib-list-by-queue <queue>
• xib-list-by-pattern <pattern> - case-insensitive match anywhere in the line

Job information

• xib-info <title or number> - a formatted summary line, then the default listing for that job
• xib-script <title or number> - the job script, via btjlist -V
• xib-history <title or number> [count] - log lines containing that text, last 20 by default

Analysis

• xib-find-command <command> [directory] - files under the directory containing that text, current directory by default
• xib-check-repeat - see the note below

Log

• xib-log-today - see the four-digit year note above
• xib-log-errors [count] - lines containing Error or Abort, case-insensitive
• xib-log-on <date> - lines beginning with that date
• xib-log-for-job <title or number> [count]

Variables

• xib-vars - every variable with its value and comment
• xib-var <name>

Monitoring and environment

• xib-watch <title or number> [seconds] - repeats a btjlist line, 5 seconds by default
• xib-compare-times <title or number> - schedule alongside the last ten log entries
• xib-env - detected commands, paths and overrides
• xib-help - the function list

Two Functions to Treat With Care

xib-check-repeat reports nothing on any system. It looks for a repeat specification with three colon-separated parts and flags it as an extra parameter, restricting the search to Minutes, Hours, Days and Weeks. Those four units always print two parts. The three-part form is produced only for the two monthly repeat units, Monthsb and Monthse, where the third field is the day of the month and is entirely correct. The function's premise is therefore inverted and its pattern excludes the only case that could match.

xib-list-running omits jobs that are finishing. The progress codes are Done, Err, Abrt, Canc, Init, Strt, Run and Fin. The function searches for Run, Strt and Init, so a job in Fin is left out.

Both functions also match against the whole output line, including the job title and the owner. A job titled "Error report" appears in xib-list-errors, and one titled "Runtime cleanup" appears in xib-list-running, whatever state either is really in. Confirm a match against btjlist before acting on it.

Reading the Log Output

Job log lines are pipe-separated with nine fields:

So the event of each recent failure is field 5:

xib-log-errors 100 | awk -F'|' '{print $1, $2, $3, $5}'

The variable log written by LOGVARS has a different layout and a variable field count, so the same field numbers do not apply to it.

Common Scenarios

Morning System Check

xib-list-running             # What is currently active
xib-list-errors              # Anything that failed overnight
xib-log-errors 20            # The log entries behind them

Investigating a Problem Job

xib-info 1471                # Job details
xib-history 1471 50          # Recent log entries
xib-script 1471              # The script

Finding Jobs by Criteria

xib-list-by-time 07:30       # Jobs due at 07:30
xib-list-by-user jsmith      # Jobs owned by jsmith
xib-list-by-queue live       # Jobs in the 'live' queue
xib-list-repeat              # Repeating jobs

Variables

xib-vars                     # Every variable
xib-var LOADLEVEL            # One variable

Portability

The library is written for Linux and needs adaptation on the commercial Unix platforms Xi-Batch also ships on.

• bash is required and may live somewhere other than /bin on Solaris, AIX and HP-UX.
• xib-watch calls the watch command, which is a Linux utility and is absent from a stock Solaris, AIX or HP-UX system. Use a shell loop with sleep instead.
• /etc/profile.d is a Linux distribution convention. Where it exists, a file placed there is sourced for login shells only, so the functions are missing from cron jobs, from su without a login shell and from non-interactive scripts. Source the file explicitly in anything that depends on it.
• sudo -u and sudo -E assume sudo is installed and configured; su - batch is the portable equivalent.

Integration With Other Work

Export 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

In a script, source the library explicitly and set the overrides first, because a script has neither a login shell nor an interactive profile:

#!/bin/bash
export XIB_SPOOLDIR=/var/spool/xi/batch
source /path/to/xib-helpers.sh

if xib-list-errors | grep -q "critical_load"; then
    echo "Critical job failed" | mail -s "Alert" ops@example.com
fi

Check the exit status as well as the output: every function returns 1 with a message on standard error when a path or a job cannot be found, and an unchecked failure reads the same as a clean result.

What the Helpers Do Not Do

They change nothing. Every function reads. To start, stop or modify jobs, use the standard Xi-Batch commands - btjchange, btjdel, btr, btvar.

They are a complement to btq rather than a replacement. For interactive job management, use btq; the helpers cover the quick command-line questions.

They are unsupported by the manuals. Where a helper and the standard command disagree, the standard command is the authority. Every helper prints the btjlist or btvlist command it is built on if you read the library, and any of them can be run directly.

Troubleshooting

Functions not found: the file must be sourced rather than executed.

source xib-helpers.sh  # Correct
./xib-helpers.sh       # Defines the functions in a child shell that then exits

"btjlist not found in PATH": the Xi-Batch commands are installed in /usr/local/bin on a packaged installation. Confirm with which btjlist and add the directory to PATH.

"spool directory not found": set XIB_SPOOLDIR as described above. This is expected on a current installation rather than a sign of damage.

"job log file not found": either LOGJOBS is unset, so no job log exists, or the file name is one the library does not guess. Check with btvlist -F "%N %V" and set XIB_LOGFILE.

A log function returns nothing: check the year format in the log before assuming the log is empty, and check that you are reading it as the batch account.

Overrides lost under sudo: add -E.

export XIB_SPOOLDIR=/var/spool/xi/batch
sudo -u batch -E bash -c 'source xib-helpers.sh && xib-env'

Example Session

export XIB_SPOOLDIR=/var/spool/xi/batch
source /path/to/xib-helpers.sh
xib-env                      # Confirm the paths were picked up

xib-list-running
xib-list-errors

xib-info backup_daily
xib-script backup_daily

xib-list-by-time 07:30
xib-vars

And the log, as the batch account:

sudo -u batch -E bash -c 'source /path/to/xib-helpers.sh && xib-log-errors 20'

The helpers make routine questions quicker to ask. Treat their output as a first look, confirm anything you are about to act on with btjlist or btvlist directly, and set XIB_SPOOLDIR before you start.