ZIIP

#### Search Results

Search

# ZIIP

`ZIIP` |  | `ziip-subfunction-and-option` `MENU` |

This system command applies to z/OS batch, batch servers, Com-plete, CICS, TSO and IMS TM environments that support the use of the IBM System z Integrated Information Processor (zIIP). Prerequisite: The required Natural for zIIP product(s) must be installed at your site.

If this system command is issued from a different environment and/or without zIIP support enabled, and/or if the required Natural for zIIP product is not installed, appropriate error messages occur.

The `ZIIP` system command provides status and processing information on the zIIPs used in your environment and the license file required for the Natural for zIIP product installed at your site. In addition, you can obtain statistics on the Natural components that cause switches to the general central processor (GCP) and manage the component switch counting.

For detailed information on zIIP support, usage and monitoring, refer to the Natural for zIIP documentation.

- Syntax of ziip-subfunction-and-option

- Syntax Element Description

- zIIP Reports

- ZIIP Menu for Report Output Options

- User Exit for ZIIP PRINT

- Application Programming Interface (API) for ZIIP Functions

This document covers the following topics:

## Syntax of ziip-subfunction-and-option

| `PRINT` |  | `INFO` `ROLL` |  |  |  |
| `STAT` `ALL` |  |  | `SORTDESC` `SORTNAME` `SORTPRODUCT` `SORTSWITCHES` |  | `[PRODUCT product-range]` `[PARAMETER {*|Y|N}]`
`STAT` |  | `ON` `OFF` `CLR` |  |
`LIC` |  | `ASIS` `XML` `FORMATTED` |  |
`RESET` |  | `ALL` `SRB` `STAT` `SWITCH` `TIMES` |  |

## Syntax Element Description

Subfunction | Option | Explanation
--- | --- | ---
`PRINT`* | `INFO` | Displays the zIIP Processing Information report.
`ROLL` | Displays the Roll Server zIIP Information report.
`STAT` | Displays the zIIP Component Switch Statistics report if component switch counting has been activated (see `STAT` below). See also Sort Options for the zIIP Component Switch Statistics to determine the sort sequence.
| `ALL` (default) | Displays the zIIP Processing Information report first, followed by the Roll Server zIIP Information report and the zIIP Component Switch Statistics (if activated). See also Sort Options for the zIIP Component Switch Statistics to determine the sort sequence.
`STAT`* | `ON` | Activates the component switch counting.
`OFF` | Deactivates the component switch counting.
`CLR` | Clears the component switch table.
`LIC` | `ASIS` | Displays the XML-formatted zIIP license file left-justified.
`XML` | Displays the XML-formatted zIIP license file.
`FORMATTED` (default) | Displays the zIIP license file in free format without brackets.
`RESET` | `ALL` | Reset all counters
`SRB` | Reset the start SRB counter
`STAT` | Reset the component switch table (equivalent to `STAT CLR`)
`SWITCH` | Reset the TCB switch counter
`TIMES` | Reset all CPU time values

* Alternatively, you can set the keyword subparameters `STAT` and `PRINT` of the profile parameter `ZIIP` and the macro `NTZIIP` respectively. See Keyword Subparameters in the section ZIIP - zIIP Processing (z/OS only) in the Parameter Reference documentation.

The RESET function does not affect the roll server zIIP information counters and CPU times.

### Sort Options for zIIP Component Switch Statistics

Keyword | Sort Order
--- | ---
`SORTDESC` | The report is sorted ascending by the component description.
`SORTNAME` | The report is sorted ascending by the component name.
`SORTPRODUCT` | The report is sorted ascending by the product name.
`SORTSWITCHES` (default) | The report is sorted descending by the number of TCB switches (default).

### Selection Criteria for zIIP Component Switch Statistics

Keyword | Description
--- | ---
`PRODUCT` | Lists the components of a single product or a range of products specified with `product-range`. Valid values for `product-range` are:
`ppp` | A valid product code. Select the product that corresponds to the three-character product code `ppp` as shown in the Prd column of the zIIP Component Switch Statistics report.
`p*` or `pp*` | One or two leading characters. Selects all products whose product codes start with `p*` or `pp*`.
`ppp>` | A start value. Selects all products with product codes greater than or equal to `ppp`.
`ppp<` | An end value. Selects all products with product codes less than or equal to `ppp`.
`PARAMETER` | Specifies the components to be listed. Valid values are:
* | Selects all components (default).
`Y` | Selects only components with a `P` indicator denoting that component switches can be influenced by a parameter.
`N` | Selects only components (without a `P` indicator) whose component switches cannot be influenced by a parameter.

## zIIP Reports

This section describes the reports and statistical data provided by the `ZIIP` system command.

- zIIP Processing Information

- Roll Server zIIP Information

- zIIP Component Switch Statistics

### zIIP Processing Information

