IMS Version 9

BPE Commands

BPE Command Syntax and Invocation

BPE supports two command formats: a verb only format, and a verb-resourcetype format.

The verb only format consists of a verb, followed by zero or more keyword-value pairs, with the values enclosed in parentheses.

Read syntax diagramSkip visual syntax diagramBPE Verb Only Command Syntax

         .--------------------------.
         V                          |
>>-verb----+----------------------+-+--------------------------><
           |          .-,-----.   |
           |          V       |   |
           '-keyword(---value-+-)-'

The verb-resourcetype format consists of a verb, a resource type, and zero or more keyword value pairs.

Read syntax diagramSkip visual syntax diagramBPE Verb-Resource Type Command Syntax

                       .--------------------------.
                       V                          |
>>-verb--resourcetype----+----------------------+-+------------><
                         |          .-,-----.   |
                         |          V       |   |
                         '-keyword(---value-+-)-'

verb
A command verb representing an action. Some verb examples are DISPLAY, UPDATE, and REFRESH.
resourcetype
The type of resource that is operated on by the verb. Some resource examples are TRACETABLE and USEREXIT.
keyword(value)
A set of zero or more keywords and values that represent attributes, filters, or other modifiers that apply to the command. For example, NAME() to identify the specific resource(s) or LEVEL() to specify a trace level.

BPE Command Invocation

You can only invoke BPE commands through the MVS MODIFY command. The following diagram illustrates the general syntax for entering commands through the modify interface.

Read syntax diagramSkip visual syntax diagramBPE Command Invocation

>>-F--jobname,command------------------------------------------><

F
The MVS modify command.
jobname
The jobname of the address space to which the command is directed.
command
The command being issued.

BPE Wildcard Character Support

Some parameters on BPE commands support wildcard characters for pattern matching. For such parameters, you can use the following wildcard characters:

*
Matches zero or more characters
%
Matches exactly one character

The following examples illustrate some uses of wildcard characters.

BE*
Matches any string beginning with "BE", of any length. For instance: BE, BEE, BEEBLEBROX.
%%S
Matches any three-character string ending with an "S". For instance: IMS, CQS.
R*S*T%R
Matches any string beginning and ending wtih "R", having an "S", followed by a "T" in the middle, with any number of intervening characters between the first "R", the "S", and the "T", and exactly one character between the "T" and the final "R". For instance: ROASTER, ROSTER, RESORTER, RESCEPTOR, RSTZR.
*
Matches any string.

Specifying IMS Component Command Parameters

BPE commands enable you to display and update resources that BPE manages. Some resource types are defined and owned by BPE itself. These resource types are known as "system resource types." Commands that specify system resource types can be issued to any IMS component running in a BPE environment. For example, BPE defines several BPE system trace table types like DISP, STG, and CBS. These trace tables exist in every BPE address space. Commands to display and update these trace table types can be issued to any BPE address space.

Other resource types are defined and owned by the IMS component that is using BPE services. These resource types are known as "component resource types" or "user-product resource types." Commands that specify component resource types can only be issued to the IMS component that defines those types. For example, CQS defines several CQS-specific trace tables such as STR, CQS, and INTF. Commands to display and update these trace table types can be issued only to CQS address spaces.

BPE commands also provide the ability to restrict the resource types upon which a command operates to either those owned by BPE, or to those owned by the IMS component of the address space to which the command is issued. This is done through the OWNER keyword on commands that support OWNER. Use OWNER(BPE) to restrict the command operation to resource types that BPE owns and defines (system resource types). Use OWNER(component_type) to restrict the command operation to resource types that the IMS component address defines and owns (component resource types). Table 205 shows the valid values for the OWNER parameter, and the address space types to which they apply:

Table 205. Valid Values for OWNER Parameter
OWNER Address Space Type
BPE Any IMS component running in a BPE address space
CQS Common Queue Server
OM Operations Manager
RM Resource Manager
SCI Structured Call Interface

BPE TRACETABLE Commands

The TRACETABLE resource type refers to the internal BPE-managed trace tables defined either by BPE (for example: DISP, CBS, STG, LATC), or by the IMS component using BPE (for example: CQS, OM, RM, SCI). Two command verbs operate on the TRACETABLE resource type:

DISPLAY
Display trace level and number of trace table pages of specified trace tables.
UPDATE
Update trace level attribute of specified trace tables.

Format of DISPLAY TRACETABLE Command

Use this command to display the current attribute settings for the requested trace tables.

Read syntax diagramSkip visual syntax diagram>>-+-DISPLAY-+--+-TRACETABLE-+---------------------------------->
   '-DIS-----'  '-TRTAB------'

         .-,---------------------.
         V                       |
