The Xi-Batch Diagnostic Helper Functions

Xi-BatchXi-Batchloggingmonitoringtroubleshooting

The Xi-Batch diagnostic helpers are a bash library of read-only shortcuts over btjlist, btvlist and the job log. They are supplied by Xi Software support. This article says how to obtain and source them, the two settings to make first, and where the library and a current installation disagree.

What the library contains

Functions whose names all begin xib-:

• Read-only: every function is a btjlist, btvlist, grep or awk invocation. Nothing modifies a job, a variable or any system state.
• Sourcing the file is the whole installation
• 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

Two of the library's assumptions are wrong on a current installation, and both are covered 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 and sourcing the library

The library is part of no Xi-Batch distribution: it is absent from the RPM, the Debian package and the tarball, the customer portal does not offer it, and the Xi-Batch manuals do not describe it. 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 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

xib-help prints the function list, and xib-env 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. 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. Xi-Batch reads it from /etc/xi/batchconfig and never places it in the environment, so the library's SPOOLDIR fallback helps only where an administrator has exported it by hand.

What the failure looks like. 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 carry 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

In time zones four or more hours west of UTC the product writes the day and month transposed, giving MM/DD/YYYY. Check one known line in your own log before writing any date pattern.

The short forms

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

What a job name is matched against

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

Who may run them

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 twenty-seven functions

xib-help prints the same list at the terminal.

Lookup

• xib-name-to-id \ - job number for a title
• xib-id-to-name \ - 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 \ - jobs whose next run time contains that text
• xib-list-repeat - jobs with a repeat interval
• xib-list-by-queue \
• xib-list-by-pattern \ - case-insensitive match anywhere in the line

Job information

• xib-info \