.. _section2:

2 - GENERAL DSUPDT USAGE
=================================

| **dsupdt** [[:ref:`-(DS|Dataset) <DS>`] dNNNNNN] [:ref:`Action Option <section3>`] [:ref:`Mode Options <section4>`] [:ref:`Info Options <section5>`]
|        or
| **dsupdt** [:ref:`-(IF|InputFile) <IF>`] InputFileNames

Brackets [] mark optional elements. A pipe '|' inside parentheses, as in
(A|B), indicates that either A or B may be used. Options fall into three
categories:

.. list-table::
   :widths: auto
   :header-rows: 0

   * - :ref:`Action options <section3>`
     - specify which task to execute
   * - :ref:`Mode options <section4>`
     - modify how an action behaves
   * - :ref:`Info options <section5>`
     - supply values to the action

Each option may be given in either its short or long form (e.g., :ref:`-DS <DS>` or
-Dataset). Some options have alias names for convenience. Option names are
case-insensitive, but the values that follow :ref:`Info options <section5>` are case-sensitive.

Option :ref:`-DS <DS>` specifies a dataset number. When provided as the first argument
following **dsupdt**, the :ref:`-DS <DS>` (-Dataset) option name itself may be omitted. Some
actions can run without a dataset number; in that case they apply to all
available update control or file records across all datasets.

Specify exactly one :ref:`Action option <section3>` per execution. Depending on the chosen
:ref:`Action <section3>`, certain :ref:`Info options <section5>` are mandatory, others are optional, and specific
:ref:`Mode options <section4>` may be applied to alter the action's behavior.

All options except :ref:`-IF <IF>` (-InputFile) may be supplied either on the command line
or in input files. Input file names are passed via :ref:`-IF <IF>` and can only be given
on the command line. See the :ref:`-IF <IF>` option description for details on how to
format options inside input files. One or more input files may be combined
with command-line options. The :ref:`-IF <IF>` option name itself may be omitted when a
single input file is supplied on the command line and all action and option
information is contained within that file.

:ref:`Info options <section5>` used with GET actions function as query filters. Four special
characters enable more precise filtering — they must be quoted or escaped on
the command line to prevent shell interpretation:

.. list-table::
   :widths: auto
   :header-rows: 0

   * - '!'
     - exclude matches; must appear immediately after the option name
   * - '<'
     - less-than comparison on the following value
   * - '>'
     - greater-than comparison on the following value
   * - '<>'
     - range between two values

Combining '!' and '<' as "-<OptionName>!<OptionValue>" expresses a 'greater
than or equal to OptionValue' condition.

The description of an individual option is displayed when **dsupdt** is run as

| **dsupdt** [Option] -(h|help) [Option]

The description is shown for the option placed either before or after
-(h|help). If no option is supplied, or **dsupdt** is run without arguments,
the full document is displayed using the UNIX 'more' utility. A hard copy of
this document can be printed from the saved file 'dsupdt.usg' inside the
Python package rda_python_dsupdt.



| :ref:`Back to Top <section2>`
| :ref:`Back to Table of Contents <index>`