>--NAME(---+-trace_table_name--+-+-)--+------------------+-----><
           '-trace_table_name*-'      '-OWNER(-+-BPE-+-)-'
                                               +-CQS-+
                                               +-OM--+
                                               +-RM--+
                                               '-SCI-'

Usage of DISPLAY TRACETABLE Command

DISPLAY | DIS
A required parameter, which specifies that the action against the specified resource is to display attributes of the resource.
TRACETABLE | TRTAB
A required parameter, which specifies that the resource type being acted upon is a BPE-managed trace table.
NAME(trace_table_name)
A required parameter, which specifies the name of the trace table type or types about which you want attributes displayed. You can specify a single trace table name or a list of trace table names separated by commas. Trace table names can contain wildcard characters. See BPE Wildcard Character Support for more information about using wildcard characters. Trace table names can be BPE-defined trace tables or IMS component-defined trace tables.

You can display BPE-defined trace tables for any IMS component address space that is using BPE. These BPE-defined trace table types are available:

AWE
Asynchronous work element (AWE) trace table
CBS
Control block services trace table
CMD
Command trace table
DISP
Dispatcher trace table
HASH
Hash trace table
ERR
BPE Error trace table
LATC
Latch trace table
MISC
Miscellaneous trace table that is used only by IMS Service for trap traces
SSRV
System services trace table
STG
Storage service trace table
USRX
User exit routine trace table

You can display CQS-defined trace tables only for CQS address spaces. These CQS-defined trace table types are available:

CQS
CQS trace table
ERR
CQS error trace table
INTF
CQS interface trace table
STR
CQS structure trace table

You can display OM-defined trace tables only for OM address spaces. These OM-defined trace table types are available:

CSL
Common Service Layer (CSL) trace table
ERR
OM error trace table
OM
Operations Manager (OM) processes trace table
PLEX
IMSplex trace table for OM processing for a specific IMSplex

You can display RM-defined trace tables only for RM address spaces. These RM-defined trace table types are available:

CSL
Common Service Layer (CSL) trace table
ERR
RM error trace table
PLEX
IMSplex trace table for RM processing for a specific IMSplex
RM
Resource Manager (RM) processes trace table

You can display SCI-defined trace tables only for SCI address spaces. These SCI-defined trace table types are available:

CSL
Common Service Layer (CSL) trace table
ERPL
SCI Error Parameter List trace table
ERR
SCI error trace table
INTF
SCI interface trace table
INTP
SCI interface parameter trace table
PLEX
IMSplex trace table for SCI processing for a specific IMSplex
SCI
Structured Call Interface (SCI) processes trace table
OWNER(BPE | CQS | OM | RM | SCI)
An optional parameter that specifies the owner of the trace table type or types about which you want attributes displayed. You can specify one of the following values:
BPE
For all IMS components that are running in a BPE address space.
CQS
For CQS address spaces only
OM
For OM address spaces only
RM
For RM address spaces only
SCI
For SCI address spaces only

The OWNER parameter acts as a filter to help you select which trace tables you want to display. For example, you could specify NAME(*) OWNER(CQS) to display all of the CQS-defined trace table types (CQS, ERR, STR, and INTF) in a CQS address space. You could specify NAME(*) OWNER(BPE) to display all of the BPE-defined trace table types in any BPE-managed address space. If OWNER is omitted, then both BPE and component trace tables might be displayed (depending on the tables specified on NAME).

DISPLAY TRACETABLE Command Output

The DISPLAY TRACETABLE command output consists of a header line, one line per selected trace table, and one message BPE0032I line indicating that the command has completed. Here is an example.

BPE0030I TABLE  OWNER  LEVEL  #PAGES
BPE0000I DISP   BPE    HIGH       12
BPE0000I STR    CQS    MEDIUM      8
BPE0032I DISPLAY TRACETABLE COMMAND COMPLETED

These columns are in the DISPLAY TRACETABLE output:

TABLE
Specifies the name of the trace table type about which information is being displayed on the current row. Either BPE or the product using BPE owns this trace table.
OWNER
Specifies the IMS component that owns the trace table. BPE-owned trace tables are system trace tables, and exist in all IMS component address spaces that use BPE. Trace tables that are specific to an IMS component show the 1- to 4-character component identifier in this column.
LEVEL
Specifies the current level setting of the trace table. A trace table's level determines the volume of trace data collected. These levels are possible:
NONE
No tracing is being done into the table.
ERROR
Only traces for error or exception conditions are being made into the table.
LOW
Only major event trace entries are made into the table.
MEDIUM
Major event trace entries and some minor event trace entries are made into the table.
HIGH
All trace entries are made into the table.
INACTV
The trace table is inactive and cannot be used. This status occurs only when BPE was unable to get any storage for the trace table. No tracing will be done for the indicated table type, and you cannot change the level for the trace table with the UPDATE TRACETABLE command. You must restart the address space in order to use the trace table again.
#PAGES
Specifies the number of 4K (4096 byte) pages allocated for the trace table type.

