NAME

swmodify − Modify software products in a target root or depot

SYNOPSIS

swmodify [-d|-r] [-p] [-P pathname_file] [-v[v]] [-V] [-u]
[-s product_specification_file| -a attribute=[value]] [-x option=value] [-X option_file]
[-f software_file] [-C session_file] [-S session_file] [software_selections] [ @  target_selection]

Remarks:

SD-UX commands are included with the HP-UX Operating System and manage software on the local host only.  To install and manage software simultaneously on multiple remote hosts (including PCs) from a central controller, you must purchase the HP OpenView Software Distributor (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs.  While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies only to the OpenView product. Where this is the case, you will see:

The following xxx applies only to HP OpenView Software Distributor

DESCRIPTION

The swmodify command modifies the definitions of software objects installed into a primary or alternate root, or available from a software depot.  It supports the following features:

• adding new objects - The user can add new bundles, products, subproducts, filesets, control files, and files to existing objects (which will contain them). 

• deleting existing objects - The user can delete existing bundles, products, subproducts, filesets, control files, and files from the objects which contain them. 

• modifying attribute values - The user can add an attribute, delete an attribute, or change the existing value of an attribute for any existing object.  When adding a new object, the user can at the same time define attributes for it. 

The swmodify commands does not manipulate the actual files which make up a product (fileset).  It can only manipulate the catalog information which describes the files. 

Common uses of swmodify include:

• adding file definitions to the existing list of file definitions in a fileset.  Example: If a fileset’s control scripts add new files to the installed filesystem, the scripts can call swmodify to "make a record" of those new files. 

• changing the values of existing attributes.  Example: If a product provides a more complex configuration process (beyond the SD configure script), that script can set the fileset’s state to CONFIGURED upon successful execution. 

• defining new objects.  Example: to "import" the definition of an existing application that was not installed by SD, construct a simple PSF describing the product.  Then invoke swmodify to load the definition of the existing application into the IPD. 

Options

swmodify supports the following options:

-d Perform modifications on a depot (not on a primary or alternate root).  The given target_selection must be a depot. 

-r Perform modifications on an alternate root (and not the primary root, /). The given target_selection must be an alternate root.) 

-p Previews a modify session without modifying anything within the target_selection.

-P pathname_file
Specifies a file containing the pathnames of files being added to, or deleted from the IPD instead of having to specify them individually on the command line.

-v[v] Turns on verbose output to stdout.  (The swmodify logfile is not affected by this option.) A second -v will turn on very verbose output. 

-V List all the SD layout_versions this command supports. 

-u If no -a attribute=value options are specified, then delete the given software_selections from withing the given target_selection. This action deletes the definitions of the software objects from the depot catalog or installed products database.

If -a attribute options are specified, then delete these attribute definitions from the given software_selections (from within the given target_selection).

-s product_specification_file
The source Product Specification File (PSF) describes the product, subproduct, fileset, and/or file definitions which will be added or modified by swmodify. 

The -s and -u options are mutually exclusive, the -s option cannot be specified when the -u option is specified. 

-a attribute[=value]
Add, modify, or delete the value of the given attribute. If the -u option is specified, then delete the attribute from the given software_selections (or delete the value from the set of values currently defined for the attribute). Otherwise add/modify the attribute for each software_selection by setting it to the given value.

Multiple -a options can be specified.  Each attribute modification will be applied to every software_selection.

The -s and -a options are mutually exclusive, the -s option cannot be specified when the -a option is specified. 

-x option=value
Set the session option to value and override the default value (or a value in an alternate options_file specified with the -X option).  Multiple -x options can be specified. 

-X option_file
Read the session options and behaviors from options_file.

-f software_file
Read the list of software_selections from software_file instead of (or in addition to) the command line. 

-C session_file
Save the current options and operands to session_file. You can enter a relative or absolute path with the file name. The default directory for session files is /.sw/sessions/.  You can recall a session file with the -S option. 

-S session_file
Execute swmodify based on the options and operands saved from a previous session, as defined in session_file. You can save session information to a file with the -C option. 

Operands

The swmodify command supports the following syntax for each software_selection:

bundle[.product[.subproduct][.fileset]][,version]

or

product[.subproduct][.fileset][,version]

The version component has the form:

[,r <op> revision][,a <op> arch][,v <op> vendor][,c <op> category]

or

[instance_id]

where <op> can be: ==, >=, <=, <, >, or != which performs individual comparisons on dot-separated fields.  For example, r>=BB.10.00 means choose all revisions that are greater than or equal to BB.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. 

The = (equals) relational operator is also allowed. It provides the shell pattern matching notations []*?! or wildcards to specify selections as opposed to comparing dot-separated fields. 