The zIIP Processing Information report looks similar to the example below:

    +---------------- zIIP Processing Information ---------------+
    |                                                            |
    |            Advanced zIIP Support Enabled                   |
    |                                                            |
    |  General central processors (GPs)             6            |
    |  Integrated Information Processors (zIIPs)    1            |
    |   zIIP SMT threads                            2            |
    |  zIIP normalization factor                10.98            |
    |                                                            |
    |  Switches into TCB mode                 1590303            |
    |  SRB starts                                  80            |
    |                                                            |
    |  Total enclave CPU time            01:00:56.411  (100.00%) |
    |   Enclave GP time                  00:12:38.305   (20.74%) |
    |   Enclave zIIP time                00:48:18.106   (79.26%) |
    |                                                            |
    |  Eligible zIIP CPU time            00:48:22.619  (100.00%) |
    |   Enclave zIIP time                00:48:18.106   (99.84%) |
    |   Eligible zIIP time on GP         00:00:04.513    (0.16%) |
    |                                                            |
    |  (zIIP times normalized)                                   |
    |                                                            |
    |                                                            |
    +------------------------------------------------------------+

If the z/OS system parameter PROJECTCPU=YES is set and no zIIPs are configured to the current logical partition, the report looks similar to the example below:

    +--------------- zIIP Processing Information ---------------+
    !                                                           !
    !           Advanced zIIP Support Enabled (PROJECTCPU)      !
    !                                                           !
    ! General central processors (GPs)             2            !
    ! Integrated Information Processors (zIIPs)    0            !
    !                                                           !
    ! zIIP normalization factor                 0.00            !
    !                                                           !
    ! Switches into TCB mode                     938            !
    ! SRB starts                                   6            !
    !                                                           !
    ! Total enclave CPU time            00:00:06.091  (100.00%) !
    !  Enclave TCB time                 00:00:04.640   (76.19%) !
    !  Enclave SRB time (*)             00:00:01.452   (23.81%) !
    !                                                           !
    ! (*) possible zIIP offload                                 !
    !                                                           !
    !                                                           !
    !                                                           !
    +-----------------------------------------------------------+

This report provides the following status and processing information:

Report Item | Explanation
--- | ---
Advanced zIIP Support Enabled | Indicates that the current Natural session runs with full zIIP enablement.
General central processors (GPs) | The number of GPs running under your z/OS system.
Integrated Information Processors (zIIPs) | The number of zIIPs running under your z/OS system.
zIIP SMT threads | The number of logical zIIPs running under your z/OS system if SMT (Simultaneous Multi-Threading) is active.
zIIP normalization factor | The zIIP normalization factor indicates the ratio of zIIP to GP speed. This factor tells you how fast your zIIP runs compared to a throttled GP with reduced power. In the example above, the value of `10.98` means that one zIIP is about eleven times faster than one GP.
Switches into TCB mode | The number of switches from SRB (service request block) into TCB (task control block) processing mode due to any system service calls that had to be issued. The corresponding switches back into SRB mode are not counted.
SRB starts | The number of times an SRB process was started. The counter is incremented by 1 for the first SRB at each session start and for the SRB restart after an abnormal termination in SRB mode.
Total enclave CPU time | The total CPU time (GP plus zIIP) consumed by the Natural WLM enclave.
Enclave GP time | The total GP time consumed within the Natural WLM enclave.
Enclave zIIP time | The total zIIP time consumed within the Natural WLM enclave.
Eligible zIIP CPU time | The total CPU time qualified for zIIP.
Eligible zIIP time on GP | The CPU time within the Natural WLM enclave on the GP qualified for zIIP but not used by it. A non-zero value means that zIIP-eligible workload could not be offloaded because no zIIP was available.

For details on the statistics items, refer to Natural zIIP Processing: TCBs, SRBs and Enclaves and Calculating the CPU Time in the Natural for zIIP documentation.

For hints on improving zIIP exploitation, refer to Tuning zIIP Usage in the Natural for zIIP documentation.

#### PF Keys Available on the zIIP Processing Information Screen

ENTER or PF5 | Updates the report data.
PF7 | Switches to the zIIP Component Switch Statistics. (Applies to `PRINT ALL` only.)
PF8 | Switches to the Roll Server zIIP Information report. (Applies to `PRINT ALL` only.)

### Roll Server zIIP Information

The Roll Server zIIP Information report looks similar to the example below:

    +------------- Roll Server zIIP Information -------------+
    !                                                        !
    ! Roll Server zIIP CPU Time Usage in Subsystem QA82      !
    !                                     Job Name QAROLL82  !
    !                                                        !
    ! Total WLM enclave CPU time ....                387524  !
    ! Qualified zIIP CPU time .......                387252  !
    ! Eligible zIIP CPU time on GCP                     133  !
    ! Total WLM enclave zIIP CPU time                387119  !
    ! Total WLM enclave zIIP CPU time (%)             99.89  !
    !                                                        !
    ! (All times in milliseconds; zIIP times normalized.)    !
    !                                                        !
    +--------------------------------------------------------+

This report provides the following status and processing information:

Report Item | Explanation
--- | ---
Total WLM enclave CPU time | The total CPU (GCP plus zIIP) time consumed by the current WLM enclave.
Qualified zIIP CPU time | The time qualified for zIIP usage on SRB, which is the sum of the eligible plus the total zIIP CPU time.
Eligible zIIP CPU time on GCP | The CPU time on the GCP qualified for a zIIP but not used by it. A non-zero value means that zIIP-eligible workload could not be offloaded because no zIIP was available.
Total WLM enclave zIIP CPU time | The total zIIP CPU time consumed by the current WLM enclave.
Total WLM enclave zIIP CPU time (%) | The percentage of the total zIIP CPU time consumed by the current WLM enclave. In the example above, Natural was able to offload 99.88 % of the total CPU load to a zIIP.

### zIIP Component Switch Statistics

The zIIP Component Switch Statistics report lists all non-zero TCB switches and the components that cause these switches as shown in the following example:

    +------------------ zIIP Component Switch Statistics -------------------------+
    !                                                                             !
    ! Prd Component Description                              TCB Switches   %   P !
    ! --------------------------------------------------------------------------- !
    ! NAT CMDBAS   Call Adabas ...............................     321587 37.43 P !
    ! NSB NSBCNXP  DB2 ConnecX access ........................     140356 16.33   !
    ! NVS NVSEXSH  VSAM I/O scheduler ........................     120904 14.07   !
    ! RPC RPC2ETB  RPC interface to EntireX Broker Stub ......     108488 12.62 P !
    ! NAT NATGWSTG Request handler for Natural Development Ser      94914 11.04 P !
    ! NAT CMPINIT  Session initialization exit ...............      58361  6.79   !
    ! ADA LNKDWA_Z TP dependent wait .........................      10947  1.27   !
    ! NAT CMWAIT   Wait for specified interval ...............       1234  0.14 P !
    ! COR COR00009 Program delete ............................        612  0.07   !
    ! NDB NDBWLI   DB2 IFI calls (DSNWLI) and RRSAF (DSNRLI) a        527  0.06 P !
    ! NAT CMFREMP  Release working storage ...................        373  0.04 P !
    ! COR COR00001 Lock contention ...........................        261  0.03   !
    ! NAT CMDLET   Release external module ...................        213  0.02 P !
    ! NAT ZPINIT   Initialization of zIIP support ............        193  0.02   !
    ! NAT CMABEND  Controlled abend routine ..................        133  0.01   !
    ! --------------------------------------------------------------------------- !
    !     Total                                                    859103         !
    !-----------------------------------------------------------------------------+

Components are service routines of the Natural nucleus, Natural add-on products or other Software AG products (for example, Adabas) that cause TCB switches when executing, for example, Adabas calls or external `CALLNAT` requests. The report contains the following:

- The code of the product (for example, `NAT` for Natural) to which the component belongs,

- The name and description of the component,

- The number of switches per component,

- The percentage of the component switches,

- The indicator `P` set for component switches that can be influenced by a parameter, and

- The total number of component switches.

#### PF Keys Available on the zIIP Component Switch Statistics Screen

`ENTER` or PF5 | Updates the statistics data.
PF4 | Opens a window where you can specify selection criteria (product range and component switches that can be influenced by a parameter) for the zIIP Component Switch Statistics report.
PF7 | Scrolls backward one page (in a long list) or switches to the zIIP Processing Information report. (Only applies on the first page of a list and if `PRINT ALL` is used.)
PF8 | Scrolls forward one page (in a long list) or switches to the zIIP Processing Information report. (Only applies on the last page of a list and if `PRINT ALL` is used.)
PF9 | Toggles between the two displays described for `SORTPRODUCT` and `SORTSWITCHES` in Sort Options for zIIP Component Switch Statistics.
PF10 | Toggles between the two displays described for `SORTDESC` and `SORTNAME` in Sort Options for zIIP Component Switch Statistics.
PF11 | Toggles between the two displays described for `SORTDESC` and `SORTSWITCHES` in Sort Options for zIIP Component Switch Statistics.

## ZIIP Menu for Report Output Options

In online mode, you can use a menu to set the `ZIIP` report options according to your requirements.

To display the ZIIP menu

- At any command prompt, enter the following:

      ZIIP MENU

  The Main Menu of the `ZIIP` command is displayed, in which you can select the required subfunction and option(s) described in Syntax Element Description.

## User Exit for ZIIP PRINT

You can use the user exit routine `ZIIPUX01` to specify the default settings for the `PRINT` options of the `ZIIP` system command. The source is provided as subprogram `ZIIPUS01` in the Natural system library `SYSEXT`. Copy the cataloged object of `ZIIPUX01` to the Natural system library `SYSLIB`, `SYSLIBS` or `SYSTEM`. For details, see the subprogram `ZIIPUS01` in the system library `SYSEXT`.

## Application Programming Interface (API) for ZIIP Functions

You can use the Natural application programming interface `USR8204N` to perform all functions of the `ZIIP` system command. For details, see the text object `USR8204T` and the program `USR8204P` in the Natural system library `SYSEXT`.

### On this page

- Syntax of ziip-subfunction-and-option
- Syntax Element Description
- zIIP Reports
- ZIIP Menu for Report Output Options
- User Exit for ZIIP PRINT
- Application Programming Interface (API) for ZIIP Functions