Command Example 1

Display the status of the BPE dispatcher trace table (DISP).

Command:

   F CQS1,DISPLAY TRACETABLE NAME(DISP)

Output:

   BPE0030I TABLE  OWNER  LEVEL  #PAGES
   BPE0000I DISP   BPE    HIGH       12
   BPE0032I DISPLAY TRACETABLE COMMAND COMPLETED

Command Example 2

Display the status of all CQS traces.

Command:

   F CQS1,DIS TRTAB NAME(*) OWNER(CQS)

Output:

   BPE0030I TABLE  OWNER  LEVEL  #PAGES
   BPE0000I CQS    CQS    MEDIUM      4
   BPE0000I ERR    CQS    HIGH        4
   BPE0000I INTF   CQS    LOW         8
   BPE0000I STR    CQS    HIGH        8
   BPE0032I DISPLAY TRACETABLE COMMAND COMPLETED

Command Example 3

Display the status of all traces in an SCI address space.

Command:

   F SCI,DIS TRTAB NAME(*)

Output:

  BPE0030I TABLE  OWNER  LEVEL  #PAGES
  BPE0000I AWE    BPE    HIGH       6
  BPE0000I CBS    BPE    HIGH       6
  BPE0000I CMD    BPE    HIGH       2
  BPE0000I CSL    SCI    HIGH       8
  BPE0000I DISP   BPE    HIGH       8
  BPE0000I ERPL   SCI    HIGH       8
  BPE0000I ERR    BPE    HIGH       2
  BPE0000I ERR    SCI    HIGH       4
  BPE0000I HASH   BPE    HIGH       8
  BPE0000I INTF   SCI    HIGH       8
  BPE0000I INTP   SCI    HIGH       16
  BPE0000I LATC   BPE    HIGH       8
  BPE0000I MISC   BPE    HIGH       1
  BPE0000I PLEX   SCI    HIGH       8
  BPE0000I SCI    SCI    HIGH       8
  BPE0000I SSRV   BPE    HIGH       4
  BPE0000I STG    BPE    HIGH       8
  BPE0000I USRX   BPE    HIGH       4
  BPE0032I DISPLAY TRACETABLE COMMAND COMPLETED

Command Example 4

Display the status of all OM traces.

Command:

   F OM,DIS TRTAB NAME(*) OWNER(OM)

Output:

  BPE0030I TABLE  OWNER  LEVEL  #PAGES
  BPE0000I CSL    OM     HIGH       4
  BPE0000I ERR    OM     HIGH       4
  BPE0000I OM     OM     HIGH       4
  BPE0000I PLEX   OM     HIGH       8
  BPE0032I DISPLAY TRACETABLE COMMAND COMPLETED

Command Example 5

Display the status of the PLEX trace and all traces beginning with "C" in the RM address space.

Command:

   F RM,DIS TRTAB NAME(PLEX,C*)

Output:

  BPE0030I TABLE  OWNER  LEVEL  #PAGES
  BPE0000I CBS    BPE    HIGH       6
  BPE0000I CMD    BPE    HIGH       2
  BPE0000I CSL    RM     HIGH       4
  BPE0000I PLEX   RM     HIGH       8
  BPE0032I DISPLAY TRACETABLE COMMAND COMPLETED

Format of UPDATE TRACETABLE Command

Use this command to change the trace level setting for the requested trace tables.

Read syntax diagramSkip visual syntax diagram>>-+-UPDATE-+--+-TRACETABLE-+----------------------------------->
   '-UPD----'  '-TRTAB------'

         .-,---------------------.
         V                       |
>--NAME(---+-trace_table_name--+-+-)--+------------------+------>
           '-trace_table_name*-'      '-OWNER(-+-BPE-+-)-'
                                               +-CQS-+
                                               +-OM--+
                                               +-RM--+
                                               '-SCI-'

>--+---------------------+-------------------------------------><
   '-LEVEL(-+-NONE---+-)-'
            +-ERROR--+
            +-LOW----+
            +-MEDIUM-+
            '-HIGH---'