All version components are repeatable within a single specification (e.g.  r>=AA.12, r<AA.20). If multiple components are used, the selection must match all components.  No isspace(3) characters are allowed. 

The \* software specification selects all products. 

If a product_specification_file is specified, then swmodify will select the software_selections from the full set defined within the PSF.  The software selected from a PSF is then applied to the target_selection, with the selected software objects either added to it or modified within it. If a PSF is not specified, then swmodify will select the software_selections from the software defined in the given (or default) target_selection.

The swmodify command supports the specification of a single, local target_selection, using the syntax: [@ /directory].  When operating on the primary root, no target_selection needs to be specified.  (The target / is assumed.)  When operating on a software depot, the target_selection specifies the path to that depot.  If the -d option is specified and no target_selection is specified, then the default target_directory is assumed (see below). 

EXTERNAL INFLUENCES

Defaults File

In addition to the standard options, several swmodify behaviors and policy options can be changed by editing the default values found in:

/var/adm/sw/defaults - the system-wide default values,

$HOME/.sw/defaults - the user-specific default values. 

Values must be specified in the defaults file using this syntax:

swmodify.option=value

The default values can be overridden by specifying an options file with the -X option, or by specifying -x option=value on the command line. The policy options that apply to swmodify are:

control_files=
When adding or deleting control file objects, this option lists the tags of those control files.  There is no supplied default.  (Control file objects being added can also be specified in the given product_specification_file.)

If there is more than one tag, they must be separated by whitespace and surrounded by quotes. 

Note that swmodify does not copy (remove) the actual control files to (from) the target. 

files= When adding or deleting file objects, this option can list the pathnames of those files.  There is no supplied default.  (File objects being added can also be specified in the given product_specification_file.)

If there is more than one pathname, they must be separated by whitespace and surrounded by quotes. 

Note that swmodify does not copy (remove) the actual files to (from) the target. 

layout_version=1.0
The object and attribute syntax of SD now conforms to the layout_version of 1.0 from the IEEE POSIX 1387.2 Software Administration standard.  This options controls to which layout_version the SD commands write distributions and swlist output. 

Supported values are "0.8" and "1.0".  The value of "1.0" should be used for future compatibility; the SD commands still accept the old keyword names as well as the new ones.  The value of "0.8" should only be used to create distributions readable by older versions of SD. 

logfile=/var/adm/sw/swmodify.log
Defines the default command logfile for the swmodify command. 

loglevel=1
Controls the log level for the events logged to the swmodify logfile.  A value of 0 prevents information from being logged.  A value of 1 enables verbose logging to the logfile.  A value of 2 enables very verbose logging to the logfile. 

logdetail=false[true]
The SD loglevel and logdetail options allow you to choose what amount of information you need in your logfiles - from no detail to complete information. 
 
The loglevel=0 option allows no information to be written to the logfile.  This essentially turns off the logfile process. 
 
The logdetail=true[false] option controls the amount of detail written to the logfile.  Here are the possible combinations of loglevel and logdetail options:

software=
Defines the default software_selections. There is no supplied default.  If there is more than one software selection, they must be separated by whitespace and surrounded by double-quotes.

source_file=
Defines the default product_specification_file to read as the source.  The -s option overrides this default.  This default will only have an effect if neither the -s nor the -a option is specified. 

target_directory=/var/spool/sw
Defines the default distribution directory in which products will be modified. The target_selection operand overrides this default.  This default only applies when the -d option is specified. 

targets=
Defines the default target_selection. There is no supplied default.

verbose=0
Controls the verbosity of the swmodify output (stdout).  A value of 0 disables output to stdout.  (Error and warning messages are always written to stderr).  A value of 1 enables verbose messaging to stdout.  A value of 2 enables very verbose messaging to stdout. 

Session File

Each invocation of the swmodify command defines a modify session.  The invocation options, source information, software selections, and target hosts are saved before the installation or copy task actually commences.  This lets you re-execute the command even if the session ends before proper completion. 

Each session is automatically saved to the file $HOME/.sw/sessions/swinstall{swcopy}.last.  This file is overwritten by each invocation of swmodify. 

You can also save session information to a specific file by executing swmodify with the -C session__file option. 

A session file uses the same syntax as the defaults files.  You can specify an absolute path for the session file.  If you do not specify a directory, the default location for a session file is /.sw/sessions/.

To re-execute a session file, specify the session file as the argument for the -S session__file option of swmodify. 

Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file.  Likewise, any command line options or parameters that you specify when you invoke swmodify take precedence over the values in the session file. 

Environment Variables

