[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here HP OpenVMS System Management Utilities Reference Manual

HP OpenVMS System Management Utilities Reference Manual


Previous Contents Index

MONITOR STATES

The MONITOR STATES command initiates monitoring of the PROCESS STATES class, which shows the number of processes in each of the 14 scheduler states.

Format

MONITOR STATES


Command Qualifiers

/qualifier[,...]

One or more qualifiers as described in the Command Qualifier Descriptions section.

Classname Qualifiers

/ALL

Specifies that a table of all available statistics (current, average, minimum, and maximum) is to be included in the display and summary output. For summary output, this qualifier is the default for all classes; otherwise, it is the default for all classes except CLUSTER, MODES, PROCESSES, STATES, SYSTEM, and VECTOR.

/AVERAGE

Specifies that a bar graph of average statistics is to be included in the display and summary outputs.

/CURRENT

Specifies that a bar graph of current statistics is to be included in the display and summary outputs. The /CURRENT qualifier is the default for the CLUSTER, MODES, STATES, SYSTEM, and VECTOR classes.

/MAXIMUM

Specifies that a bar graph of maximum statistics is to be included in the display and summary outputs.

/MINIMUM

Specifies that a bar graph of minimum statistics is to be included in the display and summary outputs.

/PERCENT

/NOPERCENT (default)

Controls whether statistics are expressed as percent values in display and summary outputs. The /PERCENT qualifier is applicable only to the DISK, MODES, SCS, and STATES class names.


Description

The STATES class shows the number of processes in each of the 14 scheduler states. The following table describes these scheduler states:
Scheduler State Description
Collided Page Wait (COLPG) Waiting for a faulted page in transition.
Mutex & Miscellaneous Resource Wait (MWAIT) Waiting for the availability of a mutual exclusion semaphore or a dynamic resource. The following table contains a summary of Mutex and Miscellaneous Resource Wait states and identifying codes, as they appear in the PROCESSES class display:
MWAIT Reason for Wait
MUTEX Mutual exclusion semaphore
RWAST AST wait (wait for system or special kernel AST)
RWBRK Breakthrough (wait for broadcast message)
RWCAP CPU capability required
RWCLU Cluster state transition wait
RWCSV Cluster server
RWIMG Image activation lock
RWLCK Lock database
RWMBX Mailbox full
RWMPB Modified page writer busy
RWMPE Modified page list empty
RWNPG Nonpaged dynamic memory
RWPAG Paged dynamic memory
RWPGF Page file full
RWQUO Job quota
RWSCS System Communications Services wait
RWSNP System snapshot
RWSWP Swap file space
Common Event Flag Wait (CEF) Waiting for a combination of event flags to be set in a common event block.
Page Fault Wait (PFW) Waiting for a page to be read as a result of a page fault; resident processes.
Local Event Flag Wait (LEF) Waiting for one or more local event flags to be posted; resident processes.
Local Event Flag (Outswapped) (LEFO) Waiting for one or more local event flags to be posted; outswapped processes.
Hibernate (HIB) Hibernating, or process has executed a hibernate request; resident processes.
Hibernate (Outswapped) (HIBO) Hibernating, or process has executed a hibernate request; outswapped processes.
Suspended (SUSP) Process has executed a suspend request; resident processes.
Suspended (Outswapped) (SUSPO) Process has executed a suspend request; outswapped processes.
Free Page Wait (FPW) Waiting for a free page of memory.
Compute (COM) Ready to use the processor; resident processes.
Compute (Outswapped) (COMO) Ready to use the processor; outswapped processes.
Current Process (CUR) Using the processor.

The data items can also be displayed as percentages of all processes.

Note that the Current Process is always the process running MONITOR, because MONITOR is running when each measurement is made.

For performance reasons, MONITOR does not synchronize the scanning of process state data structures with operating system use of those structures. It is therefore possible that MONITOR will display certain anomalous state indications.


Example


$ MONITOR/INPUT/SUMMARY/NODISPLAY -
_$/BEGINNING=29-APR-2003:13:00 -
_$/ENDING=29-APR-2003:14:00 STATES/PERCENT/ALL
$ TYPE MONITOR.SUM








                            OpenVMS Monitor Utility
                                 PROCESS STATES (%)
                                 on node SAMPLE       From: 29-APR-2003 13:00:00
                                    SUMMARY           To:   29-APR-2003 14:00:00

                                       CUR%       AVE%       MIN%       MAX%
     Collided Page Wait                0.0        0.0        0.0        0.0
     Mutex & Misc Resource Wait        0.0        0.0        0.0        0.0
     Common Event Flag Wait            0.0        0.0        0.0        0.0
     Page Fault Wait                   4.3        1.4        0.0        4.3
     Local Event Flag Wait            34.7       31.7       34.7       42.8
     Local Evt Flg (Outswapped)        0.0        9.0        0.0       19.4

     Hibernate                        43.4       40.7       43.4       52.1
     Hibernate (Outswapped)            0.0        4.3        0.0       15.4
     Suspended                         0.0        0.0        0.0        0.0
     Suspended (Outswapped)            0.0        0.0        0.0        0.0
     Free Page Wait                    0.0        0.0        0.0        0.0
     Compute                          13.0        7.3        4.3       13.0
     Compute (Outswapped)              0.0        0.8        0.0        3.2
     Current Process                   1.0        1.0        1.0        1.0
     PLAYBACK                     SUMMARIZING

The commands in this example generate and display a PROCESS STATES summary. Note that since use of the Return key is not permitted within a single MONITOR command following the MONITOR> prompt, the MONITOR command is entered at DCL level. The summary shows that, on the average, 14.1 percent of processes were swapped out for the summarized period. Note that the summary was requested for data covering only the hour between 1 P.M. and 2 P.M., although the input file could have contained data covering a longer period.

MONITOR SYSTEM

The MONITOR SYSTEM command initiates monitoring of the SYSTEM statistics class, which shows several of the most important items from other classes.

Format

MONITOR SYSTEM


Command Qualifiers

/qualifier[,...]

One or more qualifiers as described in the Command Qualifier Descriptions section.

Classname Qualifiers

/ALL

Specifies that a table of all available statistics (current, average, minimum, and maximum) is to be included in the display and summary output. For summary output, this qualifier is the default for all classes; otherwise, it is the default for all classes except CLUSTER, MODES, PROCESSES, STATES, SYSTEM, and VECTOR.

/AVERAGE

Specifies that a bar graph of average statistics is to be included in the display and summary outputs.

/CURRENT

Specifies that a bar graph of current statistics is to be included in the display and summary outputs. The /CURRENT qualifier is the default for the CLUSTER, MODES, STATES, SYSTEM, and VECTOR classes.

/MAXIMUM

Specifies that a bar graph of maximum statistics is to be included in the display and summary outputs.

/MINIMUM

Specifies that a bar graph of minimum statistics is to be included in the display and summary outputs.

Description

Because the SYSTEM class collects the most significant performance statistics from other classes in a single display, it is particularly useful to system managers and other users seeking a general overview of system activity. The SYSTEM class includes the following data items:
Interrupt Stack (on VAX systems) or Interrupt State (on Alpha systems)
MP Synchronization
Kernel Mode
Executive Mode
Supervisor Mode
User Mode
Compatibility Mode (meaningful on VAX systems only)
Idle Time
Process Count
Page Fault Rate
Page Read I/O Rate
Free List Size
Modified List Size
Direct I/O Rate
Buffered I/O Rate

The following two display formats are provided, depending on the classname qualifier specified:

  • A tabular style format for the /ALL qualifier
  • A bar graph style format for the /AVERAGE, /CURRENT, /MAXIMUM, and /MINIMUM qualifiers

Examples of these formats are at the end of this section. Note that the bar graph version of the SYSTEM class (shown in Example 2) contains the following data, which differs from the tabular version:

  • All of the CPU processor modes except Idle Time are summarized in the CPU Busy segment.
  • In the Page Fault segment, the page read I/O rate is indicated by a vertical bar. The bar provides a visual estimate of the proportion of the total page fault rate that caused read I/O operations (the hard fault rate). The hard fault rate appears to the left of the bar.
  • Four segments show the processes that are currently the top consumers of CPU (since the last screen update), page faults, direct I/Os, and buffered I/Os.

Beginning in OpenVMS Version 7.3, the following rate fields have increased in the MONITOR SYSTEM bar graph screen display:

Rate Name Old Rate New Rate
Page Fault 100 500
Hard Page Fault (vertical line on Page Fault display) 100 500
Direct I/O 60 500
Free List Size Shown in K blocks Shown in K, M, or G blocks (whichever is appropriate)
Mod (modified) List Size 5 digits; K blocks 8 digits; K, M, or G blocks (whichever is appropriate)
Buffered I/O 150 500

Any process that MONITOR designates as a top user process must be swapped in at the beginning and ending of the display interval or at the beginning and ending of the entire period covered by a summary.

When the lower bar graph (top user) and the corresponding upper bar graph (overall system measure) are tracking the same statistic for the same interval (as in Example 2), it is reasonable to compare the two graphs. This will be the case in the following situation:

  • SYSTEM is the only class being monitored (no other class names have been specified with the MONITOR command).
  • The CURRENT statistic is specified.
  • The /INTERVAL and /VIEWING_TIME values are equal.

Otherwise, exercise care in making such comparisons because the top user statistic is always CURRENT, while the overall system measure statistic may be CURRENT, AVERAGE, MAXIMUM, or MINIMUM.

Rates for top users are calculated based on the interval between two successive screen displays, while overall system rates are based on the collection interval. These two interval values can be different whenever one or more classes are being monitored with the SYSTEM class, or when /INTERVAL and /VIEWING_TIME values differ.

While other upper boundary figures for the SYSTEM class bar graphs are constants, the figures for Free List Size and Modified List Size are derived from the physical memory configuration and system parameters of individual systems. The upper boundary figure for the Free List is the number of pages available after deducting the pages permanently allocated to the operating system. This figure, sometimes referred to as balance set memory, is the number of pages that can be allocated to processes, the Free List, and the Modified List. The upper boundary figure for the Modified List is the value of the MPW_HILIMIT system parameter. Note that both upper boundary figures are calculated when the MONITOR request is initiated and do not change thereafter.


Examples

#1

MONITOR> MONITOR SYSTEM/ALL








                           OpenVMS Monitor Utility
                               SYSTEM STATISTICS
                                 on node SAMPLE
                              29-APR-2003 12:43:28

                                       CUR        AVE        MIN        MAX

    Interrupt Stack                   0.33       0.33       0.33       0.33
    MP Synchronization                0.00       0.00       0.00       0.00
    Kernel Mode                       0.16       0.16       0.16       0.16
    Executive Mode                    0.00       0.00       0.00       0.00
    Supervisor Mode                   0.00       0.00       0.00       0.00
    User Mode                         0.50       0.49       0.50       0.50
    Compatibility Mode                0.00       0.00       0.00       0.00
    Idle Time                        99.00      98.67      99.00      99.00
    Process Count                    14.00      14.00      14.00      14.00
    Page Fault Rate                   0.33       0.33       0.33       0.33
    Page Read I/O Rate                0.00       0.00       0.00       0.00
    Free List Size                 4255.00    4255.00    4255.00    4255.00
    Modified List Size              105.00     105.00     105.00     105.00
    Direct I/O Rate                   0.00       0.00       0.00       0.00
    Buffered I/O Rate                 0.16       0.16       0.16       0.16

This example shows the tabular style format for the SYSTEM display.

#2

MONITOR> MONITOR SYSTEM









Node: BRS004                OpenVMS Monitor Utility      5-JUN-2003 10:45:32
Statistic: CURRENT             SYSTEM STATISTICS
                                                     Process States
          + CPU Busy (400)          -+         LEF:    15      LEFO:     0
          |**************************|         HIB:    14      HIBO:     0
CPU     0 +--------------------------+ 400     COM:     8      COMO:     0
          |*                         |         PFW:     0      Other:    1
          +--------------------------+         MWAIT:   0
          Cur Top: BATCH_27 (6)                          Total: 38

          + Page Fault Rate (1438)  -+         + Free List Size (35173)   +
          |****|*********************|         |****************          | 54K
MEMORY  0 +--------------------------+ 500   0 +--------------------------+
          |****                      |         |*************             | 5765
          +--------------------------+         + Mod List Size (3078)     +
          Cur Top: BATCH_29 (78)

          + Direct I/O Rate (442)   -+         + Buffered I/O Rate (112) -+
          |**********************    |         |*****                     |
I/O     0 +--------------------------+ 500   0 +--------------------------+ 500
          |*                         |         |                          |
          +--------------------------+         +--------------------------+
          Cur Top: BATCH_24 (23)               Cur Top: BATCH_24 (6)

This example shows the bar graph style format for the SYSTEM display.

MONITOR TIMER

The MONITOR TIMER command initiates monitoring of the TIMER statistics class, which is the rate of processing Timer Queue Entries (TQEs) by the OpenVMS executive. A TQE is a data structure representing a timer request made by a user or by the system.

Format

MONITOR TIMER


Command Qualifiers

/qualifier[,...]

One or more qualifiers as described in the Command Qualifier Descriptions section.

Classname Qualifiers

/ALL

Specifies that a table of all available statistics (current, average, minimum and maximum) is to be included in the display and summary outputs. For summary output, this qualifier is the default for all classes; otherwise, it is the default for all classes except CLUSTER, MODES, PROCESSES, STATES, SYSTEM, and VECTOR.

/AVERAGE

Specifies that a bar graph of average statistics is to be included in the display and summary outputs.

/CURRENT

Specifies that a bar graph of current statistics is to be included in the display and summary outputs. The /CURRENT qualifier is the default for the CLUSTER, MODES, STATES, SYSTEM, and VECTOR classes.

/MAXIMUM

Specifies that a bar graph of maximum statistics is to be included in the display and summary outputs.

/MINIMUM

Specifies that a bar graph of minimum statistics is to be included in the display and summary outputs.

Description

The TIMER class consists of the following data items, which are displayed as rates of occurrences per second:
Data Item Description
Total TQE Rate Total Rate of TQEs processed per second. This statistic is a combined total of the three following TQE rates.
SYSUB TQE Rate Rate of SYSUB TQEs processed per second. These system subroutine TQEs represent timer requests made by the OpenVMS operating system.
Timer TQE Rate Rate of Timer TQEs processed per second. These TQEs represent timer requests made by users through the $SETIMR system service.
Wakeup TQE Rate Rate of wakeup TQEs processed per second. These TQEs represent timer requests made by users through the $SCHDWK system service.

Examples

#1

MONITOR> MONITOR TIMER








                            OpenVMS Monitor Utility
                                TIMER STATISTICS
                                 on node EBJB28
                             6-OCT-2003 08:46:13.84

                                       CUR        AVE        MIN        MAX

    Total TQE Rate                   56.00      56.00      56.00      56.00

    SYSUB TQE Rate                   51.33      51.33      51.33      51.33
    Timer TQE Rate                    4.33       4.33       4.33       4.33
    Wakeup TQE Rate                   0.33       0.33       0.33       0.33


This example shows a relatively low over-all level of TQE processing, most of which has been requested by OpenVMS. Note that the last three rates approximately total the first rate.

MONITOR TRANSACTION

The MONITOR TRANSACTION command initiates monitoring of the TRANSACTION class, which shows information about transactions coordinated by DECdtm services.

Format

MONITOR TRANSACTION


Command Qualifiers

/qualifier[,...]

One or more qualifiers as described in the Command Qualifier Descriptions section.

Classname Qualifiers

/ALL

Specifies that a table of all available statistics (current, average, minimum, and maximum) is to be included in the display and summary output. For summary output, this qualifier is the default for all classes; otherwise, it is the default for all classes except CLUSTER, MODES, PROCESSES, STATES, SYSTEM, and VECTOR.

/AVERAGE

Specifies that a bar graph of average statistics is to be included in the display and summary outputs.

/CURRENT

Specifies that a bar graph of current statistics is to be included in the display and summary outputs. The /CURRENT qualifier is the default for the CLUSTER, MODES, STATES, SYSTEM, and VECTOR classes.

/MAXIMUM

Specifies that a bar graph of maximum statistics is to be included in the display and summary outputs.

/MINIMUM

Specifies that a bar graph of minimum statistics is to be included in the display and summary outputs.

Description

The TRANSACTION class consists of the following data items:
Data Item Description
Start Rate The rate at which new transactions are started on the local node.
Prepare Rate The rate at which transactions on the local node are placed in the Prepared state by DECdtm services.
One-Phase Commit Rate The rate at which transactions on the local node complete using the one-phase commit operation. This operation, which consumes significantly fewer system resources, is used when there is only a single resource manager participating in the transaction.
Total Commit Rate The rate at which transactions on the local node are committed. This value is the combined total of one-phase and two-phase commit transactions.
Abort Rate The rate at which transactions on the local node are aborted.
End Rate The rate at which transactions that were started on the local node are committed.
Remote Start Rate The rate at which transaction branches are started on the local node.
Remote Add Rate The rate at which transaction branches are added on the local node.
Completion Rate The rate at which transactions complete, indexed by their duration in seconds. The following list shows the Completion Rate categories:
Completion Rate 0--1 The number of transactions completed in 0--1 seconds (1 second or less)
Completion Rate 1--2 The number of transactions completed in 1--2 seconds
Completion Rate 2--3 The number of transactions completed in 2--3 seconds
Completion Rate 3--4 The number of transactions completed in 3--4 seconds
Completion Rate 4--5 The number of transactions completed in 4--5 seconds
Completion Rate 5+ The number of transactions that took more than 5 seconds to complete

For example, a transaction that completes in 0.5 second is included in the statistics displayed for the Completion Rate 0--1 category.


Examples

#1

MONITOR> MONITOR TRANSACTION/ALL








                           OpenVMS Monitor Utility
                       DISTRIBUTED TRANSACTION STATISTICS
                                 on node SAMPLE
                              16-JAN-2003 14:52:34

                                       CUR        AVE        MIN        MAX

    Start Rate                       34.76      34.76      34.76      34.76
    Prepare Rate                     33.77      33.77      33.77      33.77
    One Phase Commit Rate             0.00       0.00       0.00       0.00
    Total Commit Rate                35.09      35.09      35.09      35.09
    Abort Rate                        0.00       0.00       0.00       0.00
    End Rate                         35.09      35.09      35.09      35.09
    Remote Start Rate                31.12      31.12      31.12      31.12
    Remote Add Rate                  31.45      31.45      31.45      31.45

    Completion Rate    0-1           35.09      35.09      35.09      35.09
     by Duration       1-2            0.00       0.00       0.00       0.00
     in Seconds        2-3            0.00       0.00       0.00       0.00
                       3-4            0.00       0.00       0.00       0.00
                       4-5            0.00       0.00       0.00       0.00
                        5+            0.00       0.00       0.00       0.00

This example shows the status of all transactions on node SAMPLE.

#2

MONITOR> MONITOR TRANSACTION/MAXIMUM









                            OpenVMS Monitor Utility
            +-----+    DISTRIBUTED TRANSACTION STATISTICS
            | MAX |              on node SAMPLE
            +-----+           16-JAN-2003 14:51:04

                                     0         25        50        75       100
                                     + - - - - + - - - - + - - - - + - - - - -+
 Start Rate                       35 |**************
 Prepare Rate                     37 |**************
 One Phase Commit Rate               |
 Total Commit Rate                35 |**************
 Abort Rate                          |
 End Rate                         35 |**************
 Remote Start Rate                33 |*************
 Remote Add Rate                  32 |************
                                     |         |         |         |          |
 Completion Rate    0-1           35 |**************
  by Duration       1-2              |
  in Seconds        2-3              |
                    3-4              |
                    4-5              |
                     5+              |
                                     + - - - - + - - - - + - - - - + - - - - -+

This example shows the maximum statistics of all transactions on node SAMPLE.

MONITOR VBS (VAX Only)

On VAX systems, the MONITOR VBS command displays information about the processing of virtual balance slots (VBS).

Format

MONITOR VBS


Description

The MONITOR VBS command includes the following data items:
Data Item Description
RBS Fault Rate Rate at which processes fault from virtual balance slots into real balance slots (RBS)
CPU Utilization Amount of CPU time used by the operating system to support the virtual balance slot feature (at a rate of 10-millisecond clock ticks per second)

To see which processes have the highest RBS fault rates, issue the MONITOR PROCESSES/TOPRBS command.


Example


MONITOR> MONITOR VBS








                           OpenVMS Monitor Utility
                         VIRTUAL BALANCE SLOT STATISTICS
                                 on node SAMPLE
                              29-APR-2003 12:43:28

                                       CUR        AVE        MIN        MAX
     RBS Fault Rate                   4.62       3.80       0.33       7.61
     CPU Utilization                  0.99       0.24       0.00       0.99

This example shows the tabular style format for the VBS display.

MONITOR VECTOR

The MONITOR VECTOR command displays the number of 10-millisecond clock ticks per second in which one or more vector consumers have been scheduled on each currently configured vector processor in the system.

Format

MONITOR VECTOR


Command Qualifiers

/qualifier[,...]

One or more qualifiers as described in the Command Qualifier Descriptions section.

Classname Qualifiers

/ALL

Specifies that a table of all available statistics (current, average, minimum, and maximum) is to be included in the display and summary output. For summary output, this qualifier is the default for all classes; otherwise, it is the default for all classes except CLUSTER, MODES, PROCESSES, STATES, SYSTEM, and VECTOR.

/AVERAGE

Specifies that a bar graph of average statistics is to be included in the display and summary outputs.

/CURRENT

Specifies that a bar graph of current statistics is to be included in the display and summary outputs. The /CURRENT qualifier is the default for the CLUSTER, MODES, STATES, SYSTEM, and VECTOR classes.

/MAXIMUM

Specifies that a bar graph of maximum statistics is to be included in the display and summary outputs.

/MINIMUM

Specifies that a bar graph of minimum statistics is to be included in the display and summary outputs.

Description

The MONITOR VECTOR command displays the number of 10-millisecond clock ticks per second in which one or more vector consumers have been scheduled on each currently configured vector processor in the system. Because the operating system schedules vector consumers only on those processors identified as "vector present," the VECTOR class output never displays vector CPU time for those processors that are "vector absent."

Note that, because vector consumers can use either the vector CPU, the scalar CPU, or both components of a vector-present processor, the vector CPU time in the VECTOR class display is not a strict measure of the actual usage of the processor's vector CPU component. Rather, it indicates the time during which a scheduled vector consumer has reserved both vector CPU and scalar CPU components of the vector-present processor for its own exclusive use.

The VECTOR class consists of the data item Vector Scheduled Rate, which is represented by a display of statistics that show the rates of 10-millisecond clock ticks per second during which vector consumers have been scheduled on each vector-present CPU.


Example


MONITOR>  MONITOR VECTOR








                           OpenVMS Monitor Utility
                          VECTOR PROCESSOR STATISTICS
              +-----+             on node SAMPLE
              | CUR |          12-JUN-2003  22:52:42
              +-----+
 Vector Consumers Scheduled          0         25        50        75      100
                                     + - - - - + - - - - + - - - - + - - - - -+
 Vector Present CPU ID  0          13|*****
 Vector Absent  CPU ID  1            |
 Vector Absent  CPU ID  2            |
 Vector Present CPU ID  4          58|**********************
                                     |         |         |         |          |
                                     |         |         |         |          |
                                     |         |         |         |          |
                                     |         |         |         |          |
                                     |         |         |         |          |
                                     |         |         |         |          |
                                     + - - - - + - - - - + - - - - + - - - - -+

This example shows the VECTOR class display for a multiprocessing system containing two vector-present processors, CPU 0 and CPU 4. Displayed statistics represent rates of 10-millisecond clock ticks per second. For an average of 13 ticks per second over the last collection interval, vector consumers have been scheduled on CPU 0. For an average of 58 ticks per second over the last collection interval, vector consumers have been scheduled on CPU 4.

SET DEFAULT

The SET DEFAULT command sets command qualifier, classname parameter, and classname qualifier defaults for the MONITOR command. Each SET DEFAULT command sets only the command qualifiers you specify, but replaces the entire set of classname parameters and classname qualifiers. All qualifiers and class names are identical to those for the MONITOR command.

Format

SET DEFAULT [/qualifier[,...]] classname[,...] [/qualifier[,...]]


Parameters

classname[,...]

Specifies one or more class names.

Command Qualifiers

/qualifier[,...]

One or more command qualifiers as described in the Command Qualifier Descriptions section.

Classname Qualifiers

/qualifier[,...]

One or more classname qualifiers.

Description

Command and classname qualifiers are identical to those for the MONITOR classname commands.

Example


MONITOR> SET DEFAULT /INTERVAL=10 PAGE/AVERAGE+IO/MAXIMUM /NODE=(LARRY,MOE,CURLEY)
      

The command in this example selects PAGE and IO as the default classes for the MONITOR command and specifies an interval of 10 seconds for the statistics display. The command specifies that AVERAGE statistics be displayed for the PAGE class, and that MAXIMUM statistics be displayed for the IO class. Finally, the command requests that data be collected on nodes LARRY, MOE, and CURLEY. After establishing these defaults, you can enter the MONITOR command without any qualifiers or parameters to display the requested information.

SHOW DEFAULT

The SHOW DEFAULT command displays the defaults established by the SET DEFAULT command.

Format

SHOW DEFAULT


Parameters

None.

Qualifiers

None.

Description

The SHOW DEFAULT command verifies the defaults you have set with the SET DEFAULT command.

Example


MONITOR> SHOW DEFAULT








/BEGINNING = current time               /INTERVAL     = 10
/ENDING    = indefinite                 /VIEWING_TIME = 10

/FLUSH_INTERVAL = 300

/NOINPUT

/NORECORD

/DISPLAY   = SYS$OUTPUT:.;

/NOSUMMARY

/NOFILENAME

/NOCOMMENT

Classes:
 PAGE/AVERAGE              IO/MAXIMUM

Nodes:
 LARRY                     MOE                       CURLEY

The command in this example displays the defaults specified by the previous SET DEFAULT command.


Chapter 17
Point-to-Point Utility

17.1 PPPD Description

The Point-to-Point Protocol utility (PPPD) initiates and manages a Point-to-Point Protocol (PPP) network connection and its link parameters from an OpenVMS Alpha host system. This chapter describes the PPPD commands, with their parameters and qualifiers, that support PPP connections.

For information about the PPP driver and its programming interface, see the files PPP_INTERFACES.TXT and PPP_INTERFACES.PS in SYS$SYSROOT:[SYSHLP.EXAMPLES.PPPD.DOC].

17.2 PPPD Usage Summary

The Point-to-Point Protocol utility (PPPD) allows you to initiate and control a Point-to-Point Protocol (PPP)-compliant network connection from an OpenVMS Alpha host and define its physical link parameters.

Specifically, you can use this utility to:

  • Create an asynchronous (ASN) device. PPPD creates the device automatically if one is not currently associated with a serial port (such as TTA1).
  • Set both PPP and ASN device characteristics such as flow control and baud rate.
  • Inform the network stacks that there is a new physical transport that uses the PPP.
  • Act as a simple terminal emulator when establishing a connection to a new system (asynchronous only).
  • Display configuration information about the ASN and PPP device drivers as well as any ongoing PPPD sessions.

Format

$ PPPD

The utility then displays the following prompt:


PPPD>


Description

After invoking PPPD, you can perform PPPD operations by entering the appropriate commands. You can also enter a single PPPD command on the same line as the command that invokes the utility, for example:


$ PPPD CONNECT TTAO:

To exit from the Point-to-Point Protocol utility, enter the EXIT command at the PPPD> prompt or press Ctrl/Z. Either method returns control to the DCL command level.

For information about the PPPD utility, enter the HELP command at the PPPD> prompt.

17.3 PPPD Commands

This section describes and provides examples of the PPPD commands. If you need to customize your PPP settings, command qualifiers are provided. However, most users will be satisfied with the default settings.

Table 17-1 summarizes the PPPD command functions.

Table 17-1 PPPD Command Summary
Command Function
CONNECT Establishes a network connection through the current physical port or a specified remote port.
DIAL_OUT Allows direct access to a device to dial out over a modem or link to an external device.
DISCONNECT Terminates the network connection and returns control to the terminal driver.
EXIT Leaves the utility and returns you to the DCL command prompt ($).
HELP Displays help text for PPPD commands.
SET Determines the device and line characteristics for the specified terminal.
SHOW Displays the device and line characteristics of the specified terminal.

CONNECT

Establishes a network connection to a device located on the current physical port or specified remote port.

Format

CONNECT device-name[:]


Parameter

device-name[:]

Optional. Supplies the name of a device through which the network connection is made. The device name has the form ddcu where dd is the device code, c is the controller designation, and u is the unit number. LAN devices are specified as the name of the device that is unit 0. For example, the first terminal device on a LAN is specified as TTA0, the second as TTB0.

Qualifiers

None.

Description

The CONNECT command creates a link, or connection, to the device located on the current physical port or a specific remote port. When you enter this command, control passes to the PPP driver and an incoming transient network session is established. When the session is disconnected, the control of the host device returns to the terminal device driver.

Example


PPPD> CONNECT TTA1:
%PPPD-I-CONNECTTERM, converting connection on device _TTA1: to a
Point-to-Point connection
      

The command in this example creates a temporary network connection to the serial port TTA1. The port is ready to receive the PPP setup negotiations initiated by the host at the other end of the serial connection.

DIAL_OUT

Provides access to a specific physical device to dial a modem or link to an external device.

Format

DIAL_OUT device-name[:]


Parameter

device-name[:]

Supplies the name of a device over which the network connection is made. The device name has the form ddcu where dd is the device code, c is the controller designation, and u is the unit number. LAN devices are specified as the name of the device that is unit 0. For example, the first terminal device on a LAN is specified as TTA0, the second as TTB0.

Qualifiers

/BREAK=break-character

Specifies a character sequence that you can use to interrupt the signal being currently transmitted. To interrupt the signal, type Ctrl/break-character. You can select any ASCII character from @ though Z, except C, M, Q, S, and Y. The default break character is ~.

/DISCONNECT=disconnect-character

Specifies a character sequence that you can use to terminate DIAL_OUT mode. To disconnect the call, type Ctrl/disconnect-character. You can select any ASCII character from @ though Z, except C, M, Q, S, and Y. The default disconnect character is \.

/SWITCH=switch-character

Specifies a character sequence that you can use to switch the line to PPP mode. To activate PPP mode, type Ctrl/switch-character. You can select any ASCII character from @ though Z, except C, M, Q, S, and Y. The default switch character is @.

Similar to the CONNECT command, this qualifier switches a line into PPP mode. If the packet negotiations fail, PPPD exits and the line is left in terminal mode. If line is set to /MODEM and /NOHANGUP, this can result in extraneous data, the ASCII representation of Internet Protocol (IP) packets, being transmitted across the open line.


Description

The DIAL_OUT command directs access to a specific physical device to dial a modem or access an external device.

Example


PPPD> DIAL_OUT TTA0:
Type control-~ to send a break,
     control-\ to disconnect,
 and control-@ to switch to a point-to-point connection.

UNIVRS - Unauthorized access is prohibited
Username:   SEBASTIAN
Password:

   Welcome to OpenVMS (TM) Alpha Operating System, Version 7.3-1 on node UNIVRS
    Last interactive login on Tuesday, AUGUST 13, 2000 02:39 PM
    Last non-interactive login on Monday, AUGUST 12, 2000 02:16 PM

$  PPPD CONNECT
%PPPD-I-CONNECTTERM, converting connection on device _TTB0: to a
Point-to-Point connection
Ctrl-@
%PPPD-I-CONNECTTERM, converting connection on device _TTA1: to a
Point-to-Point connection
      

This example illustrates using PPP with a direct serial link.

DISCONNECT

Terminates the current network connection.

Format

DISCONNECT device-name[:]


Parameter

device-name[:]

Optional. Indicates the name of a device over which the network connection occurred. The device name has the form ddcu where dd is the device code, c is the controller designation, and u is the unit number. LAN devices are specified as the name of the device that is unit 0. For example, the first terminal device on a LAN is specified as TTA0, the second as TTB0.

Qualifiers

None.

Description

The DISCONNECT command terminates the physical link to a network, independent of the state of the upper-level protocols. The physical device reverts to the appropriate terminal driver and the upper-level protocols receive a hang-up event. This command is often used to clear and reset port communication settings in the case of a system pause.


PPPD> DISCONNECT TTA1:

The command in this example terminates the current network connection established through the serial port TTA1.

Note

A user must have the same UIC as the one on the ASNn: device for the connection, or have SYSPRV privilege to disconnect a serial port.

EXIT

Stops the execution of PPPD and returns control to the DCL command level. You can enter Ctrl/Z only if the line has not already been switched to PPP mode.

Format

EXIT


Parameters

None.

Qualifiers

None.

Description

Use the EXIT command to exit the utility.


PPPD> EXIT

The command in this example leaves the PPPD utility and returns control to the DCL command level.

HELP

Provides online help information for using the PPPD commands.

Format

HELP [command-name...]


Parameter

command-name

The name of a PPPD command or PPPD command and command keyword. If you enter the HELP command with a command name only, such as HELP SET, PPPD displays a list of all of the command keywords used with the SET command.

Description

The HELP command is an online reference for PPPD commands. After you view an initial help display, press Return. The help display stops and the PPPD prompt is displayed. If you do not specify a command name, the HELP command displays general information on the commands for which help is available. Supplying a command name obtains syntax information for that command.


PPPD> HELP DISCONNECT

In this example, the HELP DISCONNECT command produces a description of the DISCONNECT command and shows the command format.

SET

Sets the communication line characteristics for a specific terminal device.

Format

SET device-name[:]


Parameter

device-name

Indicates the name of the device whose characteristics are to be set. The device name has the form ddcu where dd is the device code, c is the controller designation, and u is the unit number. LAN devices are specified as the name of the device that is unit 0. For example, the first terminal device on a LAN is specified as TTA0, the second as TTB0.

Qualifiers

/ADDRESS_COMPRESSION (default)

/NOADDRESS_COMPRESSION

Indicates whether the address and control fields are compressed.

/CLEAR_COUNTERS=(keyword,...)

Determines which counters to clear when trying to resolve performance problems. The default is to clear all counters. With this qualifier, you can specify one or more of the following keywords:
Keyword Description
ALL Resets all counters.
BAD_FCS_PACKETS Resets the count of packets with a bad frame check sequence (FCS).
DATA_LOST Resets the count of lost characters that were reported by hardware.
DROPPED_CHARACTERS Resets the count of all characters thrown away.
FRAMING_ERRORS Resets the count of characters with framing errors.
LONG_PACKETS Resets the count of packets longer than the current maximum receive unit (MRU) setting.
RECEIVED_PACKETS Resets the count of total packets received.
RUNT_PACKETS Resets the count of packets with too few characters.
TOTAL_CHARACTERS Resets the count of all characters received.
TRANSMITTED_PACKETS Resets the count of total packets transmitted.

/CONNECT

Sets the line parameters and binds the ASN device to the physical terminal.

/ECHO=(FAILURE=value, INTERVAL=value)

Specifies the number of Link Control Protocol (LCP) echo requests and the interval between requests that must be sent without response before the line is considered down. The default number of echo requests is 0.

/FLOW_CONTROL=control-option

Indicates the type of flow control used over the physical link. You can specify one of the following keywords with this qualifier:
Keyword Description
HARDWARE Uses RTS/CTS flow control. If using this control, the transmit Asynch Control Character Map (ACCM) can be 0x0, 0x0, 0x0, 0x60000000. Only valid for lines set to /MODEM or /COMMSYNCH.
XON_XOFF (default) Uses band flow control. If using this control, the optimal transmit ACCM is 0xA0000, 0x0, 0x0, 0x60000000. Only valid for asynchronous lines.

/HANGUP

/NOHANGUP

Determines the action that occurs when a session is terminated. This qualifier notifies the ASN driver when a modem hangup is necessary due to an idle device. For example, when the last network connection is closed on a transient line that is set to /NOHANGUP, the line switches back to the terminal driver but the modem remains connected. This allows users to reaccess the line and log in without having to redial and reestablish the connection.

To use this qualifier, you must have PHY_IO privilege, or the line must have TT2$M_MODHANGUP already set.

/MAGIC_NUMBER_RETRIES=value

Specifies the number of attempts made to negotiate a magic number. Magic numbers are used to detect looped back connections. If you specify 0, no negotiations are made. If you specify 255, negotiation continues until a number is found. The default number of attempts is 5.

/MAXCONFIGURE=value

Indicates the number of configure-request packets sent without receiving a valid configure-ack, configure-nak, or configure-reject before assuming the peer is unable to respond. Specify a value in the range of 0 to 255. The default number of packets sent is 10.

/MAXFAILURE=value

Indicates the number of configure-nak packets sent without receiving a valid configure-ack before assuming that the configuration is not converging. Specify a value in the range of 0 to 255. The default number of packets sent is 5.

/MAXTERMINATE=value

Indicates the number of terminate-request packets sent without receiving a terminate-ack before assuming that the peer is unable to respond. Specify a value in the range of 0 to 255. The default number of packets is 2.

/MRU=size

Specifies the largest packet that can be received over the line. This value is used as part of the line negotiation, and the actual MRU setting can vary. Specify a value in the range of 6 to 1500. The default packet size is 1500.

/MTU=size

Specifies the largest packet that can be transmitted over the line. This value is used as part of the line negotiation, and the actual maximum transfer unit (MTU) setting can vary. Specify a value in the range of 6 to 1500. The default packet size is 1500.

/NETWORK_PROTOCOL=(protocol-name)

Specifies the the protocol allowed over the link. The default network protocol is TCP/IP.

/PASSIVE

/NOPASSIVE (default)

Notifies the PPP driver how to handle the PPP connection. It can either actively initiate the connection or wait for the remote host to start the connection.

/PERMANENT

/NOPERMANENT

Determines how the link is handled when a connection is closed or lost. If you specify /PERMANENT, the link remains in place with the PPP driver in control. If you specify /NOPERMANENT, the link is treated as a transient connection, and the terminal reverts to the terminal driver.

/PROTOCOL_COMPRESSION (default)

/NOPROTOCOL_COMPRESSION

Specifies whether the two octet protocol fields are compressed into a single octet.

/RECEIVE_ACCM=mask-value

Identifies the starting Asynch Control Character Map (ACCM). This mask is used by the PPP driver to negotiate the final ACCM for asynchronous ports. Specify a mask in the range of 0x0 to 0xFFFFFFFF. The default mask value is 0xFFFFFFFF, 0x0, 0x0, 0x60000000, 0x0, 0x0, 0x0. The masks are ordered from low-order longword to high-order longword. Specify the longword mask until the last mask bits are set. The remaining longwords are set to 0. With 8 longwords, there is 1 bit for every ASCII character position (from 0 to 255). The ASCII characters 0x20 through 0x3F and 0x5E cannot be quoted.

/RESTART_TIMER=msecs

Interval in milliseconds (msecs) used to time the transmission of configure-request and terminate-request packets. Expiration of the restart timer results in a timeout event and retransmission of the packet. Specify a value from 1 to 90. The default is 30 milliseconds (.03 seconds), which is intended for relatively slow speed links. For smaller, faster links, specify a smaller value.

/SPEED=(input-rate,output-rate)

Allows you to control the input and output speed of the line for asynchronous ports. To use this qualifier, you must have PHY_IO privilege, or the line must already have TT2$M_SETSPEED set.

Specify one of the following speeds: 50, 75, 100, 134, 150, 300, 600, 1200, 1800, 2400, 3600, 4800, 7200, 9600, 19200, 38400, 57600, 76800, or 115200. If your line allows split speed, you can specify different speeds for input and output. If you only specify one speed, it is used for both input and output.

/TRANSMIT_ACCM=mask-value,...

Identifies the starting Asynch Control Character Map (ACCM). This mask is used by the PPP driver to negotiate the final transmit ACCM for asynchronous ports. Specify a mask in the range of 0x0 to 0xFFFFFFFF. The default mask value is 0xFFFFFFFF, 0x0, 0x0, 0x60000000, 0x0, 0x0, 0x0. The masks are ordered from low-order longword to high-order longword. Specify the longword mask until the last mask bits are set. The remaining longwords are set to 0. With 8 longwords, there is 1 bit for every ASCII character position (from 0 to 255). The ASCII characters 0x20 through 0x3F and 0x5E cannot be quoted.

Description

Use the SET command to specify the communications characteristic of a terminal device. Communications characteristics such as address compression, flow control, and line speed determine how data is transmitted and received. These characteristics take effect as soon as you invoke the CONNECT or DIAL_OUT command.

Note

If you you invoke a SET command from the DCL command line (for example, PPPD SET/MTU=1000 tta0), the utility assumes you wish to connect and attempt to start a PPP connection on the specified device.


PPPD> SET/PERMANENT TTA0:
%PPPD-I-CONNECTTERM, converting connection on device _TTA0: to a
Point-to-Point connection

In this example, the SET command is setting up a permanent network connection over the serial port TTA0.

SHOW

Allows you to display the communication characteristics for a specific terminal.

Format

SHOW device-name[:]


Parameter

device-name[:]

Supplies the name of the device whose characteristics are to be displayed. The device name has the form ddcu where dd is the device code, c is the controller designation, and u is the unit number. LAN devices are specified as the name of the device that is unit 0. For example, the first terminal device on a LAN is specified as TTA0, the second as TTB0.

Qualifiers

/ADDRESS_COMPRESSION

Indicates whether the address compression is on or off.

/ALL[=BRIEF] (default)

/ALL[=LONG]

Displays all the current device and communication settings. BRIEF formats the output for the screen. LONG displays each setting on a separate line.

/COUNTERS=(keyword,...)

Shows the current values for the specified counter(s). You can specify one or more of the following keywords with this qualifier:
Keyword Description
ALL Displays all counters.
BAD_FCS_PACKETS Displays the count of packets with bad frame check sequence (FCS).
DATA_LOST Displays the count of lost characters that were reported by hardware.
DROPPED_CHARACTERS Displays the count of all characters thrown away.
FRAMING_ERRORS Displays the count of characters with framing errors.
LONG_PACKETS Displays the count of packets longer than the current maximum receive unit setting (MRU).
RECEIVED_PACKETS Displays the count of total packets received.
RUNT_PACKETS Displays the count of packets with too few characters.
TOTAL_CHARACTERS Displays the count of all characters received.
TRANSMITTED_PACKETS Displays the count of total packets transmitted.

/ECHO=(FAILURE=value, INTERVAL=value)

Specifies the number of Link Control Protocol (LCP) echo requests and the interval (in milliseconds) between requests that must be sent without response before the line is considered down.

/FCS_SIZE

Shows the current receive and transmit FCS size in bits.

/FLOW_CONTROL=(keyword,...)

Shows the current flow control setting used over the asynchronous physical link. You can specify one of the following keywords with this qualifier:
Keyword Description
HARDWARE Uses RTS/CTS flow control. If using this control, the transmit Asynch Control Character Map (ACCM) can be 0x0, 0x0, 0x0, 0x60000000. Only valid for lines set to /MODEM or /COMMSYNCH.
XON_XOFF (default) Uses band flow control. If using this control, the optimal transmit ACCM is 0xA0000, 0x0, 0x0, 0x60000000. Only valid for asynchronous lines.

/HANGUP

Displays the action that occurs when a session is terminated.

/MAGIC_NUMBER_RETRIES

Shows the number of attempts that are made to negotiate a magic number.

/MAXCONFIGURE

Shows the number of configure-request packets sent without acknowledgment before assuming that the peer is not responding.

/MAXFAILURE

Displays the number of configure-nak packets sent before sending a configure-ack and before assuming that the configuration is not converging.

/MAXTERMINATE

Shows the number of terminate-request packets sent without acknowledgment before assuming the peer is unable to respond.

/MRU

Displays the largest packet that the line can receive.

/MTU

Displays the largest packet that the line can transmit.

/NETWORK_PROTOCOL

Displays the current network protocol(s) allowed over the physical link.

/PASSIVE

Indicates whether this is a passive or active line.

/PERMANENT

Indicates whether this is a permanent or transient (nonpermanent) line.

/PROTOCOL_COMPRESSION

Shows the status of protocol field compression.

/RECEIVE_ACCM

Displays the value of the current receive ACCM for asynchronous ports.

/RESTART_TIMER

Displays the interval used to time transmission of request packets.

/SPEED

Indicates the current input and output speeds of the line.

/TRANSMIT_ACCM

Displays the value of the current transmit ACCM for asynchronous ports.

Description

The SHOW command allows you display the current terminal and communication settings. To display all available settings, use the /ALL qualifier.


PPPD> SHOW/ALL=BRIEF TTA0:
Line TTA1: is being used for PPP connections

Debug trace:     OFF       Debug mailbox:
Address comp:    OFF       Max configure:        10  Restart timer:        30
ASN port name:   ASN13     Max failure:           5
Echo failure:           0  Max terminate:         2  Receive ACCM:   FFFFFFFF
Echo intervals:         0  MRU:                1500  Transmit ACCM:  FFFFFFFF
Flow control:    XON/XOFF  MTU:                1500                  00000000
Hangup:          DEFAULT   Mode:           ACTIVE                    00000000
Line type:       TRANSIENT Net protocol:   TCP/IP                    60000000
Magic retries:          0  Protocol comp:  OFF                       00000000
Input speed:     DEFAULT   Receive FCS:          16                  00000000
Output speed:    DEFAULT   Transmit FCS:         16

Counter totals for line TTA0:

Bad FCS packets:                   0   Packets received:                  4
Data lost (chars):                 0   Packets transmitted:               6
Dropped chars:                     0   Runt packets:                      0
Framing errors:                    0   Total chars received:            179
Long packets:                      0

The command in this example displays the current PPP characteristics assigned to port TTA1.


Chapter 18
POLYCENTER Software Installation Utility

18.1 Description

The POLYCENTER Software Installation utility creates, installs, and manages software products. You can use it to do the following:
  • Install and reconfigure software products.
  • Remove software products.
  • Display information from the software product database, such as the names of installed products, the names of patches applied, product dependencies, the names of files provided by product, and historical information about past operations.
  • Locate software product kits that can be installed.
  • Create a software product kit in sequential, compressed, or reference format.
  • List the contents of a software product kit or extract files from the kit, such as release notes or files you specify.
  • Perform other operations such as establishing default configuration choices offered by a product, copying a product kit or converting it to a different format, and registering information about a product in the product database.
  • Uninstall the last patch or set of patches applied to a product.

18.2 Usage Summary

The DCL interface to the POLYCENTER Software Installation utility is the PRODUCT command.


Format

PRODUCT [subcommand product-name [/qualifiers]]


Parameters

subcommand

Specifies an operation you want the POLYCENTER Software Installation utility to perform. If you do not supply a subcommand, the utility prompts you to select one from a list.

product-name

Specifies the name of the product to which you want to apply the activity. Some subcommands do not require this parameter. You can use the asterisk (*) and the percent sign (%) wildcard characters for all or part of the product-name. You can specify a list of products separated by commas (,).

The product name is the same as the third component of the file name of the product kit. For example, the product name parameter that you would use to refer to a kit named DEC-AXPVMS-FORTRAN-V0702-3-1.PCSI is FORTRAN. A product name can include an underscore character (_) but never a hyphen (-). For example, VMS73_DRIVER is the name of a remedial kit for OpenVMS whose file name is DEC-AXPVMS-VMS73_DRIVER-V0300--4.PCSI.


Description

To use the POLYCENTER Software Installation utility from the DCL prompt, enter the PRODUCT command, a subcommand, and any required parameters and optional qualifiers. For example:


  $ PRODUCT INSTALL FORTRAN /VERSION=V7.2-3 /SOURCE=DISK1:[KITS]

This command installs FORTRAN V7.2-3 on your system from a product kit located in DISK1:[KITS].

18.3 PRODUCT Commands

The following table describes PRODUCT subcommands:

Subcommand Description
CONFIGURE Creates a product configuration file (PCF)
COPY Copies a software product kit or converts it to another format
DELETE RECOVERY_DATA Deletes one or more patch recovery data sets
EXTRACT FILE Retrieves a specified file or files from a software product kit
EXTRACT PDF Retrieves the product description file (PDF) from a software product kit
EXTRACT PTF Retrieves the product text file (PTF) from a software product kit
EXTRACT RELEASE_NOTES Retrieves the release notes from a software product kit
FIND Displays the name of product kits found in a specified directory
INSTALL Installs one or more software products and updates the product database
LIST Lists the files contained in a software product kit
PACKAGE Creates a software product kit in either sequential or reference format.
RECONFIGURE Modifies the configuration of an installed product and updates the product database
REGISTER PRODUCT Records information in the product database about one or more installed products that are not yet registered in the database
REGISTER VOLUME Records a change in volume label in the product database
REMOVE Uninstalls one or more software products and updates the product database
SHOW HISTORY Displays in chronological order the operations performed on software products
SHOW OBJECT Displays information about objects created during software product installation
SHOW PRODUCT Displays information about installed products
SHOW RECOVERY_DATA Displays patch recovery data sets in chronological order
SHOW UTILITY Displays version information about the POLYCENTER Software Installation utility
UNDO PATCH Uninstalls one or more patches for which recovery data has been saved

CONFIGURE

Creates a product configuration file (PCF) for one or more products. Optionally uses the values in an existing PCF file to create the new PCF.

Format

PRODUCT CONFIGURE product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products, for which product configuration files will be generated.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/CONFIGURATION=(keyword[,...])

Specifies how the configuration choices will be supplied. Keywords are:
CURRENT This is the default. It uses values from the product database, which contains the current values recorded from the last time the product was installed or reconfigured.
PRODUCER Uses values specified by the software manufacturer for this version of the product.
INPUT=pcf-name Uses values from the specified product configuration file.
OUTPUT=pcf-name Writes configuration choices to the specified product configuration file. If no file name is supplied, creates a file named DEFAULT.PCSI$CONFIGURATION in the current default directory.
The keywords CURRENT, PRODUCER, and INPUT are mutually exclusive. Each of these, however, can be used with the keyword OUTPUT. If you specify only one keyword, you can omit the parentheses.

/HELP

/NOHELP (default)

Controls whether detailed explanations of product options and informational text are displayed. The first time you install a product, these explanations can help you decide which options to select. When you perform subsequent installations or upgrades, you might choose the brief explanations to save time.

When /NOHELP is selected, you can request a detailed explanation about a question by performing one of the following actions at the prompt:

  • Press the Help key or PF2 key
  • Type ? and press the Return key

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
   
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
MANDATORY_UPDATE A required correction to currently installed software. Functionally, this type of kit is the same as a patch kit.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PATCH A correction to currently installed software. Installation of this kit does not change the version of the product.
PLATFORM An integrated set of software products (also called a product suite).

/LOG

/NOLOG (default)

Displays the file specification of the configuration file that is created.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/REMOTE

/NOREMOTE (default)

Selects the product database located on a privately mounted system disk. By default, this utility searches the currently booted system disk for the product database.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location defined by the logical name PCSI$SOURCE. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=version-number

Selects software products that have the specified version.

Example


$ PRODUCT CONFIGURE EDITOR -
_$ /CONFIGURATION=(INPUT=EDITOR_REV1.PCF,OUTPUT=EDITOR_REV2.PCF)

      

The command in this example reads an existing PCF file named EDITOR_REV1.PCF for a product named EDITOR and then saves your changes in EDITOR_REV2.PCF.

COPY

Copies or converts one or more existing product kits that you specify to product kits in the format you request. For example, you can create a kit in reference format from a kit in sequential format, create a compressed kit from a kit in sequential format, or simply copy a kit to a new location without changing its format.

You cannot create a kit in compressed format directly from a kit in reference format. If you do not have a kit in sequential format, you must first use the PRODUCT PACKAGE command to create a sequential kit from the product materials. Then you can use the PRODUCT COPY command to convert it to compressed format.

Use the /FORMAT qualifier to determine the format of the product kits that you create. Use the /KIT_ATTRIBUTES=FORMAT qualifier to select kits of a particular format to be copied or converted.


Format

PRODUCT COPY product-name /DESTINATION=device-name:[directory-name] [/qualifiers]


Parameter

product-name

Names the product, or list of products, to copy.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/DESTINATION=device-name:[directory-name]

Specifies a location where the utility will create the sequential or compressed kit. For a reference kit, specifies the top-level directory location where the utility will place files.

If you do not provide a device name, the default is the user's default device. If you omit the directory name, the default is the user's default directory.

The PRODUCT COPY operation ignores the PCSI$DESTINATION logical name whether or not you use the /DESTINATION qualifier.

/FORMAT=keyword

Specifies the output format of the product kit. Keywords are:
   
COMPRESSED Compressed format in which a data compression technique is applied to a sequential kit to produce a .PCSI$COMPRESSED file, which is the compressed form of a sequential kit.
REFERENCE Reference format in which product files are placed in a directory tree for direct access. The utility creates a product description file, with a file type of .PCSI$DESCRIPTION, in the top level of the directory tree.
SEQUENTIAL Sequential format in which product files are placed in a container file having a .PCSI file type.
The default is to preserve the format of the product kit. You must use this qualifier if you want to change the format of the product kit.

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
MANDATORY_UPDATE A required correction to currently installed software. Functionally, this type of kit is the same as a patch kit.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PATCH A correction to currently installed software. Installation of this kit does not change the version of the product.
PLATFORM An integrated set of software products (also called a product suite).
TRANSITION Used to register information about a product that is installed but not recorded in the product database (for example, a product installed by VMSINSTAL). This kit does not provide product material.

/LOG

/NOLOG (default)

Displays the file specification of the product kit file that is created and the files packaged in the kit.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.

/OWNER_UIC=uic

Specifies the owner user identification code (UIC) for files created during a copy operation. By default, the user executing the operation owns the software product files. For example, if you are logged in to your own account, you can use this qualifier during a copy operation to assign ownership of the product files to SYSTEM rather than to your own account. Specify the UIC in alphanumeric format (in the form [name]) or in octal group-member format (in the form [g,m]). UIC formats are described in the OpenVMS User's Manual.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location defined by the logical name PCSI$SOURCE. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=version-number

Selects software products that have the specified version.

Example


$ PRODUCT COPY ABC /SOURCE=[SHERMAN.ABC] -
_$ /DESTINATION=[KITS] /FORMAT=SEQUENTIAL
      

The command in this example converts product kit ABC, located in the [SHERMAN.ABC] directory on the user's default device, to a sequential copy in the [KITS] directory on the user's default device.

DELETE RECOVERY_DATA

Deletes one or more patch recovery data sets in order of creation date, starting with the oldest one first. A recovery data set is created when a patch kit is successfully installed with the /SAVE_RECOVERY_DATA qualifier. Recovery data sets are used to uninstall patches when you use the PRODUCT UNDO PATCH command.

Note that once patch recovery data is deleted, you cannot uninstall any patch that is associated with this data. Installed patches are not affected when you use the PRODUCT DELETE RECOVERY_DATA command.


Format

PRODUCT DELETE RECOVERY_DATA [/qualifiers]


Parameters

None.

Qualifiers

/ALL (default)

Selects all patch recovery data sets to be deleted. The recovery data is deleted in the order it was created, starting with the oldest set first. If you omit this qualifier from the command line, the effect is the same as if you specified it.

/BEFORE=time

Selects patch recovery data sets created before the specified date and time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords:


    TODAY (default)
    TOMORROW
    YESTERDAY

Refer to the OpenVMS User's Manual for information about specifying time values.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the recovery data sets that have been selected for processing.

/LOG

/NOLOG (default)

Displays the file specifications of the files within the recovery data sets that are being deleted.

/OLDEST=count

Specifies the number of oldest recovery data sets that you want to delete. For example, if you specify /OLDEST=2, the PRODUCT DELETE RECOVERY_DATA command deletes the two oldest recovery data sets. If you do not specify a number with this qualifier, the default value is 1.

/REMOTE

/NOREMOTE (default)

Selects recovery data sets located on a privately mounted system disk. By default, this utility searches the currently booted system disk for recovery data sets.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

Example


$ PRODUCT DELETE RECOVERY_DATA /OLDEST=2
      

The command in this example deletes the two oldest recovery data sets starting with the one that was created first, followed by next oldest recovery data set. If, for example, three patch recovery data sets are on the system disk, you still have one set preserved after this operation completes.

Remember that once a patch recovery data set is deleted, you cannot uninstall the patch kit associated with the deleted recovery data. The installed patch kits, however, are not affected by this action.

EXTRACT FILE

Retrieves a user-specified file or files from a software product kit. The original name of the file is preserved when it is extracted.

Format

PRODUCT EXTRACT FILE product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products, from whose kits the selected file or files are to be retrieved. This parameter is required.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/DESTINATION=device-name:[directory-name]

Specifies the location where the utility is to place all the files that the user indicates are to be retrieved. If the device name is not provided, the default is the user's default device. If the directory name is omitted, or the /DESTINATION= qualifier is not specified, the default is the user's default directory. The EXTRACT FILE operation ignores the PCSI$DESTINATION logical name whether or not you use the /DESTINATION qualifier.

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
MANDATORY_UPDATE A required correction to currently installed software. Functionally, this type of kit is the same as a patch kit.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PATCH A correction to currently installed software. Installation of this kit does not change the version of the product.
PLATFORM An integrated set of software products (also called a product suite).
TRANSITION Used to register information about a product that is installed but not recorded in the product database (for example, a product installed by VMSINSTAL). This kit does not provide product material.

/LOG

/NOLOG (default)

Displays the file specifications of the files that are extracted from the kit.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/SELECT=filename[,...]

Specifies the name of a file, or a list of files, to be extracted from the specified product kit. You can use the asterisk (*) and the percent sign (%) wildcard characters for all or part of the file name. The file name can contain a directory specification that includes an ellipsis (...). If you omit this qualifier, all files will be extracted from the specified kit or kits.

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location that the logical name PCSI$SOURCE defines. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=version-number

Selects software products that have the specified version.

Example


$ PRODUCT EXTRACT FILE TEST /SELECT=TEST.EXE /SOURCE=[AL]
      

In this example, the POLYCENTER Software Installation utility extracts the file TEST.EXE from the kit of the product TEST that is in the [AL] directory on the user's default disk. The extracted file TEST.EXE is placed in the user's current default directory.

EXTRACT PDF

Retrieves the product description file (PDF) from a software product kit. The file type of the extracted PDF file is .PCSI$DESCRIPTION.

Format

PRODUCT EXTRACT PDF product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products, whose PDF file is to be retrieved from the kit.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/DESTINATION=device-name:[directory-name]

Specifies the location where the utility is to place the extracted product description file (PDF). If the device name is not provided, the default is the user's default device. If the directory name is omitted, or the /DESTINATION= qualifier is not specified, the default is the user's default directory. The EXTRACT PDF operation ignores the PCSI$DESTINATION logical name whether or not you use the /DESTINATION qualifier.

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
MANDATORY_UPDATE A required correction to currently installed software. Functionally, this type of kit is the same as a patch kit.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PATCH A correction to currently installed software. Installation of this kit does not change the version of the product.
PLATFORM An integrated set of software products (also called a product suite).
TRANSITION Used to register information about a product that is installed but not recorded in the product database (for example, a product installed by VMSINSTAL). This kit does not provide product material.

/LOG

/NOLOG (default)

Displays the file specification of the product description file that is created.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location that the logical name PCSI$SOURCE defines. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=version-number

Selects software products that have the specified version.

Example


$ PRODUCT EXTRACT PDF TEST /SOURCE=[AL]
      

In this example, the POLYCENTER Software Installation utility extracts the product description file (PDF) from the kit of the product TEST that is in the [AL] directory on the user's default disk and places it in the user's current default directory.

EXTRACT PTF

Retrieves the product text file (PTF) from a software product kit. The PTF file is stored in a product kit as a text library file. The file type of the extracted PTF is .PCSI$TLB. In addition, a text file version of this text library file is created with a file type of .PCSI$TEXT.

Format

PRODUCT EXTRACT PTF product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products, whose PTF file is to be retrieved from the kit.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/DESTINATION=device-name:[directory-name]

Specifies the location where the utility is to place the extracted product text file (PTF). If the device name is not provided, the default is the user's default device. If the directory name is omitted, or the /DESTINATION= qualifier is not specified, the default is the user's default directory. The EXTRACT PTF operation ignores the PCSI$DESTINATION logical name whether or not you use the /DESTINATION qualifier.

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
MANDATORY_UPDATE A required correction to currently installed software. Functionally, this type of kit is the same as a patch kit.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PATCH A correction to currently installed software. Installation of this kit does not change the version of the product.
PLATFORM An integrated set of software products (also called a product suite).
TRANSITION Used to register information about a product that is installed but not recorded in the product database (for example, a product installed by VMSINSTAL). This kit does not provide product material.

/LOG

/NOLOG (default)

Displays the file specifications of the product text and product text library files that are created.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location that the logical name PCSI$SOURCE defines. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=version-number

Selects software products that have the specified version.

Example


$ PRODUCT EXTRACT PTF TEST /SOURCE=[AL]
      

In this example, the POLYCENTER Software Installation utility extracts the product text file (PTF) from the kit of the product TEST that is in the [AL] directory on the user's default disk and places two files in the user's current default directory: the extracted text library file (.PCSI$TLB) and a text file (.PCSI$TEXT) created from the library.

EXTRACT RELEASE_NOTES

Retrieves the release notes for the selected product or group of products. The name of each release notes file is preserved unless you override it with the /FILE qualifier.

Format

PRODUCT EXTRACT RELEASE_NOTES product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products, from which to extract release notes.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/FILE=filespec

Specifies the name of the output file that will contain the release notes. If no file name is given, the original name of the release notes file is preserved and the file is written to your default directory.

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
MANDATORY_UPDATE A required correction to currently installed software. Functionally, this type of kit is the same as a patch kit.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PATCH A correction to currently installed software. Installation of this kit does not change the version of the product.
PLATFORM An integrated set of software products (also called a product suite).

/LOG

/NOLOG (default)

Displays the file specification of the release notes file that is created.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location that the logical name PCSI$SOURCE defines. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=version-number

Selects software products that have the specified version.

/WORK=device:[directory]

Specifies the name of the device and directory acting as a temporary work area. By default, temporary files are created in subdirectories of the user's login directory.

Example


$ PRODUCT EXTRACT RELEASE_NOTES XYZ /VERSION=2.3/FILE=[RN]XYZ.TXT
      

The command in this example places the release notes for Version 2.3 of the product XYZ in a file named [RN]XYZ.TXT on your current default device.

FIND

Displays the names of software product kits located in the specified directory, along with kit type and kit format information.

Format

PRODUCT FIND product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products to find.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/FULL

/NOFULL (default)

Displays information in 132-column format. The /NOFULL qualifier displays a subset of available information in 80-column format.

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
MANDATORY_UPDATE A required correction to currently installed software. Functionally, this type of kit is the same as a patch kit.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PATCH A correction to currently installed software. Installation of this kit does not change the version of the product.
PLATFORM An integrated set of software products (also called a product suite).
TRANSITION Used to register information about a product that is installed but not recorded in the product database (for example, a product installed by VMSINSTAL). This kit does not provide product material.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location defined by the logical name PCSI$SOURCE. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=version-number

Selects software products that have the specified version.

Example


$ PRODUCT FIND TEST* /BASE_SYSTEM=VAXVMS
      

The command in this example searches for all software product kits located in the user's default directory and displays the names of all versions of products whose names begin with "TEST" and are intended to be installed on OpenVMS VAX.

INSTALL

Installs one or more software products on your system and updates the product database. You can also use this command to install patch and mandatory update kits that modify previously installed products.

To uninstall complete products, including any patches or mandatory updates that might have been applied to them, use the PRODUCT REMOVE command.

To uninstall patches or mandatory updates while still retaining the original product that was installed, use the PRODUCT UNDO PATCH command. However, to use this command, you must use the /SAVE_RECOVERY_DATA qualifier on the PRODUCT INSTALL command when you install these patches and mandatory updates.


Format

PRODUCT INSTALL product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products, to install.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/CONFIGURATION=(keyword[,...])

Specifies how the configuration choices will be supplied. Keywords are:
CURRENT This is the default. It uses values from the product database, which has the current values recorded from the last time the product was installed or reconfigured.
PRODUCER Uses values specified by the software manufacturer for this version of the product.
INPUT=pcf-name Uses values from the specified product configuration file.
OUTPUT=pcf-name Writes configuration choices to the specified product configuration file. If no file name is supplied, creates a file named DEFAULT.PCSI$CONFIGURATION.
The keywords CURRENT, PRODUCER, and INPUT are mutually exclusive. Each of these, however, can be used with the keyword OUTPUT. If you specify only one keyword, you can omit the parentheses.

/DESTINATION=device-name:[directory-name]

Specifies a location where the utility will install software product files. If you omit the device name, the utility uses your current default device. If you omit the directory name, the utility uses the [VMS$COMMON] directory as the default directory.

If you do not use this qualifier to specify a destination, the utility installs the software in the location defined by logical name PCSI$DESTINATION. If this logical name is not defined, the utility installs the software in SYS$SYSDEVICE:[VMS$COMMON], the top-level directory for software product files.

/HELP

/NOHELP (default)

Controls whether detailed explanations of product options and informational text are displayed. The first time you install a product, these explanations can help you decide which options to select. When you perform subsequent installations or upgrades, you might choose the brief explanations to save time.

When /NOHELP is selected, you can request a detailed explanation about a question by performing one of the following actions at the prompt:

  • Press the Help key or PF2 key
  • Type ? and press the Return key

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
MANDATORY_UPDATE A required correction to currently installed software. Functionally, this type of kit is the same as a patch kit.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PATCH A correction to currently installed software. Installation of this kit does not change the version of the product.
PLATFORM An integrated set of software products (also called a product suite).

/LOG

/NOLOG (default)

Displays the file specification of each file processed. When logging is enabled, messages notify you whenever product files, libraries, directories, temporary files, and product database files are created, deleted, or modified. Information about any file and module conflict resolution is also provided.

/OPTIONS=(keyword[,...])

/NOOPTIONS (default)

Specifies PRODUCT command options. Keywords are:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.
SHOW_DISK_USAGE Displays estimated disk block usage. Both peak utilization and net change are shown in addition to the amount of free space available before and after the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/RECOVERY_MODE

/NORECOVERY_MODE (default)

Allows you to perform product installation in recovery mode. When you use this qualifier, the directories, files, and modules that are modified, deleted, or removed in the installation process are saved in a directory tree on the system disk. These files, along with a copy of the product database, comprise the recovery data set.

The recovery data set is handled somewhat differently when an installation ends successfully or if it terminates, at some point, unsuccessfully.

  • If an installation terminates in its execution phase, either voluntarily (by using Ctrl/Y or Ctrl/C) or involuntarily (because of a fatal error), the saved recovery data is used to roll back all the displaced objects in an attempt to reinstate the product environment prior to the interrupted operation. Then the recovery data set is deleted.
  • At the end of a successful installation of one or more full, platform, or partial kits, the recovery data set is automatically deleted.
  • At the end of a successful installation of one or more patch or mandatory update kits, the recovery data set is automatically deleted unless you specify the /SAVE RECOVERY_DATA qualifier. This qualifier retains the recovery data set for possible future use with the PRODUCT UNDO PATCH command.

/REMARK=string

Records a comment in the product database about the task you are performing. The PRODUCT SHOW HISTORY command displays the recorded comments. For each product, the POLYCENTER Software Installation utility stores a chronological list of tasks you perform and the associated remarks. The default behavior is that no remark is recorded.

/REMOTE

/NOREMOTE (default)

Selects the product database located on a privately mounted system disk. By default, this utility searches the currently booted system disk for the product database.

This qualifier is primarily for use in command procedures that HP supplies. Incorrect use of this qualifier can create an inconsistency in the product database or cause subsequent PRODUCT commands to fail.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/SAVE_RECOVERY_DATA

/NOSAVE_RECOVERY_DATA (default)

This qualifier applies only to patch and mandatory update kit installation. It is ignored when other types of products are installed.

This qualifier causes all the directories, files, and modules that are modified, deleted, or removed in the process of installation to be saved in a directory tree on the system disk. These files, along with a copy of the product database, comprise the recovery data set. This recovery data set can be used later to uninstall patch and mandatory update kits by using the PRODUCT UNDO PATCH command.

Note that the /SAVE_RECOVERY_DATA qualifier automatically enables recovery mode operation even if you do not explicitly specify the /RECOVERY_MODE qualifier.

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location defined by the logical name PCSI$SOURCE. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/TEST (default)

/NOTEST

Requests that the POLYCENTER Software Installation utility run the installation verification procedure (IVP) for the product.

/TRACE

/NOTRACE (default)

Identifies DCL commands and command procedures that are run in a subprocess during the execution of the PRODUCT command. Any output from these commands is also displayed.

This qualifier is primarily a debugging aid for product developers to trace the execution of non-interactive command procedures embedded in their product kits. This qualifier is not useful for command procedures running in interactive mode. See the POLYCENTER Software Installation Utility Developer's Guide for more information.

/VERSION=version-number

Selects software products that have the specified version.

/WORK=device:[directory]

Specifies the name of the device and directory acting as a temporary work area. By default, temporary files are created in subdirectories of the user's login directory.

Example


$ PRODUCT INSTALL POSIX/VERSION=3.0 /CONFIGURATION=OUTPUT=POSIX.PCF

      

The command in this example installs POSIX Version 3.0 and creates a product configuration file.

LIST

Lists the names of the files contained in a software product kit. All files are listed unless you use the /SELECT qualifier to specify a subset of the files.

Format

PRODUCT LIST product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products, whose kit contents are to be listed. This parameter is required.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/FULL

/NOFULL (default)

Displays information about files contained in the kit in 132-column format. The /FULL qualifier shows the name of each file, gives its size in blocks, and provides a comment field that can provide additional information---for example, the file is a product description file, a temporary file, or a module file that updates a library file. The /NOFULL qualifier displays only the name of each file in the kit in 80-column format.

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
MANDATORY_UPDATE A required correction to currently installed software. Functionally, this type of kit is the same as a patch kit.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PATCH A correction to currently installed software. Installation of this kit does not change the version of the product.
PLATFORM An integrated set of software products (also called a product suite).
TRANSITION Used to register information about a product that is installed but not recorded in the product database (for example, a product installed by VMSINSTAL). This kit does not provide product material.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/SELECT=filename[,...]

Specifies the name of a file, or a list of files; these files are in the specified product kit. You can use the asterisk (*) and the percent sign (%) wildcard characters for all or part of the file name. The file name can contain a directory specification that includes an ellipsis (...).

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location that the logical name PCSI$SOURCE defines. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=version-number

Selects software products that have the specified version.

Example


$ PRODUCT LIST TEST /SELECT=TEST.* /SOURCE=[AL]
      

In this example, the POLYCENTER Software Installation utility lists all the files that match the selection criteria TEST.* from the kit of the product TEST that is in the [AL] directory on the user's default disk.

PACKAGE

Creates a software product kit. This operation uses a product description file (PDF) and an optional product text file (PTF) to produce a kit that contains the images and other files that make up the product.

During a package operation, the POLYCENTER Software Installation utility reformats the input PDF file to produce a new output PDF file. Comments are removed from the output PDF file and information, such as the size of each file, is added. The input PTF file is transformed into an output PTF in text library format.

The PRODUCT PACKAGE command can create a product kit in either sequential or reference format. To create a kit in compressed format, first use the PRODUCT PACKAGE command to create a kit in sequential format. Then use the PRODUCT COPY command to convert this sequential kit to a kit in compressed format.

The PRODUCT PACKAGE command requires the /SOURCE, /DESTINATION, and /MATERIAL qualifiers.


Format

PRODUCT PACKAGE product-name[,...] [/qualifiers] /SOURCE=file-specification /DESTINATION=device-name:[directory-name] /MATERIAL=(path-name[,...])


Parameter

product-name

Names the product or list of products to be packaged.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/COPY(default)

/NOCOPY

Specifies whether you want the product material files and associated directories included in the product kit when you are producing a kit in reference format. The /NOCOPY qualifier can save file processing time when you are debugging a PDF file and do not need to produce a complete product kit.

The /NOCOPY and /FORMAT=SEQUENTIAL qualifiers are mutually exclusive.

/DESTINATION=device-name:[directory-name]

If /FORMAT=SEQUENTIAL is used, /DESTINATION specifies the directory where the utility creates the sequential kit. A sequential kit is a container file that includes the PDF, PTF, and all the images and other materials that make up the product. The file type of the sequential kit file is .PCSI.

If /FORMAT=REFERENCE is used (or defaulted), /DESTINATION specifies the directory where the utility creates the output PDF file and optional PTF file. The file types of the PDF and PTF files are .PCSI$DESCRIPTION and .PCSI$TLB, respectively. The images and other materials that make up the product are placed in a directory tree under this directory.

If the device name is not provided, it defaults to the user's default device. If the directory name is omitted, it defaults to the user's default directory.

The PRODUCT PACKAGE operation ignores the PCSI$DESTINATION logical name whether or not you use the /DESTINATION qualifier.

/FORMAT=keyword

Specifies the output format of the product kit. Keywords are:
REFERENCE Reference format in which product files are placed in a directory tree for direct access. The utility creates a product description file, with a file type of .PCSI$DESCRIPTION, in the top level of the directory tree.
SEQUENTIAL Sequential format in which product files are placed in a container file having a .PCSI file type.
The default is /FORMAT=REFERENCE.

You cannot use the PRODUCT PACKAGE command to create a kit in compressed format. Instead, use the PRODUCT COPY command to convert a kit in sequential format to a kit in compressed format.

/LOG

/NOLOG (default)

Displays the file specifications of the files that are packaged in the product kit and the name of the product kit file.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.

/MATERIAL=(path-name[,...])

Specifies one or more locations in which the utility can search for product material files to include in the software product kit. Material files represent the output of the producer's software engineering process, that is, all files that make up the software product, including any command procedures that might be used during installation.

Note that the location of the PDF and PTF are not specified with the /MATERIAL qualifier. See the /SOURCE qualifier for more information.

This is a required qualifier for the PRODUCT PACKAGE command. Parentheses (()) are optional only when you specify a single path name. They are required when you specify multiple path names.

The format for path-name is: device-name:[directory-name]

You can specify path-name as a:

Specific directory Only one directory is searched.
Root directory A period (.) following the directory name indicates a root directory specification. For example, TEST$:[ABC.FT2.] limits the search path to subdirectories of [ABC.FT2].
Wildcard directory The directory name includes one or more of the wildcard characters asterisk (*), percent sign (%), or ellipsis (...). All directories that satisfy the wildcard specification are searched.

Note that when you use either a wildcard directory or a list of path names, if files in different directories have the same name, only the first file found in the search path is used.

When either a specific directory or a wildcard directory is used, the relative file specification on the file statement in the PDF file is not used to locate the file. However, when a root directory is used, the utility appends the relative file specification from the file statement in the PDF to the root directory in the material search path to locate files.

In general, use of a specific directory or a root directory is more efficient than using a wildcard directory. When packaging a product that contains hundreds of files, you might notice a significant difference in processing time, depending on the method you use to specify the path name. The choice of material path name does no affect the time required to install the kit.

/OWNER_UIC=uic

Specifies the owner user identification code (UIC) for files created during a copy operation. By default, the user executing the operation owns the software product files. For example, if you are logged in to your own account, you can use this qualifier during a copy operation to assign ownership of the product files to SYSTEM rather than to your own account. Specify the UIC in alphanumeric format (in the form [name]) or in octal group-member format (in the form [g,m]). UIC formats are described in the OpenVMS User's Manual.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/SOURCE=file-specification

Specifies the location of the input PDF file. If the device name is omitted, it defaults to the user's default device. If the directory name is omitted, it defaults to the user's default directory. If the file name and file type components of the file specification are not provided, they default to <full-product-name>.PCSI$DESCRIPTION.

The optional PTF file, if used, must be in the same directory and have the same file name as the PDF with a .PCSI$TEXT file type. If a file named <full-product-name>.PCSI$TEXT is not found, the package operation does not use a PTF file.

This is a required qualifier for the PRODUCT PACKAGE command. The logical name PCSI$SOURCE is not used.

/VERSION=version-number

Selects software products that have the specified version.

Example


$ PRODUCT PACKAGE VIEWER -
_$ /PRODUCER=ABC /FORMAT=SEQUENTIAL/ LOG -
_$ /SOURCE=[JAMES.TEST.PDF] -
_$ /DESTINATION=DKA200:[PCSI_KITS] -
_$ /MATERIAL=BUILD$:[VIEWER0201.RESULT...]

      

The directory [JAMES.TEST.PDF] contains the PDF named ABC-AXPVMS-VIEWER-0201--1.PCSI$DESCRIPTION. This file and the product material files from the BUILD$:[VIEWER0201.RESULT...] directory tree are used to create the kit for product VIEWER. When the PACKAGE operation completes, a sequential kit named ABC-AXPVMS-VIEWER-0201--1.PCSI is created and placed in the DKA200:[PCSI_KITS] directory.

RECONFIGURE

Modifies the configuration of an installed product by allowing a user to change installation options.

Reconfiguration of a product might result in the addition or deletion of files, or both, depending on the user's selection or deselection of options; that is, users can select options that were not selected when the product was installed, or they can deselect options that were selected when the product was installed. At the conclusion of the operation, the product database is updated to reflect the changes.

Access to the original software product kit that was used to install the product is required to perform the reconfigure operation.


Format

PRODUCT RECONFIGURE product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products, to reconfigure.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/CONFIGURATION=(keyword[,...])

Specifies how the configuration choices will be supplied. Keywords are:
CURRENT This is the default. It uses values from the product database, which has the current values recorded from the last time the product was installed or reconfigured.
PRODUCER Uses values specified by the software manufacturer for this version of the product.
INPUT=pcf-name Uses values from the specified product configuration file.
OUTPUT=pcf-name Writes configuration choices to the specified product configuration file. If no file name is supplied, creates a file named DEFAULT.PCSI$CONFIGURATION.
The keywords CURRENT, PRODUCER, and INPUT are mutually exclusive. Each of these, however, can be used with the keyword OUTPUT. If you specify only one keyword, you can omit the parentheses.

/HELP

/NOHELP (default)

Controls whether detailed explanations of product options and informational text are displayed. The first time you install a product, these explanations can help you decide which options to select. When you perform subsequent installations or upgrades, you might choose the brief explanations to save time.

When /NOHELP is selected, you can request a detailed explanation about a question by performing one of the following actions at the prompt:

  • Press the Help key or PF2 key
  • Type ? and press the Return key

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PLATFORM An integrated set of software products (also called a product suite).

/LOG

/NOLOG (default)

Displays the file specification of each file processed. When logging is enabled, messages notify you whenever product files, libraries, directories, temporary files, and product database files are created, deleted, or modified. Information about any file and module conflict resolution is also provided.

/OPTIONS=(keyword[,...])

/NOOPTIONS (default)

Specifies PRODUCT command options. Keywords are:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.
SHOW_DISK_USAGE Displays estimated disk block usage. Both peak utilization and net change are shown in addition to the amount of free space available before and after the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/RECOVERY_MODE

/NORECOVERY_MODE (default)

Allows you to perform product reconfiguration in recovery mode. When you use this qualifier, the directories, files, and modules that are modified, deleted, or removed in the reconfiguration process are saved in a directory tree on the system disk. These files, along with a copy of the product database, comprise the recovery data set.

The recovery data set is handled somewhat differently when a reconfiguration ends successfully or if it terminates, at some point, unsuccessfully.

  • If a reconfiguration terminates in its execution phase, either voluntarily (by using Ctrl/Y or Ctrl/C) or involuntarily (because of a fatal error), the saved recovery data is used to roll back all the displaced objects in an attempt to reinstate the product environment prior to the interrupted operation. Then the recovery data set is deleted.
  • At the end of a successful reconfiguration, the recovery data set is automatically deleted.

/REMARK=string

Records a comment in the product database about the task you are performing. The PRODUCT SHOW HISTORY command displays the recorded comments. For each product, the POLYCENTER Software Installation utility stores a chronological list of tasks you perform and the associated remarks. The default behavior is that no remark is recorded.

/REMOTE

/NOREMOTE (default)

Selects the product database located on a privately mounted system disk. By default, this utility searches the currently booted system disk for the product database.

This qualifier is primarily for use in command procedures that HP supplies. Incorrect use of this qualifier can create an inconsistency in the product database or cause subsequent PRODUCT commands to fail.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location defined by the logical name PCSI$SOURCE. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/TRACE

/NOTRACE (default)

Identifies DCL commands and command procedures that are run in a subprocess during the execution of the PRODUCT command. Any output from these commands is also displayed.

This qualifier is primarily a debugging aid for product developers to trace the execution of non-interactive command procedures embedded in their product kits. This qualifier is not useful for command procedures running in interactive mode. See the POLYCENTER Software Installation Utility Developer's Guide for more information.

/VERSION=version-number

Selects software products that have the specified version.

/WORK=device:[directory]

Specifies the name of the device and directory acting as a temporary work area. By default, temporary files are created in subdirectories of the user's login directory.

Example


$ DEFINE PCSI$SOURCE DKA500:[DWMOTIF.KIT]
$ PRODUCT RECONFIGURE DWMOTIF /VERSION=V1.2-3

      

The command in this example enters into a dialog with the user to change the configuration options for the product DECwindows Motif Version 1.2-3.

REGISTER PRODUCT

Records information in the product database about one or more installed products that are not yet registered in the database.

You can use this command to add information to the product database about products that have been installed by a mechanism other than the POLYCENTER Software Installation utility, such as VMSINSTAL. Either a special transition kit or a complete product kit must be in the source directory to supply details about the product being registered.

You cannot register patch or mandatory update kits. The PRODUCT REGISTER PRODUCT command only updates the product database; it does not copy any files to your system.

If you do not have a kit available to provide detailed information about a product, you can use the command procedure SYS$UPDATE:PCSI$REGISTER_PRODUCT.COM to register the name of the product and its version, producer, and base system in the product database. After you register a product using the command procedure, other products can reference it, and the PRODUCT SHOW PRODUCT command displays it as an installed product.


Format

PRODUCT REGISTER PRODUCT product-name[,...] [/qualifiers]


Parameter

product-name

Names the product, or list of products, to register.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/DESTINATION=device-name:[directory-name]

Specifies the location where the installed product resides. If you omit the device name, the utility uses your current default device. If you omit the directory name, the utility uses the [VMS$COMMON] directory as the default directory.

If you do not use this qualifier to specify a destination, the utility uses the location defined by logical name PCSI$DESTINATION. If this logical name is not defined, the utility uses the location SYS$SYSDEVICE:[VMS$COMMON], the top-level directory.

/KIT_ATTRIBUTES=keyword([,...])

Selects kits by kit type or kit format, or both. Keywords are:
FORMAT=
format-type
Designates the format of the product kit as follows:
   
COMPRESSED Compressed format in which a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.
REFERENCE Reference format in which product files exist in a directory tree. A .PCSI$DESCRIPTION file in the top level of the directory tree denotes a reference kit.
SEQUENTIAL Sequential format in which product files are placed in a container file. A file type of .PCSI indicates a sequential kit.
TYPE=
kit-type
Specifies the type of product kit as follows:
FULL Layered product (application) software.
OPERATING_SYSTEM Operating system software.
PARTIAL An upgrade to currently installed software. Installation of this kit changes the version of the product.
PLATFORM An integrated set of software products (also called a product suite).
TRANSITION Used to register information about a product that is installed but not recorded in the product database (for example, a product installed by VMSINSTAL). This kit does not provide product material.

/LOG

/NOLOG (default)

Displays the file specifications of the product database files that are created or modified.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/REMARK=string

Records a comment in the product database about the task you are performing. The PRODUCT SHOW HISTORY command displays the recorded comments. For each product, the POLYCENTER Software Installation utility stores a chronological list of tasks you perform and the associated remarks. The default behavior is that no remark is recorded.

/REMOTE

/NOREMOTE (default)

Selects the product database located on a privately mounted system disk. By default, this utility searches the currently booted system disk for the product database.

This qualifier is primarily for use in command procedures that HP supplies. Incorrect use of this qualifier can create an inconsistency in the product database or cause subsequent PRODUCT commands to fail.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/SOURCE=device-name:[directory-name]

Specifies the disk and directory where the utility searches for the software product kit or kits. If /SOURCE is not specified, the utility searches in the location defined by the logical name PCSI$SOURCE. If PCSI$SOURCE is not defined, and the /SOURCE qualifier is not specified, the POLYCENTER Software Installation utility searches the current default directory.

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=version-number

Selects software products that have the specified version.

Example


$ PRODUCT REGISTER PRODUCT TOOLCHEST /SOURCE=DKB500:[TOOLCHEST.KIT]
      

The command in this example registers the product TOOLCHEST in the product database. TOOLCHEST was installed by VMSINSTAL, and a special transition kit is in the source directory to supply details about the product.

REGISTER VOLUME

For a volume containing installed products, records a change in volume label in the product database.

For device independence, the product database identifies the destination device of an installed product by its logical volume name, not by its physical device name. The logical volume name (usually in the form DISK$labelname) is defined by the MOUNT command and associated with the device.

You can check the logical volume name of a mounted device by issuing a command in the following format:


 $ WRITE SYS$OUTPUT F$GETDVI("device","LOGVOLNAM")

When you use the SET VOLUME command to change the volume label of a nonsystem device that contains installed products, you must also use the PRODUCT REGISTER VOLUME command to update the product database with this information. Register the new volume label after you dismount and remount the volume so that the new logical volume name (DISK$labelname) is defined.

If you change the volume label of the system device, you do not need to use the PRODUCT REGISTER VOLUME command because the POLYCENTER Software Installation utility automatically detects the change after the volume is remounted following a system reboot.


Format

PRODUCT REGISTER VOLUME old-volume-label device-name [/qualifiers]


Parameters

old-volume-label

Names the old (existing) volume label.

device-name

Names the device for which the volume label is to be changed in the product database.

Qualifiers

/LOG

/NOLOG (default)

Displays the file specifications of the product database files that are created or modified.

/REMOTE

/NOREMOTE (default)

Selects the product database located on a privately mounted system disk. By default, this utility searches the currently booted system disk for the product database.

This qualifier is primarily for use in command procedures that HP supplies. Incorrect use of this qualifier can create an inconsistency in the product database or cause subsequent PRODUCT commands to fail.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

Example


$ PRODUCT REGISTER VOLUME AXPVMSV62 DKA0:

      

The command in this example replaces all occurrences of the old volume label in the POLYCENTER Software Installation utility database with the current volume label of the specified disk.

REMOVE

Uninstalls one or more software products from your system and updates the product database. This command operates on complete products. Any patches or mandatory updates that might have been applied to complete products are also removed.

To uninstall patches or mandatory updates while still retaining the original product that was installed, use the PRODUCT UNDO PATCH command.


Format

PRODUCT REMOVE product-name[,...] [/qualifiers]


Parameter

product-name

Names the installed product or list of installed products to remove. Specify only the names of complete products, not the names of patches or mandatory updates applied to products.

Qualifiers

/BASE_SYSTEM=base-system-name

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

/LOG

/NOLOG (default)

Displays the file specification of each file processed. When logging is enabled, messages notify you whenever product files, libraries, directories, temporary files, and product database files are created, deleted, or modified.

/OPTIONS=(keyword[,...])

/NOOPTIONS (default)

Specifies PRODUCT command options. Keywords are:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the products that have been selected for the operation.
SHOW_DISK_USAGE Displays estimated disk block usage. Both peak utilization and net change are shown in addition to the amount of free space available before and after the operation.

/PRODUCER=producer-name

Selects software products that the specified manufacturer produces.

/REMARK=string

Records a comment in the product database about the task you are performing. The PRODUCT SHOW HISTORY command displays the recorded comments. For each product, the POLYCENTER Software Installation utility stores a chronological list of tasks you perform and the associated remarks. The default behavior is that no remark is recorded.

/REMOTE

/NOREMOTE (default)

Selects the product database located on a privately mounted system disk. By default, this utility searches the currently booted system disk for the product database.

This qualifier is primarily for use in command procedures that HP supplies. Incorrect use of this qualifier can create an inconsistency in the product database or cause subsequent PRODUCT commands to fail.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/TRACE

/NOTRACE (default)

Identifies DCL commands and command procedures that are run in a subprocess during the execution of the PRODUCT command. Any output from these commands is also displayed.

This qualifier is primarily a debugging aid for product developers to trace the execution of non-interactive command procedures embedded in their product kits. This qualifier is not useful for command procedures running in interactive mode. See the POLYCENTER Software Installation Utility Developer's Guide for more information.

/VERSION=version-number

Selects software products that have the specified version.

/WORK=device:[directory]

Specifies the name of the device and directory acting as a temporary work area. By default, temporary files are created in subdirectories of the the user's login directory.

Example


$ PRODUCT REMOVE FTAM
      

The command in this example uninstalls the product named FTAM and updates the product database to remove all information about the product.

SHOW HISTORY

Displays a chronological log of operations performed on the specified products.

Format

PRODUCT SHOW HISTORY product-name[,...] [/qualifiers]


Parameter

product-name

Names the product or list of products to include in the display. This is an optional parameter. If you omit it, operations performed on all products will be shown.

Qualifiers

/BASE_SYSTEM=(base-system-name[,...])

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

Parentheses (()) are optional only when you specify a single base system name. They are required when you specify multiple base system names.

/BEFORE=time

Selects entries that were created before the specified date and time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords:
TODAY (default)
TOMORROW
YESTERDAY

Refer to the OpenVMS User's Manual for information about specifying time values.

/FULL

/NOFULL (default)

Displays information in 132-column format. The /NOFULL qualifier displays a subset of available information in 80-column format.

/OPERATION=(keyword[,...])

Specifies one or more of the following operations as the value for keyword:
INSTALL
RECONFIGURE
REGISTER_PRODUCT
REGISTER_VOLUME
REMOVE

Parentheses (()) are optional only when you specify a single keyword. They are required when you specify multiple keywords.

/PRODUCER=(producer-name[,...])

Selects software products that the specified manufacturer produces.

Parentheses (()) are optional only when you specify a single producer name. They are required when you specify multiple producer names.

/REMOTE

/NOREMOTE (default)

Selects the product database located on a privately mounted system disk. By default, this utility searches the currently booted system disk for the product database.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/SINCE=time

Selects entries that were created on or after the specified date and time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords:
TODAY (default)
YESTERDAY

Refer to the OpenVMS User's Manual for information about specifying time values.

/USER=(username[,...])

Displays information about the products installed, configured, or removed by the specified user.

Parentheses (()) are optional only when you specify a single user name. They are required when you specify multiple user names.

/VERSION=(version-number[,...])

Selects software products that have the specified version.

Parentheses (()) are optional only when you specify one version number. They are required when you specify more than one version number.


Example


$ PRODUCT SHOW HISTORY * /OPERATION=INSTALL /BEFORE=22-MAY-2002

      

The command in this example lists all the products that were installed before May 22, 2002.

SHOW OBJECT

Displays information about objects created during a software product installation. Examples of software objects are files, directories, and modules in libraries. The standard display lists the name, type, generation number, and status of each object. The expanded display, which you request by using the /FULL qualifier, includes the destination root directory and the product that owns the object.

Each file and library module object has an associated generation number, either explicit or implied. A generation number is an integer value in which the largest value in a comparison of generation numbers denotes the object that supersedes the others.

The product developer specifies generation numbers to aid the POLYCENTER Software Installation utility in resolving conflict on installation when two or more products or patch kits supply the same object. An explicit or implicit value of zero means no generation information has been supplied. A tie of non-zero generation numbers means the objects are identical and that an object from a product kit should replace a previously installed object. If all generation numbers in a comparison are zero, the conflict cannot be resolved.

Each object has an installation status. A status of "OK" means that the object is currently installed. A status of "Conflict" indicates that the object lost a generation comparison with an object of the same name supplied by another product or patch. This is not an error condition. "OK/Adopt" indicates that a product inherited the object from another product. This happens only when a product loses an object conflict to another product, and, subsequently, the other product is removed, causing the file or module on the system to be adopted by the surviving product.


Format

PRODUCT SHOW OBJECT object-name [/qualifiers]


Parameter

object-name

Names the object or list of objects to include in the display. This is an optional parameter. If you omit it, all objects for the selected products will be shown. You can use the asterisk (*) and the percent sign (%) wildcard characters to specify the object-name.

The name of a file object includes its directory specification relative to the destination root directory for the installed product. For example, a file placed in DISK$ALPHA:[VMS$COMMON.SYSEXE]TEST.EXE is identified in the product database as the file object [SYSEXE]TEST.EXE.


Qualifiers

/BASE_SYSTEM=(base-system-name[,...])

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

Parentheses (()) are optional only when you specify a single base system name. They are required when you specify multiple base system names.

/FULL

/NOFULL (default)

Displays information in 132-column format. The /NOFULL qualifier displays a subset of available information in 80-column format.

/PRODUCER=(producer-name[,...])

Selects software products that the specified manufacturer produces.

Note that the PRODUCT SHOW HISTORY command allows you to specify both the /PRODUCER and /PRODUCT qualifiers, which you need to spell out because they are not unique within the first four characters.

Parentheses (()) are optional only when you specify a single producer name. They are required when you specify multiple producer names.

/PRODUCT=(product-name[,...])

Selects products with the specified product name.

Note that the PRODUCT SHOW HISTORY command allows you to specify both the /PRODUCER and /PRODUCT qualifiers, which you need to spell out because they are not unique within the first four characters.

Parentheses (()) are optional only when you specify a single product name. They are required when you specify multiple product names.

/REMOTE

/NOREMOTE (default)

Selects the product database located on a privately mounted system disk. By default, this utility searches the currently booted system disk for the product database.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/VERSION=(version-number[,...])

Selects software products that have the specified version.

Parentheses (()) are optional only when you specify one version number. They are required when you specify more than one version number.


Example


$ PRODUCT SHOW OBJECT * /PRODUCT=ABC /FULL

      

The command in this example lists all objects such as files, directories, library modules, and other objects that were created when the product ABC was installed.

SHOW PRODUCT

Displays a list of software products installed on your system. Use the /FULL qualifier to display additional information such as kit type, maintenance activity, and software dependencies.

Format

PRODUCT SHOW PRODUCT product-name[,...] [/qualifiers]


Parameter

product-name

Names the product or list of products to include in the display. This is an optional parameter. If you omit it, the names of all installed products will be shown.

Qualifiers

/BASE_SYSTEM=(base-system-name[,...])

Selects software products whose base system matches the one specified. The base system name identifies both a hardware platform and an operating system. Standard names are:
Name Description
AXPVMS Denotes an OpenVMS Alpha product
I64VMS Denotes an OpenVMS Industry Standard 64 product
VAXVMS Denotes an OpenVMS VAX product
VMS Indicates a product that can be installed on more than one OpenVMS platform

Parentheses (()) are optional only when you specify a single base system name. They are required when you specify multiple base system names.

/FULL

/NOFULL (default)

Displays information in 132-column format. The /NOFULL qualifier displays a subset of available information in 80-column format.

/MAINTENANCE=(product-name[,...])

Displays the products to which the named maintenance products have been applied. A maintenance product is either a patch kit or a mandatory update kit.

Parentheses (()) are optional only when you specify a single product name. They are required when you specify multiple product names.

To list all maintenance products that have been applied to a particular product, use the following command:


PRODUCT SHOW PRODUCT product-name /FULL

/PRODUCER=(producer-name[,...])

Selects software products that the specified manufacturer produces.

Parentheses (()) are optional only when you specify a single producer name. They are required when you specify multiple producer names.

/REFERENCED_BY=(product-name[,...])

Displays products that are referenced by the named product. Use this qualifier to show if the product, specified in the /REFERENCED_BY qualifier, has a software dependency on the product or products specified in the product-name parameter of the SHOW PRODUCT command. If you specify an asterisk (*) as the product name, all referenced products are listed for the product named in the /REFERENCED_BY qualifier.

Parentheses (()) are optional only when you specify a single product name. They are required when you specify multiple product names.

To list all products that require a specified product to be installed, use the command:


PRODUCT SHOW PRODUCT product-name /FULL /REFERENCED_BY=*

To list all products that are referenced by (that is, required by) a particular product, use the command:


PRODUCT SHOW PRODUCT * /REFERENCED_BY=product-name

To list all products that are referenced by (that is, required by) other products, use the command:


PRODUCT SHOW PRODUCT * /REFERENCED_BY=*

/REMOTE

/NOREMOTE (default)

Selects the product database located on a privately mounted system disk. By default, this utility searches the currently booted system disk for the product database.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/SPAN_VERSIONS=keyword([,...])

Selects software products whose versions match the specified version criteria. The keywords are:
ABOVE=version Selects versions greater than the version specified
BELOW=version Selects versions less than the version specified
MINIMUM=version Selects versions greater than or equal to the version specified
MAXIMUM=version Selects versions less than or equal to the version specified

The ABOVE, BELOW, MINIMUM, and MAXIMUM keywords can be used alone or in combination. For example, /SPAN_VERSIONS= (MINIMUM=V2.1,BELOW=V3.0) selects versions greater than or equal to V2.1 and less than (but not including) V3.0. Using the MAXIMUM keyword instead of BELOW would select versions that include V3.0.

/VERSION=(version-number[,...])

Selects software products that have the specified version.

Parentheses (()) are optional only when you specify one version number. They are required when you specify more than one version number.


Example


$ PRODUCT SHOW PRODUCT * /REFERENCED_BY=DECNET_OSI

      

The command in this example lists all products on which the DECnet-Plus product is dependent.

SHOW RECOVERY_DATA

Displays patch recovery data sets in chronological order, starting with the set created most recently and ending with the oldest one. Each recovery data set identifies one or more patches that can be uninstalled.

Format

PRODUCT SHOW RECOVERY_DATA [/qualifiers]


Parameters

None.

Qualifiers

/BEFORE=time

Selects recovery data sets created before the specified date and time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords:


    TODAY (default)
    TOMORROW
    YESTERDAY

Refer to the OpenVMS User's Manual for information about specifying time values.

/FULL

/NOFULL (default)

Displays information in 132-column format. The /NOFULL qualifier displays a subset of available information in 80-column format.

/LOG

/NOLOG (default)

Displays the file specifications of recovery data set files as they are accessed.

/NEWEST=count

Displays the most recently created patch recovery data sets. For example, if you specify /NEWEST=2, the SHOW RECOVERY_DATA command displays the two newest recovery data sets. If you do not specify a number with this qualifier, the default value is 1.

/OLDEST=count

Displays the oldest recovery data sets. For example, if you specify /OLDEST=2, the SHOW RECOVERY_DATA command displays the two oldest recovery data sets. If you do not specify a number with this qualifier, the default value is 1.

/REMOTE

/NOREMOTE (default)

Selects recovery data sets located on a privately mounted system disk. By default, this utility searches the currently booted system disk for recovery data sets.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/SINCE=time

Selects recovery data sets that were created on or after the specified date and time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords:
TODAY (default)
YESTERDAY

Refer to the OpenVMS User's Manual for information about specifying time values.


Example


$ PRODUCT SHOW RECOVERY_DATA /SINCE=10-DEC-2002

      

The command in this example displays the recovery data sets created on or after December 10, 2002, starting with the one created most recently.

SHOW UTILITY

Displays the version of the POLYCENTER Software Installation utility that you are using.

Format

PRODUCT SHOW UTILITY


Parameters

None.

Qualifiers

None.

Example


$ PRODUCT SHOW UTILITY
POLYCENTER Software Installation utility version: V7.3-100
   .
   .
   .

      

The command in this example shows the version of the utility that is executing the command.

UNDO PATCH

Uninstalls one or more patch or mandatory update kits from your system. The associated recovery data sets are deleted at the conclusion of the operation.

Note that you can perform this operation only if the patch or mandatory update kits were installed with the /SAVE_RECOVERY_DATA qualifier and if the saved recovery data is still available. You can verify that recovery data still exist by entering the PRODUCT SHOW RECOVERY_DATA command.

A recovery data set is created when you use the PRODUCT INSTALL /SAVE_RECOVERY_DATA command to install one or more patches (also known as ECOs or remedial kits). The PRODUCT UNDO PATCH command uninstalls all patches associated with the selected recovery data sets. Furthermore, you can "undo" patches only in the reverse chronological order of the creation dates of their recovery data sets.

To uninstall complete products, including any patches or mandatory updates that have been applied to them, use the PRODUCT REMOVE command.


Format

PRODUCT UNDO PATCH [/qualifiers]


Parameters

None.

Qualifiers

/ALL

Uninstalls all patch and mandatory updates for which recovery data has been saved. Once the operation completes, all the recovery data sets are deleted and cannot be reused. If you do not specify the /ALL, /NEWEST, or /SINCE qualifier, only the most recently created recovery data set is used to select patches and mandatory updates to uninstall.

/LOG

/NOLOG (default)

Displays the file specifications of files as they are accessed; also provides other information related to file activity. For example, when logging is enabled, messages notify you when product files, libraries, directories, temporary files, and product database files are created, deleted, or modified.

/NEWEST=count

Selects the most recently created patch recovery data sets. For example, if you specify /NEWEST=3, the PRODUCT UNDO PATCH command uninstalls patches using data from the three newest recovery data sets. If you do not specify a number with this qualifier, the default value is 1.

/OPTIONS=keyword

/NOOPTIONS (default)

Specifies PRODUCT command options. The keyword is:
NOCONFIRM Omits the confirmation dialog that asks the user to verify the recovery data sets that have been selected for processing.

/REMOTE

/NOREMOTE (default)

Selects recovery data sets located on a privately mounted system disk. By default, this utility searches the currently booted system disk for recovery data sets. Also, the saved product database is restored to the privately mounted system disk.

When you use /REMOTE, the following logical names must be defined:

  • PCSI$SYSDEVICE must specify the physical disk name of the target system disk. This disk must be mounted and allocated to the process executing the PRODUCT command.
  • PCSI$SPECIFIC must point to a system root on PCSI$SYSDEVICE. It must be defined in the following form, where x is a valid system root:


    PCSI$SYSDEVICE:[SYSx.]
    

/SINCE=time

Selects recovery data sets that were created on or after the specified date and time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords:
TODAY (default)
YESTERDAY

Refer to the OpenVMS User's Manual for information about specifying time values.

/TRACE

/NOTRACE (default)

Identifies DCL commands and command procedures that are run in a subprocess during the execution of the PRODUCT command. Any output from these commands is also displayed.

This qualifier is primarily a debugging aid for product developers to trace the execution of non-interactive command procedures embedded in their product kits. This qualifier is not useful for command procedures running in interactive mode. See the POLYCENTER Software Installation Utility Developer's Guide for more information.


Example


$ PRODUCT UNDO PATCH

      

The command in this example uninstalls all patch and mandatory update kits that were installed in the last INSTALL operation performed with the /SAVE_RECOVERY_DATA qualifier. The recovery data set used in this operation is deleted at the end of the operation and cannot be reused.


Chapter 19
SCA Control Program Utility

19.1 SCACP Description

The SCA Control Program (SCACP) utility is designed to monitor and manage cluster communications. It is derived from the Systems Communications Architecture (SCA), which defines the communications mechanisms that allow nodes in an OpenVMS Cluster system to cooperate.

SCA does the following:

  • Governs the sharing of data between resources at the nodes
  • Binds together System Applications (SYSAPs) that run on different Alpha and VAX computers

Historically, LAN cluster port information has been available only in the System Dump Analyzer (SDA) utility and by using the Availability Manager management tool. The ability to start and stop PEDRIVER on a LAN device was provided by SYS$EXAMPLES:SYS$LAVC_START_BUS.EXE and SYS$LAVC_STOP_BUS.EXE. No way existed to prioritize use of LAN devices or individual channels.

SCACP provides an alternative method of collecting cluster management data and exercising management control over cluster communications. OpenVMS Version 7.3 introduced SCACP's ability to manage SCA use of LAN paths. Beginning with OpenVMS Version 7.3-1, you can use SCACP to manage all OpenVMS Cluster interconnects.

19.1.1 Terminology Related to SCACP

Definitions of terms that are related to SCACP are in the following sections.

19.1.1.1 SCS Ports and Circuits

SCA communications mechanisms between nodes are defined in terms of System Communications Services (SCS) ports and circuits:

  • An SCS port is any device that provides SCA communications services.
  • An SCS circuit is an SCS port layer connection that provides a standardized set of services using a reliable port-to-port communication connection between OpenVMS Cluster nodes.

After a circuit is formed between two ports, communication using the SCS services can be established between SYSAPs in the nodes. In a cluster, each port maintains a circuit with every other remote port.

Circuits provide the SCS layer with the following standardized SCS services:

  • Datagram delivery
  • Message delivery
  • Block data read and write operations

Note

Some differences exist in the use of the terms paths and circuits:
  • The SCA architecture specification and OpenVMS code use the term paths to refer to circuits.
  • The SHOW CLUSTER utility and other OpenVMS utilities use the term circuits to refer to what SCA calls paths.
  • SCACP follows the SHOW CLUSTER precedent and uses the term circuits as well.

19.1.1.2 Virtual Circuits

A virtual circuit (VC) is the interconnect-specific transport layer connection within a circuit that provides reliable port-to-port communication. In other words, VCs are the details of a circuit concerned with interconnect-specific reliable data delivery.

Circuits ensure the following:

  • The delivery of messages without duplication or loss
  • The sequential ordering of messages

The concepts of circuits and virtual circuits are so closely related that usually it has been unnecessary to differentiate between them because SHOW CLUSTER provides no visability into the internal operation of a circuit. SCACP, however, makes the differentiation necessary by providing this internal visability. Beginning with OpenVMS Version 7.3, SCACP can be used to manage and display information about the VCs underlying the circuits between LAN ports. Because SCACP displays different types of information about circuits and VCs, its commands must differentiate between them.

LAN cluster communications create virtual circuits using the NI-SCA Transport Protocol to communicate over LAN hardware, providing datagram services.

19.1.1.3 LAN Channels

A channel is a logical communication path between two LAN devices. Each channel between two nodes is determined by a local-remote pair of devices and the connecting network. For example, two nodes, each having two LAN devices, can establish up to four channels. The messages that a particular virtual circuit carries can be sent over any of the channels connecting the two nodes.

The LAN cluster driver, PEDRIVER, builds reliable virtual circuits using channels that the LAN adapters (devices) and the network connections define. It then uses these VCs to provide circuits to SCS.

19.1.1.4 Channels and Virtual Circuits

The differences between channels and virtual circuits are the following:

  • Channels are LAN paths providing datagram service.
  • NI-SCA port-to-port virtual circuits are layered on channels and provide error-free paths between nodes.

Multiple channels can exist between nodes in an OpenVMS Cluster system, but only one LAN-based virtual circuit can exist between any two nodes at a time.

19.1.2 New Cluster SCA Circuit and Port Functionality

The following sections explain new functionality available for SCA circuits and ports and new support for SCS dynamic load class. In addition, you can independently enable or disable checksumming on individual PEdriver virtual circuits (VCs).

19.1.2.1 Ability to Set Port and Circuit Priorities

Beginning with OpenVMS Version 7.3-1, you can exercise management control over the circuits chosen to be used for SCS connections. This control allows you to override the automatic selection of the circuit with the highest load class value.

To override automatic circuit selection, assign a management priority value to a specific circuit or SCA port. (A circuit's current priority value is the sum of the local port's management-assigned priority and the management priority value assigned to that circuit.)

Connections are assigned to a circuit with the highest priority. If multiple circuits have the highest priority value, then the circuit with the highest load class is selected.

A change in a circuit's current priority has one of the following effects:

  • If a circuit's new current priority value is higher than another circuit's current priority, the connection is moved to the circuit with the higher current priority.
  • Similarly, if a circuit's new current priority value is lower than another circuit's current priority, the connection moves to the circuit with the highest current priority.

CIRCUIT MANAGEMENT PRIORITY IS VOLATILE

Whenever a circuit is closed, its management priority setting is lost. This is because the data structure containing information about a circuit is deallocated each time a circuit is closed. When a circuit is reopened, the structure is initialized with default values. Thus, circuit management priority does not propagate across VC closures.

19.1.2.2 Ability to Enable/Disable PEdriver Checksumming

You can use SCACP to enable or disable checksumming on a per-VC basis. For example, in a disaster tolerent cluster, you might want to enable only checksumming on VCs to nodes at the remote site to ensure that failure of a LAN device's checksumming function resulting in corrupted packets would not propagate to the remote site.

19.1.2.3 SCS Dynamic Load Class Support

Prior to OpenVMS Version 7.3-1, the load class of SCS circuits was determined only by the port's hard-coded load class value. As a result, CI or DSSI circuits were chosen over a GigaBit Ethernet circuit. Beginning with OpenVMS Version 7.3-1, PEdriver dynamically updates the load class value of its SCS circuits to reflect the performance of the underlying LAN path or paths currently in use.

If the circuits have the same priority, a change in a circuit's load class has one of the following effects:

  • If a circuit's new load class value is higher than another circuit's current load class, the connection is moved to the higher load class circuit.
  • Similarly, if a circuit's new load class value is lower than another circuit's load class, the connection moves to the circuit with the highest load class.

19.1.3 Managing Cluster Ports and Circuits

Beginning with V7.3-1, SCACP provides the ability to display information about one cluster interconnect's local ports and their circuits with remote ports.

SCACP port and circuit data is intended to provide the information necessary to exercise management control over ports and circuits. SCACP is not intended to replace the wealth of data that SHOW CLUSTER provides about ports and circuits. The SHOW CLUSTER and SCACP utilities are intended to be used together to manage cluster communications.

SCACP port and circuit data show the following:

  • SCACP port data shows an overview of a particular port's characteristics.
  • SCACP circuit data shows the characteristics and the status of SCS communications with other nodes in the cluster.

You can also manage cluster communications by assigning a priority value to individual ports or circuits. See the SET CIRCUIT and SET PORT command descriptions.

19.1.4 Managing LAN Cluster Ports

To manage LAN cluster ports, you can use common port and circuit commands. Additional commands exist for LAN port VCs, channels, and LAN devices on nodes in the cluster:

  • VC data shows detailed internal information about the characteristcs and operation of the NI-SCA transport layer connection underlying the circuit between the local and remote PEDRIVER ports.
  • Channel data shows the characteristics of each LAN communications path and shows how suitable each channel is for use by the virtual circuit.
  • LAN device data shows low-level local LAN device characteristics, counters, and errors.

SCACP allows you to set channel and LAN device priority. SCACP also allows you to start and stop PEDRIVER on LAN devices.

Using the PEDRIVER Event-Tracing Facility

The LAN cluster port driver, PEDRIVER, includes an event-tracing facility that collects a small amount of information for each defined event and saves it in a buffer associated with the virtual circuit or channel. (Any event not associated with a particular virtual circuit or channel is saved in a global PEDRIVER trace buffer.)

The event trace data is used when debugging, performing dump analysis, and looking at detailed aspects of PEDRIVER operation.

Note

The TRACE commands are reserved for use by OpenVMS Engineering and HP Services under OpenVMS Engineering direction only. Trace commands and output are subject to change from release to release.

19.1.5 Troubleshooting Cluster Communications

You can use SCACP to diagnose cluster communications problems. The appendix "Troubleshooting the NISCA Protocol" in OpenVMS Cluster Systems provides troubleshooting strategies to help cluster or network managers use SCACP and other tools to pinpoint network-related cluster communications problems.

19.1.6 Related Documents

For additional information on the topics covered in this chapter, refer to the following documents:

  • OpenVMS Cluster Systems
  • Guidelines for OpenVMS Cluster Configurations

19.2 SCACP Commands

SCACP commands are provided for the following types of functions:

  • Display
  • Port selection
  • Circuit selection
  • Channel operation and selection
  • LAN device operation and selection
  • Trace
  • Miscellaneous: Help, Spawn, Execute, and Exit

The SCACP commands are shown in Table 19-1.

`

Table 19-1 SCACP Commands
Command Function
SCACP Display Commands Qualifiers
SHOW CHANNEL Displays PEDRIVER channel information.
SHOW CIRCUIT (nodename) Shows information about all circuits between this node and other cluster nodes, including LAN circuit information.
SHOW LAN_DEVICE Displays PEDRIVER LAN device information.
SHOW PORT Displays information about all SCA ports on the node, including the LAN port, PEA0.
SHOW VC Displays PEDRIVER virtual circuit information.
SCACP Operation Commands
SET CHANNEL Allows a user to set PEDRIVER channel management options.
SET CIRCUIT Allows a user to set a management priority value for the selected circuit or circuits.
SET PORT Allows a user to set a management priority value for the selected port or ports.
SET VC Allows a user to set PEDRIVER virtual channel options.
SCACP LAN Device Operation Commands
SET LAN_DEVICE Sets PEDRIVER LAN device management options.
START LAN_DEVICE Starts PEDRIVER on the specified LAN devices.
STOP LAN_DEVICE Stops PEDRIVER on the specified LAN devices.
SCACP Trace Commands
These commands are reserved for HP use only.
SET TRACE Sets PEDRIVER event tracing options.
SHOW TRACE Displays PEDRIVER event tracing information.
START TRACE Displays PEDRIVER event tracing.
STOP TRACE Stops PEDRIVER event tracing.
SCACP Miscellaneous Commands
HELP Displays help data.
SPAWN [command] Spawns and executes a DCL command.
@filename Executes command file.
EXIT Exits SCACP.

19.3 SCACP Usage Summary

The SCA Control Program (SCACP) is a cluster management utility that performs certain privileged cluster communications management functions.


Format

RUN SYS$SYSTEM:SCACP


Parameters

None.

Description

To invoke SCACP, enter the following command at the DCL prompt:


$ RUN SYS$SYSTEM:SCACP

SCACP displays the following prompt, at which you can enter SCACP commands using the standard rules of DCL syntax:


SCACP>

To exit SCACP and return to the DCL command level, enter the EXIT command at the SCACP> prompt or press Ctrl/Z.

Note

OpenVMS Version 7.3 and later require SYSPRV privilege to issue SCACP commands.

SCACP also requires you to have the following privileges:

  • A minimum of DISPLAY privilege is required to issue commands that display information or influence SCACP execution (that is, SHOW, HELP, SPAWN, EXIT, and so on.)
  • SYSPRV privilege is reqired to issue commands that change cluster communications operations (that is, SET, START,and STOP).

Example


$ CREATE COUNT.COM
SHOW LAN_DEVICE/COUNTERS
SPAWN WAIT 00:01:00
@COUNT

[Ctrl/Z]
$ RUN SYS$SYSTEM:SCACP
SCACP> @COUNT
      

This example creates and runs a command procedure, COUNT.COM, which displays device counters once a minute.

EXIT

Stops execution of SCACP and returns control to the DCL command level. You can also enter Ctrl/Z at any time to exit.

Format

EXIT


Parameters

None.

Qualifiers

None.

Example


SCACP> EXIT
$
      

This command stops execution of SCACP and returns control to the DCL command level.

HELP

Provides online help information about the SCACP utility.

Format

HELP [topic]


Parameter

topic

Specifies a subject for which you want information: SCACP command or command plus command keyword. If you enter the HELP command with a command name only, such as HELP SET, SCACP displays a list of all of the command keywords used with the SET command.

Qualifiers

None.

Example


SCACP> HELP SET TRACE
      

The HELP command in this example displays information about the SET TRACE command:


SET

   TRACE

        Sets or modifies PEDRIVER tracing parameters.

        Format

          SET TRACE

     Additional information available:

     Parameters Qualifiers
     /AFTER   /DEFAULT   /EVENT   /EXCLUDE   /LOCAL_DEVICE
     /REMOTE_DEVICE      /STOP   /SIZE

     Examples

 SET TRACE Subtopic?

SET CHANNEL

Sets CHANNEL management parameters, including priority values.

Note

If a LAN device is disabled for use by cluster communications, all channels associated with that device are deleted. This means that all management settings for the device and the channels will be deleted.

Format

SET CHANNEL nodename


Parameter

nodename[,...]

Includes channels to specific nodes, which you can use wildcards to specify. Each node name can be accompanied by optional qualifiers to specify local and remote device names. If no local or remote device name is specified, all channels to the specified node name are included.

Qualifiers

/EXCLUDE=(nodename[,...])

Excludes channels to specific nodes, which you can use wildcards to specify. Each node name can be accompanied by optional qualifiers to specify local and remote device names. If no local or remote device name is specified, all channels associated with the specified node are included.

/LOCAL_DEVICE=(landevicename[,...])

Specifies a LAN device that identifies the local end of the channel; you can use wildcards to specify LAN devices.

/PRIORITY=n

Sets the management priority value for channels to selected nodes. n can be a value between -127 and +127.

/REMOTE_DEVICE=(landevicename[,...])

Specifies a LAN device that identifies the remote end of the channel; you can use wildcards to specify LAN devices.

Usage Notes

  • Use the SHOW CHANNEL command to display node names and local and remote device names.
  • Use the SHOW LAN_DEVICE command to display device names.
  • Use the SHOW LAN_DEVICE command on the remote node to display remote device names.

Examples

#1

SCACP> SET CHANNEL/PRIORITY=3 NODE5
      

The command in this example sets the priorities of all channels to node NODE5 to 3.

#2

SCACP> SET CHANNEL/LOCAL=EWA/REMOTE=EWB -
_SCACP> NODE10,NODE15/L=F*/R=F*,NODE20/PRIORITY=10
      

The command in this example is equivalent to the following command:


SET CHANNEL NODE10/L=EWA/R=EWB,NODE15/L=F*/R=F*,NODE20/L=*/R:*/PRIORITY=10

This command sets the priority of the following channels to 10:

  • To node NODE10, the channel with local device EWA and remote device EWB
  • To node NODE15, the channels with local LAN devices starting with F and remote LAN devices starting with F
  • All channels to node NODE20

SET CIRCUIT

Sets the circuit management priority value.

Note

If a circuit is closed, it is deleted. This means that the management settings for that circuit are also deleted.

If the circuit is opened again, it has the default values for its management settings.


Format

SET CIRCUIT nodename


Parameter

nodename[,...]

Names a circuit or circuits to specific nodes, which you can use wildcards to specify. You can qualify each node name with additional parameters to uniquely identify a single circuit.

Qualifiers

/EXCLUDE=(nodename[/PORT=portname[/RSTATION=n]][,...])

Allows you to exclude a specific circuit to a node. If multiple circuits to the same node exist, you can use the /PORT and /RSTATION qualifiers to uniquely identify the circuit.

/PORT=portname[/RSTATION=n]

If multiple circuits to the same node exist, you can use the /PORT and /RSTATION qualifiers to uniquely identify the circuit. You can use the /RSTATION qualifier only in conjunction with the /PORT qualifier.

/PRIORITY=n

Sets the management priority value for the selected circuits. n can be a value between -127 and +127.

Example


SCACP> SET CIRCUIT CLUIO1 /PORT=PIB0 /PRI=10
      

The command in this example sets the priority of the circuit to node CLUIO1 through PIB0 to 10. You need to use the /PORT qualifier if multiple circuits to node CLUI01 exist and only the circuit through PIB0 is meant to have its priority raised.

SET LAN_DEVICE

Sets device management priority parameter

Format

SET LAN_DEVICE landevicename


Parameter

landevicename[...,]

Includes specific LAN devices, which you can use wildcards to specify.

Usage Note

  • Use the /EXCLUDE qualifier to exclude LAN devices.
  • Use the SHOW LAN_DEVICE command to display device names.

Qualifiers

/EXCLUDE=(landevicename1[,...])

Excludes one or more specific LAN devices, which you can use wildcards to specify.

/PRIORITY=n

Sets the management priority value for the selected devices. n can be any value between -127 and +127.

Usage Note

Use the SHOW LAN_DEVICE command to display device names.


Example


SCACP> SET LAN_DEVICE/PRIORITY=3 EWA
      

The command in this example sets the management priority for device EWA to 3.

SET PORT

Sets a port management priority value.

Format

SET PORT portname


Parameter

portname[,...]

Specifies SCA port names, in which you can include wildcards.

Qualifiers

/EXCLUDE=(portname[,...])

Excludes specific ports from the operation.

/PRIORITY=n

Sets the management priority value for the selected ports. n can be any value between -127 and +127.

Usage Notes

  • To display all ports available on your system, use the SHOW PORT command.
  • Use the /EXCLUDE qualifier to exclude specific ports.

Examples

#1

SCACP> SET PORT PEA0/PRIORITY=5
      

The command in this example sets the management priority for the PEA0 port to 5.

#2

SCACP> SET PORT PEA0 /PRIORITY=5 /EXCLUDE=PEA0
      

The command in this example sets all ports with the exception of PEA0 to a management priority of 5.

SET TRACE

SET TRACE sets or modifies PEDRIVER tracing parameters.

Note

This command is reserved for use by HP Services and OpenVMS Engineering only. Trace commands and output are subject to change from release to release.

Format

SET TRACE nodename


Parameter

nodename[,...]

Includes channels and VCs to specific nodes, which you can use wildcards to specify. Each node name can be accompanied by optional qualifiers to specify local and remote device names. If no local or remote device name is specified, all channels associated with the specified node are included, as well as the VC to the specified node.

Qualifiers

/AFTER=n

After the trace stop condition has been satisfied, continue tracing for n events, and then stop. If you do not specify /AFTER, tracing does not continue after the trace stop event. n can be any value between 0 and FFFFFFF.

/DEFAULT

Sets the trace context back to the default settings, which are:


       trace all channels and VCs
       /AFTER=0
       /EVENT=default settings
       /STOP
       /SIZE=512

/EVENT=(event1[,...])

Enables tracing on specific events, which you can use wildcards to specify. The default is a subset of the events, which includes most errors and state changes when the system parameter SYSTEM_CHECK is set to 0. The default is "all events included" when SYSTEM_CHECK is set to 1.

/EXCLUDE=(nodename[/LOCAL_DEVICE=landevicename] [/REMOTEDEVICE=landevicename][,...])

Excludes VCs or channels, or both, to specific nodes, which you can use wildcards to specify. Each node name can be accompanied by optional qualifiers to specify local and remote device names. If no local or remote device name is specified, the VC and all channels associated with the specified node are excluded.

/LOCAL_DEVICE=(landevicename[,...])

Includes specific LAN devices that identify the local end of the channel. You can use wildcards to specify LAN devices.

/REMOTE_DEVICE=(landevicename[,...])

Includes specific LAN devices that identify the remote end of the channel; you can use wildcards to specify LAN devices.

/STOP=(event1[,...])

Stops tracing on specific events, which you can use wildcards to specify. The default is "no events included."

/SIZE=n

Specifies a trace buffer size of n bytes to be used by PEDRIVER for each trace buffer: one for global PEDRIVER use, one for each selected channel, and one for each selected VC. n can be any value between 0 and FFFFFFF.

Usage Notes

  • Use the SHOW CHANNEL command to display node names and local and remote device names.
  • Use the SHOW TRACE/CONTEXT command to display event names.
  • Use the SHOW LAN_DEVICE command to display device names.
  • Use the SHOW TRACE/CONTEXT command to display event names.

Examples

#1

SCACP> SET TRACE/EVENT=CC_STATE/SIZE=1000
      

The command in this example specifies that the trace buffers for each channel, VC, and the global buffer each be 1000 bytes in length.

#2

SCACP> SET TRACE/EVENT=* NODE10/LOCAL=EWA,NODE20
      

The command in this example specifies that all events are to be recorded; when applicable to a particular node, however, only channels and VCs to nodes NODE10 and NODE20 are to be included.

#3

SCACP> SET TRACE/EVENT=(ALL,NOTIMER) NODE10
      

The command in this example specifies that all events except timer events on node NODE10 are to be included.

#4

SCACP> SET TRACE/LOCAL=EWA/REMOTE=EWB NODE10,NODE15/L=F*/R=F*,NODE20
      

The command in this example is equivalent to the following command:


SET TRACE NODE10/L=EWA/R=EWB,NODE15/L=F*/R=F*,NODE20/L=EWA/R:EWB

The command in the example sets tracing on the following channels:

  • On node NODE10, channels with local device EWA and remote device EWB
  • On node NODE15, channels with local LAN device starting with F and remote LAN device starting with F
  • On node NODE20, channels with local LAN device EWA and remote LAN device EWB

SET VC

Sets VC management parameters: checksumming values.

Format

SET VC nodename


Parameter

nodename[,...]

Includes VCs to specific nodes, which you can use wildcards to specify.

Usage Notes

  • Use the /EXCLUDE qualifier to exclude VCs to specific nodes.
  • Use the SHOW CHANNEL or SHOW VC commands to display VC names, which are simply the names of remote nodes.

Qualifiers

/CHECKSUMMING/

NOCHECKSUMMING (default)

Enables or disables checksum verification on the selected VCs to specified nodes.

You can use this command alone or in combination with the system parameter NISCS_PORT_SERV. (Refer to online help for NISCS_POST_SERV for more information.)

VC CLOSURE SIDE-EFFECT

When you enable or disable checksumming on a circuit, the circuit closes briefly and then reopens using the specified operating mode. This is necessary to ensure that both ends of the circuit are synchronized.

Because the SET VC/CHECKSUMMING setting is not valid beyond the life of the system, you might want to include SET VC/CHECKSUMMING commands in your startup file, or reissue these commands at the next boot.

/EXCLUDE=(nodename[,...])

Excludes VCs to specific nodes, which you can use wildcards to specify.

Example


SCACP> SET VC/CHECKSUMMING NODE10,NODE20
      

The command in this example enables checksum verification of VCs to nodes NODE10 and NODE20.

SHOW CHANNEL

Displays PEDRIVER channel information for specific nodes. Each channel is a single NISCA communications path between a LAN device on a local system and a LAN device on a remote system.

Usage Note

Use the SHOW CHANNEL command to display node names and local and remote device names.


Format

SHOW CHANNEL nodename


Parameter

nodename[,...]

Includes channels to specific nodes, which you can use wildcards to specify. Each node name can be accompanied by optional qualifiers to specify local and remote device names. If no local or remote device name is specified, all channels associated with the specified node name are included.

Qualifiers

/ALL

Includes all channel data.

/COUNTERS

Includes channel counters data.

/ECS

/NOECS

Includes only channels that are (or are not) members of the ECS.

/EXCLUDE=(nodename[,...])

Excludes channels to specific nodes, which you can use wildcards to specify.

Each node name can be accompanied by optional qualifiers to specify local and remote device names. If no local or remote device name is specified, all channels associated with the specified node are included.

/INTERVAL

For the /COUNTERS display, displays the changes to counters since the last SHOW command.

/LOCAL_DEVICE=(landevicename[,...])

Includes specific LAN devices that identify the local end of the channel; you can use wildcards to specify LAN devices.

/n

Displays the nth page. To select a particular page of a multipage display, specify the number of the page you want to display.

/OUTPUT=filespec

Creates the specified file and directs output to it.

/REMOTE_DEVICE=(landevicename[,...])

Includes specific LAN devices that identify the remote end of the channel; you can use wildcards to specify LAN devices.

/SDA

Includes channel data displayed in SDA format, with all the data collected in one display for one channel.

/SUMMARY

Includes channel summary data. This is the default if /ALL, /COUNTERS, and /SDA qualifiers are not specified.

Usage Note

Use the SHOW LAN_DEVICE command to display device names.


Examples

#1

SCACP> SHOW CHANNEL
      

The command in this example produces output similar to the following:


AFFC6 PEA0 Channel Summary 19-AUG-2003 08:53:11.80:

Remote  LAN Dev Channel  Total    ECS     Priority       Buffer   Delay   Load    Total    ---- Most Recent...
 Node   Loc Rmt  State  Errors   State    Cur  Mgt  Hops  Size    (uSec)  Class  Pkts(S+R)    CH Opened Time...
 ----   --- ---  -----  ------   -----    ---  ---  ----  ----    ------  -----  ---------    --------------
AFFC5   EWA EWA  Open        2  N(T,I,F)    0    0    2   1426     249.9    10    1043542  12-AUG 08:59:52.40
AFFC5   EBA EBA  Open        2  Y(T,P,F)    0    0    2   7268   18722.7 30000    1343885  12-AUG 08:59:51.37
AFFC6   LCL LCL  Open        1  Y(T,P,F)    0    0    2   1426     241.0     0    1038822  12-AUG 08:58:41.67

#2

SCACP> SHOW CHANNEL/ALL
      

In addition to channel summary information, the command in this example produces output similar to the following:


   .
   .
   .
AFFC6 PEA0 Channel Miscellaneous 19-AUG-2003 08:53:24.61:

Remote    -- LAN Device --         Local              Remote        ------ Buffer Size --------  ...
 Node     Local     Remote      LAN Address        LAN Address      Cur   Neg   Mgt   Loc   Rmt  ...
 ----     -----     ------      -----------        -----------      ---   ---   ---   ---   ---
AFFC5   EWA DE450 EWA DE450  AA-00-04-00-3F-4D  08-00-2B-C3-1F-C8  1426  1426  8120  1426  1426
AFFC5   EBA SMLAN EBA SMLAN  AA-00-04-00-3F-4D  00-00-00-00-02-00  7268  7268  8120  7268  7268
AFFC6   LCL       LCL        00-00-00-00-00-00  00-00-00-00-00-00  1426  1426  8120  1426  1426


AFFC6 PEA0 Channel Equivalent Channel Set (ECS) 19-AUG-2003 08:53:24.61:

Remote  LAN Dev    ECS     ECS      ECS       Average     Remote      Remote    Rsvp       Channel...
 Node   Loc Rmt   State  Losses  Transitions   RTTime    Ring Size   Rcv Cache  Thresh    Open Time...
 ----   --- ---   -----  ------  -----------   -----     ---------   ---------  ------    ---------
AFFC5   EWA EWA  N(T,I,F)      0          2      249.1         16        31         2   23:53:32.20
AFFC5   EBA EBA  Y(T,P,F)      0          3    18650.9         15        31         0   23:53:33.23
AFFC6   LCL LCL  Y(T,P,F)      0          1      241.0          8        31         1   23:54:42.93


AFFC6 PEA0 Channel Counters and Errors 19-AUG-2003 08:53:24.61:

Remote  LAN Dev     -- Transmit --          -- Receive --                Rexmit   TransmitFail Receive...
 Node   Loc Rmt    Messages    Bytes     Messages    Bytes    Xmt:Rexmit Errors   Penalties    Errors ...
 ----   --- ---    --------    -----     --------    -----    ---------- ------   ---------    ------
AFFC5   EWA EWA      392983   40871612     650580   67661700     392983       1          0          0
AFFC5   EBA EBA      542506   40213388     801402   67138651     542506       1          0          0
AFFC6   LCL LCL      393036   40877022     645808   67165310   Infinite       0          0          0


AFFC6 PEA0 Channel Errors 19-AUG-2003 08:53:24.61:

Remote  LAN Dev   -------------------- Receive --------------------    -- Timeouts --  No MSCP   Disk Not...
 Node   Loc Rmt  Bad Auth Bad ECO Bad MCA  Short  Incompat  Old Chan  Handshake Listen  Server    Served ...
 ----   --- ---  -------- ------- -------  -----  --------  --------  --------- ------  ------   ------
AFFC5   EWA EWA       0       0       0      0         0         0         0       0       0         0
AFFC5   EBA EBA       0       0       0      0         0         0         0       0       0         0
AFFC6   LCL LCL       0       0       0      0         0         0         0       0       0         0

#3

SCACP> SHOW CHANNEL NODE20/LOCAL=EWA
      

The command in this example displays channel definition data for all nodes defined with local device EWA and any remote device and remote node name starting with NODE20.

#4

SCACP> SHOW CHANNEL/COUNTERS/INTERVAL
SCACP> SPAWN WAIT 0:0:10
SCACP> SHOW CHANNEL/COUNTERS/INTERVAL
      

The first command in this example displays channel counters since the last SHOW command. The SPAWN command tells the DCL WAIT command to insert a 10-second delay. The second SHOW CHANNEL command displays counters after the 10-second period.

#5

SCACP> SHOW CHANNEL/1/3
      

The command in this example displays the first and third pages of data for all channels. The first page contains Channel Summary data, and the third page contains Channel Equivalent Channel Set (ECS) data.

#6

SCACP> SHOW CHANNEL/LOCAL=EWA/REMOTE=EWB NODE10,
NODE15/L=F*/R=F*, NODE20
      

The command in this example is equivalent to the following command:


SHOW CHANNEL NODE10/L=EWA/R=EWB, NODE15/L=F*/R=F*, NODE20/L=EWA/R:EWB

This command shows the following channels:

  • To node NODE10, the channel with local device EWA and remote device EWB
  • To node NODE15, the channel with local LAN device starting with F and remote LAN device starting with F
  • To node NODE20, the channel with local LAN device EWA and remote LAN device EWB

SHOW CIRCUIT

Displays SCA circuit information. You can further qualify each node name you specify with additional parameters to uniquely identify a single circuit.

Format

SHOW CIRCUIT nodename


Parameter

nodename[,...]

Includes specific circuits to individual nodes, which you can use wildcards to specify.

Qualifiers

/EXCLUDE=(nodename[/PORT=portname[/RSTATION=n]][,...])

Allows you to exclude a specific circuit to a node. If multiple circuits to the same node exist, you can use the /PORT and /RSTATION qualifiers to uniquely identify the circuit.

/PORT=portname[/RSTATION=n]

If multiple circuits to the same node exist, you can use the /PORT and /RSTATION qualifiers to uniquely identify the circuit. You can use the /RSTATION qualifier only in conjunction with the /PORT qualifier.

Example


SCACP>SHOW CIRCUIT
      

The command in this example displays all circuits to nodes over port PEA0.



 Circuit data for CLUIO2 at 07-DEC 11:55:31.80

  Node     Port   Priority       Load                Remote  Remote
  Name     Name   Cur   Mgt  Class    State     Station  Type
 -------- -------- ---- ---- -------- --------  -------  --------
 LYNX03   PEA0        0    0       10     Open      dc       NI
 CLUIO1   PEA0        0    0       10     Open      dd       NI
 PRMMC2   PEA0        0    0       10     Open      de       NI
 RXBOT1   PIB0        5    0       48     Open       4     RF72
 RXTOP1   PIB0        5    0       48     Open       1     RF73
 RXTOP0   PIB0        5    0       48     Open       0     RF73
 CLUIO1   PIB0        5    0       48     Open       7     N710
 R4JC3I   PIC0        5    0       48     Open       7     RF73
 R4HLEK   PIC0        5    0       48     Open       5     RF73
 R4XEWM   PIC0        5    0       48     Open       3     RF73
 R4A1FN   PIC0        5    0       48     Open       2     RF73
 R4XSVE   PIC0        5    0       48     Open       4     RF73
 R4VLNI   PIC0        5    0       48     Open       1     RF73

SCACP>SHOW CIRCUIT * /PORT=PEA0
      

The command in this example displays all circuits to all nodes.



 Circuit data for CLUIO2 at 07-DEC 12:42:23.03

   Node     Port              Priority    Load    Remote_Port
   Name     Name     State    Cur  Mgt    Class   Number  Type
 -------- -------- --------   ---- ---- -------- ------- --------
 LYNX03   PEA0       Open      0    0      100      dc       NI
 LYNX03   PNA0       Open      0    0      140       1       CI
 CLUIO1   PEA0       Open      0    0       10      dd       NI
 PRMMC2   PEA0       Open      0    0       10      de       NI

SHOW LAN_DEVICE

Displays PEDRIVER device data. Each device is a local LAN device on the system, which can be used for NISCA communications.

Format

SHOW LAN_DEVICE landevicename


Parameter

landevicename[,...]

Includes specific LAN devices, which you can use wildcards to specify.

Usage Notes

  • Use the /EXCLUDE qualifier to exclude LAN devices.
  • Use the SHOW LAN_DEVICE command to display device names.

Qualifiers

/ALL

Includes all device data.

/COUNTERS

Includes device counters data maintained by PEDRIVER and counters data maintained by the LAN drivers.

/EXCLUDE=(landevicename[,...])

Excludes specific LAN devices, which you can use wildcards to specify.

/INTERVAL

For the /COUNTERS display, displays the changes to counters since the last SHOW command.

/n

Displays the nth page. To select a particular page of a multipage display, specify the number of the page you want to display.

/OUTPUT=filespec

Creates the specified file and directs output to it.

/SDA

Includes LAN device data displayed in SDA format, with all the data collected in one display for one LAN device.

/SUMMARY

Includes device summary data. This is the default if /ALL, /COUNTERS, and /SDA qualifiers are not specified.

Examples

#1

SCACP> SHOW LAN_DEVICE
      

The command in this example produces output similar to the following:


SYS999 PEA0 Device Summary 31-JAN-2001 10:58:57.93:

       Device Errors +                           Mgt  Buffer MgtMax  Line    Total       Current
Device  Type  Events    Status                Priority Size  BufSiz  Speed Pkts(S+R)   LAN Address
------  ----  ------    ------                -------- ----  ------  ----- ---------   -----------
 LCL               0  Run Online Local Restart      0  1426      0    N/A     46456  00-00-00-00-00-00
 FWA   DEFPA  847806  Run Online Restart            0  4396      0    100         0  08-00-2B-B9-1A-2C
 EWA   DE500       0  Run Online Restart         -123  1426      0     10    228538  AA-00-04-00-62-4D
 EWB   DEGPA    1204  Run Online Restart            0  7460      0   1000     63188  00-60-6D-21-12-1E
   .
   .
   .
#2

SCACP> SHOW LAN_DEVICE/ALL
      

The command in this example produces output similar to the following:



SYS999 PEA0 Device Summary 31-JAN-2001 10:59:00.88:

       Device Errors +                           Mgt  Buffer MgtMax  Line    Total       Current
Device  Type  Events    Status                Priority Size  BufSiz  Speed Pkts(S+R)   LAN Address
------  ----  ------    ------                -------- ----  ------  ----- ---------   -----------
 LCL               0  Run Online Local Restart      0  1426      0    N/A     46456  00-00-00-00-00-00
 FWA   DEFPA  847806  Run Online Restart            0  4396      0    100         0  08-00-2B-B9-1A-2C
 EWA   DE500       0  Run Online Restart         -123  1426      0     10    228538  AA-00-04-00-62-4D
 EWB   DEGPA    1204  Run Online Restart            0  7460      0   1000     63188  00-60-6D-21-12-1E
   .
   .
   .
SYS999 PEA0 Device Counters and Errors 31-JAN-2001 10:59:00.88:

      --------- Transmit ---------   --------- Receive -------- Port  Port  Addr  Restart
Device  Messages    Bytes   Errors  Messages    Bytes   Errors Usable Down Change Failed *Last Event Time
------  --------    -----   ------  --------    -----   ------ ------ ---- ------ ------ ----------------
LCL       77926   10131658      0      77926    9196546      0     1*   0       0      0 30-JAN 14:53:04.27
EBA       79932   10771395      0      79828    9471857      0     1*   0       0      0 30-JAN 14:53:04.27
EWA    95170718  951046392      0   90389699  824505995      0     1    0       1*     0 30-JAN 14:53:54.96
EWB    28515398 3596974072      0   31235328 1573461656      0     1    0       1*     0 30-JAN 14:53:56.96
ELA   288523549 3938187772      0  268398349 1991472896      0     1*   0       0      0 30-JAN 14:53:04.38

SYS999 PEA0 Device Errors 31-JAN-2001 10:59:00.88:

        - Transmit -                      ------------------- Received --------------------    Allocation
       Generic Hello                      With Bad  Mcast TR  Short  Short  On Wrong Discard  Failures On
Device Errors  Errors Last Transmit Error SYSTEMID  Message  CC Msg  DX Msg   Port   PortDisa   CH    VC
------ ------  ------ ------------------- --------  -------  ------  ------   ----   --------  ----  ----
LCL      0       0    (No time)                0        0       0       0       0       0        0     0
EBA      0       0    (No time)                0        0       0       0       0       0        0     0
EWA      0       0    (No time)                0        0       0       0       0       0        0     0
EWB      0       0    (No time)                0        0       0       0       0       0        0     0
ELA      0       0    (No time)                0        0       0       0       0       0        0     0


SYS999 LAN Counters and Errors 31-JAN-2001 10:59:00.88:

        ---------- Transmit --------    ---------- Receive ------  Buffer Unavailable -- Unrecognized --
Device   Packets       Bytes  Errors    Packets       Bytes  Errors System User Individual Multicast Events
 ------   -------      -----  ------    -------       -----  ------ ------ ---- ---------- --------- ------
LCL           0            0       0          0            0    0      0      0       0         0         0
EBA       80172     10808778       0      80068     10786180    0      0      0       0       240         0
EWA    95170964 214548983411       0   90390818 185699326463    0      0      0       0      1119         0
EWB    28520511  14930703525       0   31255260  18836142478    0      0      0    1697      1653         0
ELA   288523791 655074988675       0  268399522 415695135533    0      0      0       0      1173         0
#3

SCACP> SHOW LAN_DEVICE/COUNTERS
      

The command in this example displays device counters.

#4

SCACP> SHOW LAN_DEVICE/COUNTERS/INTERVAL
SCACP> SPAWN WAIT 0:0:10
SCACP> SHOW LAN_DEVICE/COUNTERS/INTERVAL
      

The first command in this example displays device counters since the last SHOW command. The SPAWN command tells the DCL WAIT command to insert a 10-second delay. The second SHOW command displays counters after the 10-second period.

SHOW PORT

Displays information about selected SCA ports.

Format

SHOW PORT portname


Parameter

portname[,...]

Displays information about specific SCA ports, which you can use wildcards to specify. If no portname is specified, all ports on the node are displayed.

Qualifiers

/EXCLUDE=(portname[,...])

Excludes specific port names from the display. You cannot use wildcards to specify port names.

/OUTPUT=filespec

Creates the specified file and directs the output of the command to this file.

Example


SCACP> SHOW PORT
      

The command in this example produces output similar to the following:


Port data for AFFC6 at 19-AUG 09:05:52.84

    Port  Mgt  Load     Msgs       Msgs       DGs        DGs
    Name  Prio Class    Sent       Rcvd       Sent       Rcvd
   ------ ---- ----- ---------- ---------- ---------- ----------
    PEA0     0    10          0     227053          0          0
    PBA1     0 32767     414250     328271          0          0

SHOW TRACE

Displays PEDRIVER tracing data and parameters.

Note

This command is reserved for use by HP Services and OpenVMS Engineering only. Trace commands and output are subject to change from release to release.

Format

SHOW TRACE nodename


Parameter

nodename[,...]

Includes channels to specific nodes, which you can use wildcards to specify.

Each node name can be accompanied by optional qualifiers to specify local and remote device names. If no local or remote device name is specified, all channels associated with the specified node are included.

To display node names and local and remote device names, use the SHOW CHANNEL command.


Qualifiers

/CONTEXT

Displays only PEDRIVER trace settings and the event definition. If this qualifier is not included, trace event data is displayed.

/EVENT=(event1[,...])

Enables tracing on specific events, which you can use wildcards to specify. The default is all of the events that are in the trace buffer.

/EXCLUDE[=(nodename[,...])

Excludes channels to specific nodes, which you can use wildcards to specify. Each node name can be accompanied by optional qualifiers to specify local and remote device names. If no local or remote device name is specified, all channels associated with the specified node are included.

/GLOBAL (default when no nodes are specified)

/NOGLOBAL (default when nodes are specified)

Specifies whether global trace data is to be returned.

/INPUT=filename

Reads trace data from the specified file and displays it.

/LOCAL_DEVICE=(landevicename[,...])

Includes specific LAN devices that identify the local end of the channel; you can use wildcards to specify LAN devices.

/OUTPUT=filename

Creates the specified file and directs output to it. If the filename extension is .DMP, the trace data is written to a dump file so that you can use the /INPUT qualifier to display it later.

/REMOTE_DEVICE=(landevicename[,...])

Includes specific LAN devices which identify the remote end of the channel, which you can use wildcards to specify.

/SORT

/NOSORT (default)

Returns trace data sorted across channels, VCs, and the global trace buffer by sequence number. The default is trace data returned for channels and VCs one at a time, in order, for the channel or VC, but not across channels and VCs.

Usage Notes

  • Use the SHOW TRACE/CONTEXT command to display event names.
  • Use the SHOW LAN_DEVICE command to display device names.

Examples

#1

SCACP> SHOW TRACE
      

The command in this example produces output similar to the following:


SYS999 Trace Results 31-JAN-2001 10:59:24.81

 EntryTimeStamp  Sequence  VC/Channel        State/Status  Addl Data                      Event/SubType
 --------------  --------  ----------        ------------  ---------                      -------------
53850998.232793  00000004    SYS999          004  STS.   = 00000004 00000000 00000000 ECS_state/Exiting NEW_EPOCH
53850998.232793  00000009    SYS999          004  WSeq   = 00010001 LAcc   = 00000000 Send_TR_msg/None
53850998.232793  0000000A    SYS999          005  00000000 00000000 00000000 00000000 VC_state/VC opened
53850998.232793  0000000B    SYS999          005  WSeq   = 00010001 LAcc   = 00000000 Send_TR_msg/None
53850998.232793  0000000C    SYS999          005  WSeq   = 00010001 LAcc   = 00000000 Send_TR_msg/None
   .
   .
   .
53851866.350546  3069EF05    SYS11           005  WSeq   = 00010553  LAcc   = 000008CB Send_TR_msg/None
53851866.350628  3069EF0C    SYS666          005  EDly   = 007F428A 000F722A 0003B13A Rcvd_TR_msg/Estimated RTT
53851866.352023  3069EF7E    SYS44           005  WSeq   = 00010000 LAcc   = 00000D01 Send_TR_msg/None
53851866.352140  3069EF8B    SYS11           005  EDly   = 0075FFB9 000E16E8 00054879 Rcvd_TR_msg/Estimated RTT
53851866.375951  3069F644  SYS444_EWB_EIB   Open 6B Evnt = 00000000 00000000 00000000 CC_event/Process CC event
  .
  .
  .

  Channel status legend:
    6B - Path Open Remote_HWA_valid Tight Fast

  VC status legend:
    004 - Path
    005 - Open Path
    00D - Open Path Queued
#2

SCACP> SHOW TRACE/CONTEXT
      

The command in this example displays trace settings and definition.

#3

SCACP> SHOW TRACE/OUTPUT=NODE10.TRC
      

The command in this example displays trace data and writes it to the specified file.

An example of the screen output of a SHOW TRACE/CONTEXT command follows.


SYS999 Trace Context 31-JAN-2001 10:59:28.25:

  Trace buffer size requested 2048 bytes
  Trace buffer total allocated 92160 bytes
  Trace buffer allocations 45 successful
  Trace buffer allocations 0 failed
  Current trace sequence number 812286047
  System cycle counter 404196 cps
  Stop tracing 0 events after stop event

  Trace  Stop  Default  Event
  -----  ----  -------  -----
  Active          Y     Error
  Active                Penalize_ch
  Active                Timer
  Active                Listen_timr
  Active                Handsh_timr
  Active                Size_probe
  Active                Delay_msmt
  Active                Verf_vack
  Active          Y     CC_event
  Active          Y     CC_state
  Active          Y     Path_state
  Active          Y     ECS_state
  Active                ACK_process
  Active          Y     Chan_update
  Active                Rcvd_CC_msg
  Active                Rcvd_TR_msg
  Active                Send_TR_msg
  Active                Xmt_failed
  Active          Y     VC_state
  Active                ACK_timeout
  Active          Y     TMO_listen
                  Y     No_path

    Channel Selection:
    Local Dev  Remote Dev  Remote Node Name    Selection
    ---------  ----------  ----------------    ---------
    All channels and VCs selected
#4

SCACP> SHOW TRACE/LOCAL=EWA/REMOTE=EWB NODE10,NODE15/L=F*/R=F*,NODE20
      

The command in this example is equivalent to the following command:


  SHOW TRACE NODE10/L=EWA/R=EWB, NODE15/L=F*/R=F*, NODE20/L=EWA/R:EWB

In this example, the command shows tracing for the following channels:

  • To node NODE10, channels with local device EWA and remote device EWB
  • To node NODE15, channels with local LAN device starting with F and remote LAN device starting with F
  • To node NODE20, channels with local LAN device EWA and remote LAN device EWB

SHOW VC

Displays PEDRIVER virtual circuit data. Each VC is an SCACP communications path between the local system and a remote system comprised of a set of channels.

Usage Note

Use the SHOW CHANNEL or SHOW VC commands to display node names, which are simply the names of the remote nodes.


Format

SHOW VC nodename


Parameter

nodename[,...]

Includes specific nodes, which you can use wildcards to specify.

Qualifiers

/ALL

Includes all VC data.

/COUNTERS

Includes VC counter data.

/EXCLUDE=(nodename[,...])

Excludes specific nodes, which you can use wildcards to specify.

Use the SHOW CHANNEL or SHOW VC commands to display VC names, which are simply the names of the remote nodes.

/INTERVAL

For the /COUNTERS display, displays the changes to counters since the last SHOW command.

/n

Displays the nth page. To select a particular page of a multipage display, specify the number of the page you want to display.

/OUTPUT=filespec

Creates the specified file and directs output to it.

/SDA

Includes VC data displayed in SDA format.

/SUMMARY

Includes VC summary data. This is the default if /ALL, /COUNTERS, and /SDA qualifiers are not specified.

Examples

#1

SCACP> SHOW VC
      

The command in this example produces output similar to the following:


AFFC6 PEA0 VC Summary 19-AUG-2003 08:23:20.30:

Remote        Total           Channels  ECS MaxPkt   ReXmt  XmtWindow Xmt       Total     ------Most Recent ...
Node    State Errors  Xmt:TMO Open ECS  Pri  Size  TMO(uSec) Cur Max  Options   Pkts(S+R)  VC Opened Time ...
------  ----- ------  ------- ---- ---  ---  ----  --------- --- --- ---------  ---------  ------------------...
 AFFC5  Open       0 Infinite    2   1    0  7268   522711.6  15  15               678293  12-AUG 08:59:51.37...
 AFFC6  Open       0 Infinite    1   1    0  1426  3000000.0   1   8                    5  12-AUG 08:58:41.67...

#2

SCACP> SHOW VC/ALL
      

In addition to VC summary information, the command in this example produces output similar to the following:


   .
   .
   .

AFFC6 PEA0 VC Equivalent Channel Set (ECS) Membership Criteria 19-AUG-2003 08:23:20.30:

Remote Number Number  Buffer Size  ECS   ECS   Load   Current  -- ECS Speed Thrsh --   #LAN Devices ...
Node   Epochs NewECS   VC   ECS    Pri.  Hops  Class  MinDly  Faster  Promote Demote    Loc   Rem   ...
------ ------ ------  ----- -----  ----  ----  -----  ------- ------- ------- --------  ----- ----- ...
 AFFC5      9      9   7268  7268     0     2  30000  16140.4 14122.9 20175.4  23201.8      1     1 ...
 AFFC6      2      2   1426  1426     0     2      0    108.8     0.0  1017.3   1478.3      1     1 ...


AFFC6 PEA0 VC Sequence Numbers and Miscellaneous 19-AUG-2003 08:23:20.30:

Remote Next Seq     Lowest Ack    Highest Ack     High Seq Rcvd  Last     Total     ---MaxCache--- ...
Node   To Send(NSU) Received(LAR) Acceptable(HAA) In Order(HSR)  Accepted RcvCached Max  Mgt  Rmt  ...
------ ------------ ------------- --------------- -------------- -------- --------- ---- ---- ----
 AFFC5        37330         3732F           3732F          3732F    3732F    0   31    0   31     0...
 AFFC6            1             0               0              0        0    0   31    0   31     0...


AFFC6 PEA0 VC Counters 19-AUG-2003 08:23:20.30:

Remote  ----------------- Transmit -------------------- MaxCmdq --------------- Receive -------------
Node    Messages Acks    Retransmits Bytes     WinFull   Len    Messages Acks     Duplicates Bytes  ...
------  -------- --------- --------- --------- --------- -----  -------- --------- --------- ---------
 AFFC5    339147    113049         0  19105253         0     1    339146    113049         0  17070331...
 AFFC6         3         0         0       210         0     0         2         0         0       108...


AFFC6 PEA0 VC Errors 19-AUG-2003 08:23:20.30:

        --------------------- Receive -----------------------  -----Transmit ----- ------- VC Closures
Remote  Short   Illegal  Illegal Checksum  Cache     FreeQ     SeqPkt              SeqPkt     No   ...
Node    Message Ack      SeqPkt  Failures  Misses    Empty     Timeouts  NoXmtChan RetryExh   Path ...
------- ------- -------- -------- -------- --------- --------- --------- --------- ---------- ---------
  AFFC5       0        0        0        0         0         0         0         0          0         0
  AFFC6       0        0        0        0         0         0         0         0          0         0

#3

SCACP> SHOW VC/COUNTERS NODE10
      

The command in this example displays VC counters for all VCs whose name (remote node name) starts with NODE10.

#4

SCACP> SHOW VC/COUNTERS/INTERVAL
SCACP> SPAWN WAIT 0:0:10
SCACP> SHOW VC/COUNTERS/INTERVAL
      

The first command in this example displays VC counters since the last SHOW command. The SPAWN command tells the DCL WAIT command to insert a 10-second delay. The second SHOW VC command displays counters after the 10-second period.

SPAWN

Creates a subprocess of the current process. The SPAWN command copies the context of the subprocess from the current process.

Format

SPAWN [command-string]


Parameter

command-string

A string of commands to be executed in the context of the created subprocess. After the command string is executed, control returns to SCACP.

Qualifiers

None.

Example


SCACP> SPAWN SHOW TIME
24-AUG-2002 15:22:39
SCACP>
      

The command in this example creates a subprocess of the current process and displays the time.

START LAN_DEVICE

Directs PEDRIVER to start using the specified LAN device. The original (and still supported) means of starting PEDRIVER on a LAN device is SYS$EXAMPLES:LAVC$START_BUS.

Format

START LAN_DEVICE landevicename


Parameter

landevicename[,...]

Includes specific LAN devices, which you can use wildcards to specify.

Usage Notes

  • Use the /EXCLUDE qualifier to exclude LAN devices.
  • Use the SHOW LAN_DEVICE command to display device names.

Qualifiers

/EXCLUDE=(landevicename[,...])

Excludes specific LAN devices, which you can use wildcards to specify.

Usage Note

Use the SHOW LAN_DEVICE command to display device names.


Example


SCACP> START DEVICE EWA
      

This command starts PEDRIVER on the LAN device EWA.

START TRACE

Starts or resumes PEDRIVER tracing, optionally setting tracing options.

Note

This command is reserved for use by HP Services and OpenVMS Engineering only. Trace commands, their qualifiers, and output are subject to change from release to release.

Format

START TRACE nodename


Parameter

nodename[,...]

Includes information about communications with specific nodes, which you can use wildcards to specify. Each node name can be accompanied by optional qualifiers to specify local and remote device names. If no local or remote device name is specified, the VC and all channels associated with the specified node are included.

Usage Note

Use the SHOW CHANNEL command to display node names and local and remote device names.


Qualifiers

/AFTER=n

After the trace stop condition has been satisfied, continues tracing for n events, and then stops. If you do not specify /AFTER, tracing does not continue after the trace stop event. n can be any value between 0 and FFFFFFF.

/DEFAULT

Sets the trace context back to the default settings, which are:


       channelname=*
       /AFTER=0
       /EVENT=default settings
       /STOP
       /SIZE=512

/EVENT=(event1[,...])

Enables tracing on specific events, which you can use wildcards to specify. The default is a subset of the events, which includes most errors and state changes.

/EXCLUDE=(landevicename[,...])

Excludes specific LAN devices, which you can use wildcards to specify.

/LOCAL_DEVICE=(landevicename[,...])

Includes specific LAN devices which identify the local end of the channel; you can use wildcards to specify LAN devices.

/REMOTE_DEVICE=(landevicename[,...])

Includes specific LAN devices that identify the remote end of the channel. You can use wildcards to specify LAN devices.

/STOP=(event[,...])

Stops tracing on specific events, which you can use wildcards to specify. The default is to stop no events.

/SIZE=n

Specifies a trace buffer size of n bytes to be used by PEDRIVER for each trace buffer: one for global PEDRIVER use, one for each selected channel, and one for each selected VC. n can be any value between 0 and FFFFFFF.

Usage Notes

  • Use the SHOW TRACE/CONTEXT command to display event names.
  • Use the SHOW LAN_DEVICE command to display device names.

Examples

#1

SCACP> START TRACE/EVENT=CC_STATE/SIZE=2000
      

The command in this example changes the Trace Channel Control layer state with a 2000-byte trace buffer.

#2

SCACP> START TRACE/EVENT=ALL NODE10,NODE20
      

The command in this example traces all events but only for the NODE10 and NODE20 channels.

#3

SCACP> START TRACE/LOCAL=EWA/REMOTE=EWB NODE10,
NODE15/L=F*/R=F*, NODE20
      

The command in this example is equivalent to the following command:


START TRACE NODE10/L=EWA/R=EWB, NODE15/L=F*/R=F*, NODE20/L=EWA/R:EWB

In the example, the command starts tracing for the following channels:

  • To node NODE10, channels with local device EWA and remote device EWB
  • To node NODE15, channels with local LAN device starting with F and remote LAN device starting with F
  • To node NODE20, channels with local LAN device EWA and remote LAN device EWB

STOP LAN_DEVICE

Directs PEDRIVER to stop using the specified LAN device. The original (and still supported) means of stopping PEDRIVER on a LAN device is SYS$EXAMPLES:LAVC$STOP_BUS.

Caution

If you use either STOP LAN_DEVICE or SYS$EXAMPLES:LAVC$STOP_BUS to stop the only device you have providing communications to a cluster, the system will CLUEXIT.

Format

STOP LAN_DEVICE landevicename


Parameter

landevicename[,...]

Includes specific LAN devices, which you can use wildcards to specify.

Usage Notes

  • Use the /EXCLUDE qualifier to exclude LAN devices.
  • Use the SHOW LAN_DEVICE command to display device names.

Qualifier

/EXCLUDE=(landevicename[,...])

Excludes specific LAN devices, which you can use wildcards to specify.

Example


SCACP> STOP LAN_DEVICE EWA
      

This command stops PEDRIVER on the LAN device EWA.

STOP TRACE

Stops PEDRIVER tracing. You can read the trace data recorded so far with a SHOW TRACE command.

Usage Note

To revert trace behavior to initial settings, enter the command SET TRACE/DEFAULT.

Note

This command is reserved for use by HP Services and OpenVMS Engineering only. Trace commands and output are subject to change from release to release.

Format

STOP TRACE


Parameters

None.

Qualifiers

None.

Example


SCACP> STOP TRACE
      

The command in this example stops PEDRIVER tracing.


Previous Next Contents Index