Usage of UPDATE TRACETABLE Command

UPDATE | UPD
A required parameter, which specifies that the action against the trace table is to update its attributes.
TRACETABLE | TRTAB
A required parameter, which specifies that the resource type being acted upon is a BPE-managed trace table.
NAME(trace_table_name)
A required parameter, which specifies the name of the trace table type or types that you want to update. You can specify a single trace table name or a list of trace table names separated by commas. Trace table names can contain wildcard characters. See BPE Wildcard Character Support for more information about using wildcard characters. Trace table names can be BPE-defined trace tables or IMS component-defined trace tables.

You can update BPE-defined trace tables for any IMS component address space that is using BPE. These BPE-defined trace table types are available:

AWE
Asynchronous work element (AWE) trace table
CBS
Control block services trace table
CMD
Command trace table
DISP
Dispatcher trace table
ERR
BPE Error trace table
HASH
Hash trace table
LATC
Latch trace table
MISC
Miscellaneous trace table that is used only by IMS Service for trap traces
SSRV
System services trace table
STG
Storage service trace table
USRX
User exit routine trace table

You can update CQS-defined trace tables only for CQS address spaces. These CQS-defined trace table types are available:

CQS
CQS trace table
ERR
CQS error trace table
INTF
CQS interface trace table
STR
CQS structure trace table

You can update OM-defined trace tables only for OM address spaces. These OM-defined trace table types are available:

CSL
Common Service Layer (CSL) trace table
ERR
OM error trace table
OM
Operations Manager (OM) processes trace table
PLEX
IMSplex trace table for OM processing for a specific IMSplex

You can update RM-defined trace tables only for RM address spaces. These RM-defined trace table types are available:

CSL
Common Service Layer (CSL) trace table
ERR
RM error trace table
PLEX
IMSplex trace table for RM processing for a specific IMSplex
RM
Resource Manager (RM) processes trace table

You can update SCI-defined trace tables only for SCI address spaces. These SCI-defined trace table types are available:

CSL
Common Service Layer (CSL) trace table
ERPL
SCI Error Parameter List trace table
ERR
SCI error trace table
INTF
SCI interface trace table
INTP
SCI interface parameter trace table
PLEX
IMSplex trace table for SCI processing for a specific IMSplex
SCI
Structured Call Interface (SCI) processes trace table
OWNER(BPE | CQS | OM | RM | SCI)
An optional parameter that specifies the owner of the trace table type or types that you want to update. You can specify one of the following values:
BPE
For all IMS components that are running in a BPE address space
CQS
For CQS address spaces only
OM
For OM address spaces only
RM
For RM address spaces only
SCI
For SCI address spaces only

The OWNER parameter acts as a filter to help you select which trace tables you want to update. For example, you could specify NAME(*) OWNER(CQS) to update all of the CQS-defined trace table types (CQS, ERR, STR, and INTF) in a CQS address space. You could specify NAME(*) OWNER(BPE) to update all of the BPE-defined trace table types in any BPE-managed address space. If OWNER is omitted, then both BPE and component trace tables might be updated (depending on the tables specified on NAME).

LEVEL(level)
An optional parameter that sets the new tracing level for the specified trace tables. If LEVEL is omitted, the level of the specified trace tables is not changed. These levels are possible:
NONE
No tracing is being done into the table.
ERROR
Only traces for error or exception conditions are being made into the table.
LOW
Only major event trace entries are made into the table.
MEDIUM
Major event trace entries and some minor event trace entries are made into the table.
HIGH
All trace entries are made into the table.

Important: You cannot change the level for the trace table type ERR. BPE forces the level to HIGH to ensure that error diagnostics are captured. Any level that you specify for the ERR trace table is ignored.

UPDATE TRACETABLE Command Output

The UPDATE TRACETABLE command output consists of message BPE0032I indicating that the command has completed:

   BPE0032I UPDATE TRACETABLE COMMAND COMPLETED

Command Example 1

Update the level of the BPE dispatcher trace table (DISP) to HIGH.

Command:

   F CQS1,UPDATE TRACETABLE NAME(DISP) LEVEL(HIGH)

Output:

   BPE0032I UPDATE TRACETABLE COMMAND COMPLETED

Command Example 2

Update the level of all SCI trace tables to MEDIUM.

Important: You cannot change the level for the trace table type ERR -- even when using a wildcard character to select all tables with a given owner, as in this example. BPE forces the level to HIGH to ensure that error diagnostics are captured.

Command:

    F SCI,UPD TRTAB NAME(*) OWNER(SCI) LEVEL(MEDIUM)