The swlist program sets the following environment variable, which is used by the software control scripts being executed. 

LANG

Determines the language in which messages are displayed.  If LANG is not specified or is set to the empty string, a default value of C is used.  See lang(5) for more information. 

NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, /etc/rc.config.d/LANG.  For example, /etc/rc.config.d/LANG, must be set to LANG=ja_JP.SJIS or LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. 

Signals

The swmodify command ignores SIGHUP, SIGTERM, SIGUSR1, and SIGUSR2.  The swmodify command catches SIGINT and SIGQUIT.   If these signals are received, swmodify prints a message and then exits.  During the actual database modifications, swmodify blocks these signals (to prevent any data base corruption).  All other signals result in their default action being performed. 

PRODUCT SPECIFICATION FILE

The product_specification_file (PSF) for swmodify uses the swpackage PSF format as defined in swpackage(4).

A full PSF contains at least product, fileset, and file definitions.  It would serve as valid input to the swpackage command, and provides swmodify with the information needed to create a new product, with filesets, with files.  A full PSF can also be specified when adding new filesets or files to existing products or filesets.  A full PSF can also be specified when removing existing filesets or files from existing products or filesets. 

RETURN VALUES

The swmodify command returns:

0 The add, modify, or delete operation(s) were successfully performed on the given software_selections.

1 An error occurred during the session (e.g. bad syntax in the product_specification_file, invalid software_selection, etc.)  Review stderr or the logfile for details.

DIAGNOSTICS

The swmodify command writes to stdout, stderr, and to specific logfiles. 

Standard Output

In verbose mode, the swmodify command writes messages for significant events.  These include:

• a begin and end session message,

• selection, analysis, and execution task messages. 

Standard Error

The swmodify command also writes messages for all WARNING and ERROR conditions to stderr. 

Logfile

The swmodify command logs events to the command logfile and to the swagent logfile associated with each target_selection.

Command Log
The swmodify command logs all messages to the the logfile /var/adm/sw/swmodify.log. (The user can specify a different logfile by modifying the logfile option.) 

Target Log
When modifying installed software, swmodify logs messages to the file var/adm/sw/swagent.log beneath the root directory (e.g.  / or an alternate root directory).  When modifying available software (within a depot), swmodify logs messages to the file swagent.log beneath the depot directory (e.g.  /var/spool/sw).

EXAMPLES

Add additional files to an existing fileset:

swmodify -xfiles=’/tmp/a /tmp/b /tmp/c’  PRODUCT.FILESET

Replace the definitions of existing files in an existing fileset (e.g.  to update current values for the files’ attributes):

chown root /tmp/a /tmp/b
swmodify -x files=’/tmp/a /tmp/b’  PRODUCT.FILESET

Delete control files from a fileset in an existing depot:

swmodify -d -xcontrol_files=’checkinstall subscript’ \
         PRODUCT.FILESET @  /var/spool/sw

Create a new fileset definition where the description is contained in the file new_fileset_definition:

swmodify -s new_fileset_definition

Delete an obsolete fileset definition:

swmodify -u PRODUCT.FILESET

Create some new bundle definitions for products in an existing depot:

swmodify -d -s new_bundle_definitions  \*  @  /mfg/master_depot

Modify the values of some fileset’s attributes:

swmodify -a state=installed  PRODUCT.FILESET

Modify the attributes of a depot:

swmodify -a title=’Manufacturing’s master depot’ \
         -a description=</tmp/mfg.description @  /mfg/master_depot

WARNINGS

If the target_selection is a software depot and you delete file definitions from the given software_selections, the files’ contents are not deleted from the depot.

LIMITATIONS

The following applies only to HP OpenView Software Distributor

swmodify command does not apply to PC software. 

FILES

/var/adm/sw/

The directory which contains all of the configurable (and non-configurable) data for SD.  This directory is also the default location of logfiles. 

/usr/lib/sw/sys.defaults

Contains the master list of current SD options (with their default values). 

/var/adm/sw/defaults

Contains the active system-wide default values for some or all SD options. 

$HOME/.sw/defaults

Contains the user-specific default values for some or all SD options. 

$HOME/.sw/sessions/

Contains session files automatically saved by the SD commands, or explicitly saved by the user. 

/var/adm/sw/products/

The Installed Products Database (IPD), a catalog of all products installed on a system. 

/var/spool/sw/

The default location of a target software depot. 

AUTHOR

swmodify was developed by the Hewlett-Packard Company. 

SEE ALSO

sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the HP OpenView Software Distributor Administrator’s Guide or Managing HP-UX Software with SD-UX manuals. 

Hewlett-Packard Company  —  HP-UX Release 10.20:  July 1996