Working with Variables in Xi-Batch

What Are Variables?

Variables in Xi-Batch are named containers holding data that jobs can read and modify. They enable:

• Job dependency control (wait for conditions)
• State tracking across jobs
• Data passing between jobs
• Workflow synchronization
• System-wide settings (LOADLEVEL, LOGJOBS, etc.)

Variable Components

Each variable has multiple attributes:

Name : Unique alphanumeric identifier starting with alphabetic character : Case-sensitive, must be unique per machine : Examples: STATUS, Counter1, Backup_Done

Value : Either integer or text string : Numeric: -999 to 999999 (any integer) : String: Any text, prefixed with " when entering

Comment : Free text description : Not used by scheduler, for documentation only : Recommended for all variables

User : Owner username : Initially creator, can be transferred : Controls permissions

Group : Group name : Initially creator's primary group : Can be transferred

Mode : Permissions similar to Unix file modes : More granular than file permissions : Controls read/write/reveal access

Export flag : Local (visible only on this machine) : Export (visible across network)

Cluster flag : Only meaningful for exported variables : Controls whether jobs use local copy

Variable Types: Numeric vs String

Numeric variables:

bash

# Create numeric variable
btvar -c counter 0

# Arithmetic operations supported
btvar -s counter 100
btvar -s counter '+=5'   # Now 105
btvar -s counter '*=2'   # Now 210

String variables:

bash

# Create string variable (note quote prefix)
btvar -c STATUS "Pending"

# Update string
btvar -s STATUS "Ready"
btvar -s STATUS "Complete"

Type detection:

• Starts with digit or - → numeric
• Starts with anything else → string
• To force string starting with digit: prefix with "

Examples:

bash

btvar -c value 123      # Numeric: 123
btvar -c value -456     # Numeric: -456
btvar -c value "123"    # String: "123"
btvar -c value abc      # String: "abc"

System Variables

Seven pre-defined system variables exist:

CLOAD (read-only) : Current total load level of running jobs : Updated in real-time by scheduler : Cannot be modified by users

LOADLEVEL : Maximum allowed total load for running jobs : Jobs start only if: CLOAD + job_load <= LOADLEVEL : Can be adjusted to control workload

LOGJOBS : Job audit trail destination : String value: filename or |program : Empty string disables logging

LOGVARS : Variable audit trail destination : String value: filename or |program : Empty string disables logging

MACHINE (read-only) : Current machine hostname : Only usable as local variable : Useful in conditions: MACHINE = myhost

STARTLIM : Maximum jobs to start simultaneously : Default: 5 : Controls start rate to prevent resource swamping

STARTWAIT : Seconds to wait between job start batches : Default: 30 : Works with STARTLIM to pace job starts

View system variables:

bash

btvlist | grep -E "CLOAD|LOADLEVEL|LOGJOBS|LOGVARS|MACHINE|STARTLIM|STARTWAIT"

Local vs Exported Variables

Local variables:

• Visible only on machine where created
• Cannot be used in remote job conditions
• Faster access (no network lookup)
• Use for machine-specific state

bash

# Create local variable (default)
btvar -c local_status "Ready"

# Or explicitly set as local
btvar -c local_status "Ready"
btvar -L local_status

Exported variables:

• Visible across all networked Xi-Batch hosts
• Accessible in remote job conditions
• Synchronized automatically
• Use for workflow coordination

bash

# Create variable then export
btvar -c shared_status "Ready"
btvar -E shared_status

# Reference from remote host in job
# Condition: server1:shared_status = Ready

Network variable names:

Remote variables referenced as: hostname:varname

bash

# From server2, reference server1's variable
btvar -v server1:shared_status

Clustered Variables

Clustered flag only meaningful for exported variables:

Non-clustered (default):

Jobs running on any host use the same variable instance.

Clustered:

Jobs running on a host use that host's local copy of the variable.

bash

# Mark exported variable as clustered
btvar -E STATUS      # Export first
btvar -U STATUS      # Mark as clustered

# Unmark clustered
btvar -K STATUS