Output:

   BPE0032I UPDATE TRACETABLE COMMAND COMPLETED

BPE DISPLAY VERSION Command

Use this command to display both the version of the IMS component that is using BPE, and the version of the BPE in use.

Format of DISPLAY VERSION Command

Read syntax diagramSkip visual syntax diagram>>-+-DISPLAY-+--+-VERSION-+------------------------------------><
   '-DIS-----'  '-VER-----'

Usage of DISPLAY VERSION Command

DISPLAY | DIS
A required parameter, which specifies that the action against the specified resource is to display attributes of the resource.
VERSION | VER
A required parameter, which specifies that the resource types being acted upon are the version number of the IMS component and the BPE in the current address space.

DISPLAY VERSION Command Output

The DISPLAY VERSION command output consists of a single display output line in the format BPE00001 comp VERSION=cv.cr.cp BPE VERSION=bv.br.bp.

Command Example 1

Display the version of a CQS address space.

Command:

   F CQS1,DISPLAY VERSION

Output:

BPE00001 CQS VERSION = 1.3.0  BPE VERSION = 1.4.0

Command Example 2

Display the version of an RM address space.

Command:

   F RM1,DISPLAY VERSION

Output:

BPE00001 RM VERSION = 1.1.0  BPE VERSION = 1.4.0

BPE USEREXIT Commands

Note:  Throughout this section, the term "user exit routine" means "user-supplied exit routine."

The USEREXIT resource type refers to the user exit types defined to and managed by either BPE or the IMS component using BPE (for example, CQS).

DISPLAY
Display attributes of specified user exit types.
REFRESH
Load new copies of the user exit modules for specified user exit types.

Format of DISPLAY USEREXIT Command

Use this command to display attributes for all modules associated with the specified user exit types.

Read syntax diagramSkip visual syntax diagram>>-+-DISPLAY-+--+-USEREXIT-+------------------------------------>
   '-DIS-----'  '-USRX-----'

         .-,------------------------.
         V                          |
>--NAME(---+-user_exit_type_name--+-+-)--+------------------+--->
           '-user_exit_type_name*-'      '-OWNER(-+-BPE-+-)-'
                                                  +-CQS-+
                                                  +-OM--+
                                                  +-RM--+
                                                  '-SCI-'

>--+-------------------------+---------------------------------><
   |       .-,-----------.   |
   |       V             |   |
   '-SHOW(---+-ABENDS--+-+-)-'
             +-ABLIM---+
             +-ACTIVE--+
             +-CALLS---+
             +-ENTRYPT-+
             +-ETIME---+
             +-LOADPT--+
             +-OWNER---+
             +-RTIME---+
             +-SIZE----+
             '-TEXT----'

Usage of DISPLAY USEREXIT Command

DISPLAY | DIS
A required parameter, which specifies that the action against the specified resource(s) is to display attributes of the resource(s).
USEREXIT | USRX
A required parameter, which specifies that the resource type being acted upon is a BPE-managed user exit type.
NAME(user_exit_type_name)
A required parameter, which specifies the name of the user exit type or types about which you want attributes displayed. You can specify a single user exit type name or a list of user exit type names separated by commas. User exit type names can contain wildcard characters.

Related Reading:

For more information about using wildcards, see BPE Wildcard Character Support.

Important:  The name(s) specified in this parameter are the name(s) of user exit types, not the name(s) of individual user exit modules.

BPE and each address space that can use BPE have different user exit types. BPE's user exit types, as specified by OWNER(BPE), include the following:

INITTERM
Initialization-Termination user exit
STATS
BPE system functions statistics user exit

User exit types are defined in all CQS address spaces, as specified by OWNER(CQS), and include the following:

CLNTCONN
Client Connection user exit
INITTERM
Initialization-Termination user exit
OVERFLOW
Queue Overflow user exit
STRSTAT
Structure statistics user exit
STREVENT
Structure event user exit

User exit types are defined in all OM address spaces, as specified by OWNER(OM), and include the following:

CLNTCONN
Client Connection command registration and deregistration user exit
INITTERM
Initialization-Termination user exit
INPUT
Command input user exit
OUTPUT
Output user exit
SECURITY
Security checking user exit

User exit types are defined in all RM address spaces, as specified by OWNER(RM), and include the following:

CLNTCONN
Client Connection and Disconnection user exit
INITTERM
Initialization-Termination user exit

User exit types are defined in all SCI address spaces, as specified by OWNER(SCI), and include the following:

CLNTCONN
Client Connection and Disconnection user exit
INITTERM
Initialization-Termination user exit

Related Reading:

OWNER(BPE | CQS | OM | RM | SCI)
An optional parameter that specifies the owner of the user exit type or types about which you want attributes displayed. You can specify one of the following values:
BPE
For all IMS components that are running in a BPE address space
CQS
For CQS address spaces only
OM
For OM address spaces only
RM
For RM address spaces only
SCI
For SCI address spaces only

The OWNER parameter acts as a filter to help you select the user exit types that you want to display. For example, you could specify NAME(*) OWNER(CQS) to display all of the CQS-defined user exit types in a CQS address space. If OWNER is omitted, then both BPE and component user exits can be displayed (depending on the exits specified on NAME).

SHOW(attribute)
An optional parameter that specifies the attributes you want to display about the requested user exits.

When you display information about user exits, each row of display output contains the requested attributes for one user exit module, in columns. Every display for user exits contains the columns labeled EXITTYPE (the type of the exit), and MODULE (the load module name of the exit). Additionally, any of the following attributes can be requested by using the SHOW parameter:

ABENDS
The number of abends that have occurred in the user exit module since the last user exit refresh of that module (or since address space initialization if no refreshes have been done). BPE keeps track of the number of abends that have occurred in each user exit module. When this number reaches the number defined on the ABLIM= parameter of the EXITDEF statement for the exit's type, BPE stops calling the module. If the user exit module is refreshed, this count is reset to zero, and BPE calls the module again.

If the abend limit (ABLIM) value is not zero, and if the number of abends is greater than or equal to the abend limit value, then the user exit has reached its abend limit, and is no longer being called by BPE.

The maximum value that can be displayed in this field is 2147483647 (231-1). If the abend count exceeds this value, 2147483647 is displayed.

ABLIM
The abend limit count for the user exit type, as specified on the ABLIM= parameter on the EXITDEF statement for the user exit type in the BPE exit list PROCLIB member. This is the number of times the user exit module is allowed to abend before BPE stops calling the user exit. A value of 0 indicates that there is no abend limit.

The maximum value that can be displayed in this field is 2147483647 (231-1). If the abend limit count exceeds this value, 2147483647 is displayed.

ACTIVE
The number of currently active instances of the user exit. This is a point-in-time number that represents the number of calls to the user exit that have not yet returned.

The maximum value that can be displayed in this field is 999999. If the active count exceeds this value, 999999 is displayed.

CALLS
The number of calls to the user exit since the last user exit refresh.

For performance reasons, serialization is not obtained when BPE collects this number. For an exit type that can run multiple instances in parallel, this number should be considered an approximation only.

The maximum value that can be displayed in this field is 2147483647 (231-1). If the call count exceeds this value, 2147483647 is displayed.

ENTRYPT
The entry point address of the user exit module.
ETIME
The total (cumulative) elapsed time spent in the exit module since it was last refreshed, in milliseconds.

For performance reasons, serialization is not obtained when BPE collects this number. For an exit type that can run multiple instances in parallel, this number should be considered an approximation only.

The maximum value that can be displayed in this field is 2147483647 (231-1). If the elapsed number of milliseconds exceeds this value, 2147483647 is displayed.

LOADPT
The load point address of the user exit module.
OWNER
The IMS component that owns the user exit type. BPE-owned user exit types are system exit types, and exist in all IMS component address spaces that use BPE. User exit types that are specific to the component show the 1- to 4-character component identifier in this column (for example, CQS).
RTIME
The refresh time of the user exit module. This is the local date and time that the user exit module was last refreshed (or initially loaded, if no refreshes have been done). The format of this output field is:
   yyyy-mm-dd hh:mm:ss.th
SIZE
The size of the user exit load module, in bytes (displayed in hexadecimal).
TEXT
27 bytes starting from offset +04 from the module's entry point, translated to EBCDIC, with non-printable characters replaced by periods ( . ). This is a common location for module identification information. If your user exits contain printable identification data at this point in the module, the TEXT option enables that information to be displayed.

If the SHOW parameter is not specified, the default attributes displayed after the EXITTYPE and MODULE are OWNER, ACTIVE, and ABENDS.

The order in which you list the attributes on the SHOW parameter has no effect on the order the attributes are displayed. BPE determines the order of the attribute columns in the display output. This order is as follows:

Important:  It is possible to request so many attributes that the length of the output line is too long to display with a WTO. If this happens, the command is processed, but some lines might be truncated. The maximum line length that BPE displays is 126 characters.

DISPLAY USEREXIT Command Output

The DISPLAY USEREXIT command output consists of a header line, one line per user exit module about which information is being displayed, and one message, BPE0032I line indicating the command has completed. For example, the command

   F CQS1,DISPLAY USEREXIT NAME(INITTERM,STRSTAT)

