% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/htc-status.R
\name{htc_status}
\alias{htc_status}
\title{Check the status of submitted HTCondor jobs}
\usage{
htc_status(
  cluster_id = NULL,
  config = NULL,
  watch = FALSE,
  interval = 60L,
  dry_run = FALSE,
  verbose = FALSE
)
}
\arguments{
\item{cluster_id}{An integer or character string. The cluster ID returned
by \code{\link[=htc_submit]{htc_submit()}}, e.g. \code{6302860}. If \code{NULL} (the default), shows all
of your jobs currently in the queue. Required when \code{watch = TRUE}.}

\item{config}{A named list as returned by \code{\link[=htc_config]{htc_config()}}. Must contain
\code{username} and \code{server}. If \code{NULL}, the function errors with instructions
to call \code{\link[=htc_config]{htc_config()}} first.}

\item{watch}{Logical. If \code{TRUE}, polls the queue repeatedly at \code{interval}
seconds until all jobs in \code{cluster_id} have completed. Requires
\code{cluster_id} to be supplied. Defaults to \code{FALSE}.}

\item{interval}{A positive integer. Number of seconds to wait between
polls when \code{watch = TRUE}. Defaults to \code{60}.}

\item{dry_run}{Logical. If \code{TRUE}, prints the SSH command that would be
executed without running it. Defaults to \code{FALSE}.}

\item{verbose}{Logical. If \code{TRUE}, prints progress messages. Defaults to
\code{FALSE}.}
}
\value{
Called for its side effects. Prints the \code{condor_q} output to the
console. Returns the most recent output invisibly as a character vector.
}
\description{
\code{htc_status()} connects to an HTC submit node via SSH and runs
\code{condor_q} to report the status of jobs in the queue. By default it
shows all of your jobs. Optionally filter by cluster ID to monitor a
specific submission.
}
\details{
When \code{watch = TRUE}, \code{htc_status()} polls the queue repeatedly at a
fixed interval until all jobs in the cluster have completed, printing
a timestamped snapshot after each poll.
}
\section{Job status codes}{

HTCondor reports each job's status with a single letter:\tabular{ll}{
   Code \tab Meaning \cr
   I \tab Idle -- waiting for a matching execute node \cr
   R \tab Running -- currently executing \cr
   H \tab Held -- paused, usually due to an error \cr
   C \tab Completed -- finished successfully \cr
   X \tab Removed -- cancelled \cr
   S \tab Suspended \cr
}


Jobs disappear from \code{condor_q} once they complete and their output has
been transferred back to the submit node. Use \code{\link[=htc_download]{htc_download()}} to retrieve
completed job output.
}

\section{Workflow}{


\if{html}{\out{<div class="sourceCode r">}}\preformatted{cfg <- htc_config()

# One-shot status check
htc_status(config = cfg)

# Monitor a specific cluster until completion
htc_status(cluster_id = 6302860, config = cfg, watch = TRUE)
}\if{html}{\out{</div>}}
}

\section{SSH connection reuse}{

Each poll in watch mode opens a new SSH connection. Configuring
ControlMaster in your \verb{~/.ssh/config} (see \code{\link[=htc_config]{htc_config()}}) is strongly
recommended when using \code{watch = TRUE} to avoid repeated Duo MFA prompts.
}

\examples{
\donttest{
# Preview the SSH command without connecting to CHTC
cfg <- list(username = "netid", server = "ap2002.chtc.wisc.edu")
htc_status(config = cfg, dry_run = TRUE)

# Preview with a specific cluster ID
htc_status(cluster_id = 6302860, config = cfg, dry_run = TRUE)
}

\dontrun{
# All remaining examples require a live CHTC connection
cfg <- htc_config()

# Check all your jobs
htc_status(config = cfg)

# Check a specific cluster
htc_status(cluster_id = 6302860, config = cfg)

# Watch a cluster until all jobs complete (polls every 60 seconds)
htc_status(cluster_id = 6302860, config = cfg, watch = TRUE)

# Watch with a shorter polling interval
htc_status(cluster_id = 6302860, config = cfg, watch = TRUE, interval = 30)
}
}