Use case for clustering:

Each host has its own LOCAL_STATUS variable with same name:

• Server1: LOCAL_STATUS = "Processing A"
• Server2: LOCAL_STATUS = "Processing B"

Jobs on Server1 see Server1's value, jobs on Server2 see Server2's value.

Variable Permissions (Modes)

Variables have granular permission system:

Read : View variable value

Write : Modify variable value

Reveal : See that variable exists (see name) : Automatically granted with Read

Display Mode : View variable permissions

Set Mode : Change variable permissions

Permissions apply to:

• User (owner)
• Group (owner's group)
• Other (everyone else)

View permissions:

bash

# In btq: press M on variable
# Or command line:
btvlist -v varname

Modify permissions:

bash

# In btq: select variable, press M
# Use cursor to navigate, s/u/t to set/unset/toggle

Creating Variables

Command line:

bash

# Create numeric variable
btvar -c counter 0

# Create string variable
btvar -c status "Pending"

# Create with comment
btvar -c counter 0
btvar -C counter "Job execution counter"

# Create and export
btvar -c shared_var 100
btvar -E shared_var

In btq interactive interface:

1. Press V to switch to variables screen
2. Press C to create
3. Enter variable name
4. Enter value (numeric or string)
5. Optionally add comment

Modifying Variables

Change value:

bash

# Set new value
btvar -s status "Ready"

# Arithmetic on numeric variables
btvar -s counter '+=1'      # Increment
btvar -s counter '-=5'      # Decrement
btvar -s counter '*=2'      # Multiply
btvar -s counter '/=2'      # Divide
btvar -s counter '%=10'     # Modulus

Change comment:

bash

btvar -C varname "New description"

Change ownership:

bash

# Change owner (requires appropriate privileges)
btvar -u newuser varname

# Change group
btvar -g newgroup varname

Deleting Variables

bash

# Delete variable
btvar -d varname

# In btq: select variable, press D, confirm

Note: System variables (CLOAD, LOADLEVEL, etc.) cannot be deleted.

Listing Variables

All variables:

bash

btvlist

Exported variables only:

bash

btvlist -e

Specific variable:

bash

btvar -v varname

With full details:

bash

btvlist -v varname

Remote variables:

bash

# From server2, view server1's variables
btvlist | grep "^server1:"

Common Variable Patterns

Counter Pattern

bash

# Create counter
btvar -c job_count 0

# Jobs increment on start
# In job submission:
btr -A "job_count += 1 @ Job start" script.sh

Status Flag Pattern

bash

# Create status variable
btvar -c backup_status "Not Started"

# Backup job updates status
btr -A "backup_status = Running @ Job start" \
    -A "backup_status = Complete @ Job completed" \
    -A "backup_status = Failed @ Job error" \
    backup.sh

# Other jobs wait for completion
btr -c "backup_status = Complete" post-backup.sh

Lock Pattern

bash

# Create lock variable
btvar -c update_lock 0

# Job acquires lock
btr -c "update_lock = 0" \
    -A "update_lock = 1 @ Job start" \
    -A "update_lock = 0 @ Job completed" \
    update-database.sh

Shared Counter Pattern

bash

# Create exported counter for network-wide tracking
btvar -c total_processed 0
btvar -E total_processed

# Jobs on any host increment
btr -A "total_processed += 1 @ Job completed" process.sh

Best Practices

Use descriptive names:

• Good: backup_status, db_update_lock, file_counter
• Avoid: var1, temp, x

Add comments:

Always document variable purpose:

bash

btvar -C backup_status "Current status of nightly backup job"

Choose appropriate scope:

• Local for machine-specific state
• Export for workflow coordination

Set restrictive permissions:

Prevent accidental modification:

bash

# Only owner can write, others can read
# Set via btq mode editor

Use meaningful initial values:

bash

# Good
btvar -c status "Not Started"
btvar -c counter 0

# Less clear
btvar -c status ""
btvar -c counter 1

Export only when needed:

Network overhead for exported variables. Keep local when possible.