displays the following:

   BPE0030I EXITTYPE MODULE   OWNER    ACTIVE     ABENDS
   BPE0000I INITTERM MYINIT00 CQS           0          0
   BPE0000I INITTERM ZZZINIT0 CQS           0          0
   BPE0000I STRSTAT  MYSTAT00 CQS           1          2
   BPE0032I DISPLAY USEREXIT COMMAND COMPLETED

The EXITTYPE and MODULE columns are present for all DISPLAY USEREXIT commands, regardless of what is specified on SHOW. When multiple exit modules are listed for a single user exit type, the order in which they are listed is the order in which they are called.

Command Example 1

Display the status of the CQS structure event user exit type:

Command:

   F CQS1,DISPLAY USEREXIT NAME(STREVENT)

Output:

   BPE0030I EXITTYPE MODULE   OWNER    ACTIVE     ABENDS
   BPE0000I STREVENT STREVX00 CQS           1          0
   BPE0000I STREVENT ZZZSTEV0 CQS           0          0
   BPE0032I DISPLAY USEREXIT COMMAND COMPLETED

In this example, there are two structure event exit modules defined that are called for CQS structure events. STREVX00 is called first, followed by ZZZSTEV0.

Command Example 2

Display the number of calls to, the elapsed time spent in, and the abend limit for all CQS user exit types:

Command:

   F CQS1,DIS USRX NAME(*) OWNER(CQS) SHOW(CALLS,ETIME,ABLIM)

Output:

   BPE0030I EXITTYPE MODULE        ABLIM      CALLS      ETIME
   BPE0000I CLNTCONN CLCONX00          0          2         12
   BPE0000I INITTERM MYCQSIT0          0          1          2
   BPE0000I INITTERM OEMCQIT0          0          1        162
   BPE0000I OVERFLOW OVERFL01          5          3          6
   BPE0000I OVERFLOW OVERFL02          5          3         19
   BPE0000I OVERFLOW OVERFL03          5          3          9
   BPE0000I OVERFLOW OVERFL04          5          3      15593
   BPE0000I STREVENT STREVNT0         10        542        628
   BPE0000I STRSTAT  STRSTAT0          1         36       1889
   BPE0000I STRSTAT  STRSTA10          1         36        241
   BPE0032I DIS USRX COMMAND COMPLETED
Command Example 3

Display the entry point, load point, and size of all of the SCI CLNTCONN user exit modules.

Command:

   F SCI,DIS USRX NAME(CLNTCONN) SHOW(SIZE,ENTRYPT,LOADPT)

Output:

   BPE0030I EXITTYPE MODULE    ENTRYPT   LOADPT     SIZE
   BPE0000I CLNTCONN SCCLCN00 8B864D78 8B864D78 00000458
   BPE0000I CLNTCONN SCCLCN10 8BA14200 8BA14200 00001C10
   BPE0000I CLNTCONN SCCLCN20 8BA18EE8 8BA18AF0 00000AB0
   BPE0032I DIS USRX COMMAND COMPLETED
Command Example 4

Display the first part of the module text for all of the BPE user exits in the OM address space.

Command:

   F OM,DIS USRX NAME(*) OWNER(BPE) SHOW(TEXT)

Output:

   BPE0030I EXITTYPE  MODULE   TEXT
   BPE0000I INITTERM  MYINIT00 .MYINIT00+20010615+17:47...
   BPE0000I STATS     HHGSTAT0 .HHGSTAT0+20010615+08:47...
   BPE0032I DIS USRX COMMAND COMPLETED
Command Example 5

Display the refresh time for all of the RM INITTERM modules.

Command:

   F RM,DIS USRX NAME(*) OWNER(RM) SHOW(RTIME)

Output:

   BPE0030I EXITTYPE MODULE   RTIME
   BPE0000I INITTERM RMINITRM 2001-06-15 16:48:22.39
   BPE0032I DIS USRX COMMAND COMPLETED

Refreshing User Exits

The REFRESH USEREXIT command causes BPE to reprocess the user exit PROCLIB members specified in the BPE configuration PROCLIB member and to reload the user exit modules currently listed in the user exit PROCLIB members for the types specified on the command. This command enables you to make updates to your user exits without stopping and restarting the address space.

When you enter the REFRESH USEREXIT command, BPE performs the following processing:

BPE loads the new copies of the user exit modules before deleting the old modules. If an error occurs during this process (for instance, a module could not be loaded or BPE internal control block storage could not be obtained), BPE will fail the command and leave the old copies of the user exits in effect. All modules of the specified user exit type(s) must be loaded successfully for the command to complete successfully.

