ccs(CDMT)

ccs -- component control script

Syntax

ccs step [keyword_list] package_list

Description

The Component Control Script (ccs) located in SSOroot/cntl/ccs, defines how custom(ADM) installs the component. For each component that you prepare for installation, create a ccs.

custom calls the ccs multiple times during the installation, upgrade, and removal processes, at the beginning and end of each phase. See ``Software management phases'' in Developer's Topics.

The ccs takes three arguments:

$1

step to perform

The step name contains three items:

the name of the phase to perform (such as LOAD)
the prefix UN (if the step is a reverse operation)
the prefix PRE_ or POST_, indicating which step to perform

For example, use PRE_LOAD to indicate the pre-load step during an installation; POST_UNATTACH indicates the post-attach step during a removal.

$2

keyword_list

The keyword specifies how the ccs behaves (during installation only):

UPGRADE: Upgrades an older version of an SSO-based component to the new version of an SSO-based component.
OLD_CUSTOM_UPGRADE: Upgrades a non-SSO component to an SSO component.

See ``Creating software upgrades'' in Developer's Topics.

$3

package_list

The package_list is a space-separated list of the fully-qualified package names in the component. Package names are in the form:

vendorCode:componentCode:packageCode.

See ``Component identifiers'' in Developer's Topics. To use the simpler packageCode, use the getPackageCode function in the ccsSetup(CDMT) library.

In addition to these three arguments, the ccs receives information from custom by way of environment variables. See ``Component script environment variables'' in Developer's Topics. If the ccs receives the UPGRADE or OLD_CUSTOM_UPGRADE keyword during installation, some (not necessarily all) packages of the component will be upgraded. There is no guarantee that older versions for all packages in the new version exist on the system. To determine if a previous version of a given package is installed, in the ccs script:

include a call to customquery(ADM) using the ListPackages command

include a check for every reference to a file from the older package using the following Bourne shell construct:

   if [ -r filename ]
   then
      # look at the file <filename>
   else
      # choose some default instead of looking for the file
   fi

Exit values

Component control scripts should exit with one of the following values:

Value Variable Description

0 OK script executed successfully.

1 FAIL script execution was unsuccessful and the installation or removal is aborted; the user can choose to STOP the component.

2 WARN script execution logged warnings, but the installation or removal proceeded; the user can choose to STOP or continue the component.

3 STOP script stopped processing on this component (the component is left in the state it was in when the ccs returned STOP), but continued other component installation without user intervention.

If a ccs exits with an exit value of 1 during an installation or upgrade, the installation or upgrade will not proceed further. However, other components that are being installed simultaneously will continue to install. The component is left in whatever state it was in at the time of failure and the custom database for the component is updated to indicate the phase that was executing at the time of failure, along with the keyword corrupt. For example, a component might be left in the state of (attach, corrupt).

Value	Variable	Description
0	OK	script executed successfully.
1	FAIL	script execution was unsuccessful and the installation or removal is aborted; the user can choose to STOP the component.
2	WARN	script execution logged warnings, but the installation or removal proceeded; the user can choose to STOP or continue the component.
3	STOP	script stopped processing on this component (the component is left in the state it was in when the ccs returned STOP), but continued other component installation without user intervention.

If a ccs exits with an exit value of 1 during a removal, custom notifies the user and prompts the user to continue or cancel the removal. If the user continues the removal, the removal proceeds as if the ccs returned a successful exit status; if the user cancels, custom sets the state of the component to corrupt and halts the removal process.

If the ccs exits with a value of 1, custom attempts to recover the component from the corrupted state by running the ccs backwards through the unsuccessful phase.

For example, if the ccs for a component installation successfully executed through the PRE_ATTACH and system ATTACH steps, but returned an error code of 1 during the POST_ATTACH step, the installation is aborted and the component status is "(ATTACH, corrupt)". In this case, custom attempts to recover the component by running these three operations:

ccs PRE_UNATTACH empty_keyword_list package_list
undo the ATTACH system step
ccs POST_UNATTACH empty_keyword_list package_list

If all three steps execute successfully, custom marks the component as "(LOADED, not corrupt)" and then is ready to retry the ATTACH step.

When you write your ccs, makes sure that the removal process (the ``UN'' steps) can undo any actions that take place in the installation process, even if the phase does not complete successfully.

Limitations

The following limitations apply to ccs operation:

Do not use the ccs to prompt the user for input; use the cqs(CDMT) instead.
Do not allow the ccs to echo to stdout or stderr; use the logging facility in the ccsSetup library instead.
In the PRE_LOAD step, make sure that the ccs only references files contained in the SharedControl package of the component.
Until the POST_CONFIGURE step, make sure that the ccs only references utilities that are either part of the component itself or are located in the /ibin directory.
Until the POST_ATTACH step, make sure that the ccs does not refer to its /var/opt hierarchy; this hierarchy does not exist until the POST_ATTACH step.
The ccs must kill any running daemons in the PRE_UNEXPORT step.
Do not assume that installations and removals will be run in single-user mode and do not force the user to enter single-user mode.

Files

SSOroot/cntl/ccs

Standards conformance

ccs is not part of any currently supported standard; it is an extension of AT&T System V provided by The Santa Cruz Operation, Inc.