HP OpenVMS systems documentation

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.

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

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

17.1 PPPD Description

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.

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.

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.

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.

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.

18.1 Description

• 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.

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].

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

19.1 SCACP Description

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

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.

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.

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.

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

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.

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.

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?

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

SCACP> SET CHANNEL/PRIORITY=3 NODE5
      

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

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

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.

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.

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

SCACP> SET PORT PEA0/PRIORITY=5
      

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

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 sets or modifies PEDRIVER tracing parameters.

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

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.

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.

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.

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

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.

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

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

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

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.

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.

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.

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

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

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

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 . . .

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

SCACP> SHOW LAN_DEVICE/COUNTERS
      

The command in this example displays device counters.

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.

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

Displays PEDRIVER tracing data and parameters.

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

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

SCACP> SHOW TRACE/CONTEXT
      

The command in this example displays trace settings and definition.

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

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

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

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...

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

SCACP> SHOW VC/COUNTERS NODE10
      

The command in this example displays VC counters for all VCs whose name (remote node name) starts with NODE10.

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.

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.

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.

Starts or resumes PEDRIVER tracing, optionally setting tracing options.

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

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.

SCACP> START TRACE/EVENT=ALL NODE10,NODE20
      

The command in this example traces all events but only for the NODE10 and NODE20 channels.

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

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.

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.

Format

STOP TRACE

Parameters

None.

Qualifiers

None.

Example

SCACP> STOP TRACE
      

The command in this example stops PEDRIVER tracing.