When a user exit module is refreshed, its abend count is reset to zero. This means that a user exit module that had reached its abend limit (specified by the ABLIM parameter on the EXITDEF statement) and was no longer being called by BPE is again called.

Important:  If you changed the ABLIM parameter for a user exit in the PROCLIB member, the new value of ABLIM takes effect after the refresh command.

Related Reading:  See IMS Version 9: Base Primitive Environment Guide and Reference for more information about the EXITDEF statement.

Considerations for Refreshing User Exits

Format of REFRESH USEREXIT Command

Read syntax diagramSkip visual syntax diagram>>-+-REFRESH-+--+-USEREXIT-+------------------------------------>
   '-REF-----'  '-USRX-----'

         .-,------------------------.
         V                          |
>--NAME(---+-user_exit_type_name--+-+-)--+------------------+--><
           '-user_exit_type_name*-'      '-OWNER(-+-BPE-+-)-'
                                                  +-CQS-+
                                                  +-OM--+
                                                  +-RM--+
                                                  '-SCI-'

Usage of REFRESH USEREXIT Command

REFRESH | REF
A required parameter, which specifies that the action against the specified resource(s) is to refresh the resource(s).
USEREXIT | USRX
A required parameter, which specifies that the resource type being acted upon is a BPE-managed user exit type.
NAME(user_exit_type_name)
A required parameter, which specifies the name of the user exit type or types that you want to refresh. You can specify a single user exit type name or a list of user exit type names separated by commas. User exit type names can contain wildcard characters.

Related Reading:

For more information about using wildcard characters, see BPE Wildcard Character Support.

Important:  The names specified in this parameter are the name(s) of user exit types, not the names of individual user exit modules.

BPE and each address space that can use BPE have different user exit types. BPE's user exit types, as specified by OWNER(BPE), include the following:

INITTERM
Initialization-Termination user exit
STATS
BPE system functions statistics user exit

User exit types are defined in all CQS address spaces, as specified by OWNER(CQS), and include the following:

CLNTCONN
Client Connection user exit
INITTERM
Initialization-Termination user exit
OVERFLOW
Queue Overflow user exit
STRSTAT
Structure statistics user exit
STREVENT
Structure event user exit

User exit types are defined in all OM address spaces, as specified by OWNER(OM), and include the following:

CLNTCONN
Client Connection command registration and deregistration user exit
INITTERM
Initialization-Termination user exit
INPUT
Command input user exit
OUTPUT
Output user exit
SECURITY
Security checking user exit

User exit types are defined in all RM address spaces, as specified by OWNER(RM), and include the following:

CLNTCONN
Client Connection and Disconnection user exit
INITTERM
Initialization-Termination user exit

User exit types are defined in all SCI address spaces, as specified by OWNER(SCI), and include the following:

CLNTCONN
Client Connection and Disconnection user exit
INITTERM
Initialization-Termination user exit

Related Reading:

OWNER(BPE | CQS | OM | RM | SCI)
An optional parameter that specifies the owner of the user exit type or types that you want to refresh. You can specify one of the following values:
BPE
For all IMS components that are running in a BPE address space.
CQS
For CQS address spaces only.
OM
For OM address spaces only.
RM
For RM address spaces only.
SCI
For SCI address spaces only.

The OWNER parameter acts as a filter to help you select the user exit types that you want to refresh. For example, you could specify NAME(*) OWNER(CQS) to refresh all of the CQS-defined user exit types in a CQS address space. If OWNER is omitted, then both BPE and component user exits can be refreshed (depending on the exits specified on NAME).

REFRESH USEREXIT Command Output

The REFRESH USEREXIT command output consists of message, BPE0032I indicating that the command has completed:

   BPE0032I REFRESH USEREXIT COMMAND COMPLETED
Command Example 1

Refresh all user exit modules.

Command:

   F CQS1,REFRESH USEREXIT NAME(*)

Output:

   BPE0032I REFRESH USEREXIT COMMAND COMPLETED
Command Example 2

Refresh all user exit modules for the OM command input and output exit types.

Command:

   F OM,REF USRX NAME(INPUT,OUTPUT)

Output:

   BPE0032I REF USRX COMMAND COMPLETED

Go to the previous page Go to the next page

IBM Confidential

Downloads | Library | Support | Support Policy | Terms of use | Feedback
Copyright: IBM Corporation 1974, 2004 Copyright IBM Corporation 1974, 2004  timestamp Last updated: March, 2004