BPE configuration parameter member of the IMS PROCLIB data set

Use the BPE configuration parameter member of the IMS PROCLIB data set to define BPE execution environment settings such as tracing, language, and statistics time interval settings for an address space that is being started.

You can use the BPE configuration parameter member of the IMS PROCLIB data set to specify parameters for:

Whether trace entries are written to an external data set, and the external data set that trace entries are written to if so (EXTTRACE=)
The language that is used for BPE and IMS component messages (LANG=)
The trace level settings for BPE and IMS component internal trace tables (TRCLEV=)
The name of a BPE exit list member of the IMS PROCLIB data set where configuration information for IMS component user exit routines is stored (EXITMBR=)
The time interval between calls to the BPE statistics exit routines (STATINTV=)
Whether conditional SRB threads run in SRB mode (CONDSRB=)

Specify the member name by coding BPECFG=member_name on the EXEC PARM= statement in the address space startup JCL, as shown in this example:

EXEC CQSINIT0,PARM='BPECFG=BPECFGCQ'

Avoid coding statements in the BPE configuration member that specify definitions for the same resources multiple times. For example, avoid multiple TRCLEV statements for the same trace table type, or multiple EXITMBR statements for the same IMS component type. BPE uses the last statement that it encounters in the member. Any values that are specified on earlier duplicate statements are ignored. Message BPE0017I is issued for each duplicate statement found.

Environments

The BPE configuration parameter member of the IMS PROCLIB data set can be used whenever you are using an IMS address space that uses BPE, such as CQS, DBRC, ODBM, OM, RM, Repository Server (RS), SCI, and IMS Connect.

BPECFG= EXTTRACE syntax

The EXTTRACE parameter defines the external trace data set to IMS.

Usage

If you do not include the COMP keyword, the EXTTRACE statement applies to all address spaces that use the current BPE configuration parameter member (BPECFG=) of the IMS PROCLIB data set and do not have a separate EXTTRACE statement. For example, you can define one EXTTRACE statement for CQS address spaces and another for all other address spaces:

EXTTRACE ( GDGDEF (...) )
EXTTRACE ( GDGDEF (...)  COMP(CQS) )

If you have an EXTTRACE statement that is shared by more than one address space, use dynamic system symbols to make the GDG name unique for each address space. If two or more address spaces use the same GDG name, only one of them can allocate and open the data set at a time. If a BPE address space attempts to allocate a GDG data set that is already in use by another address space, the dynamic allocation fails with a return code 00000004, reason code 02100000, indicating that the data set is allocated by another job. To allow the GDG data set to be used by the second address space, stop the first address space's external tracing. This causes the first address space to deallocate the GDG name so that the second address space can allocate it.

BPECFG= EXTTRACE parameters

BLKSIZE

Specifies the block size for the data set. The maximum allowable decimal value for block size is 32 760.

Recommendation: Although the minimum supported block size is 8340, use a large block size or the maximum block size. Using a large block size is more efficient (multiple records are written per block). In addition, your BPE external trace definitions do not have to be changed if the minimum supported block size is ever increased.

COMP

Specifies the IMS component to which the current EXTTRACE statement applies. Values include:

CQS: Specifies that the current EXTTRACE statement applies only to CQS address spaces.
DBRC: Specifies that the current EXTTRACE statement applies only to DBRC address spaces.
HWS: Specifies that the current EXTTRACE statement applies only to IMS Connect address spaces.
ODBM: Specifies that the current EXTTRACE statement applies only to ODBM address spaces.
OM: Specifies that the current EXTTRACE statement applies only to OM address spaces.
REPO: Specifies that the current EXTTRACE statement applies only to RS address spaces.
RM: Specifies that the current EXTTRACE statement applies only to RM address spaces.
SCI: Specifies that the current EXTTRACE statement applies only to SCI address spaces.

COPYBUFS

Specifies the number of buffers that are used to copy the trace table entries from the BPE tables. IMS copies the data from these buffers into the buffers that are specified by the IOBUFS keyword.

The values for this keyword can be 1 - 64000. The default value is 15.

DATACLAS

Specifies the data class for the data set.

If you specify a value for this parameter, the specified data class must have attributes DSORG=PS and RECFM=VB.

GDGDEF

Specifies the generation data group (GDG) data set for the external trace. For general information about GDGs, see z/OS MVS™ JCL Reference. For specific information about defining GDGs for BPE external tracing, see IMS Version 15.5 System Administration.

DSN

Specifies the GDG data set name. This data set name does not include absolute or relative generation numbers. You can create the data set on DASD or you can specify a system-managed storage (SMS) class to manage the data set.

Any static or dynamic z/OS® system symbol can be specified in the data set name. This includes all static system symbols that you specify by using SYMDEF in an IEASYMxx PARMLIB member. For example, the dynamic system symbol &JOBNAME. can be used to include the job name of the BPE address space in the GDG data set name. Specifying DSN(IMSTESTL.&JOBNAME..GDG) results in a data set name IMSTESTL.SCI1.GDG for the BPE SCI1 address space. For more information about system symbols, see the topic Sharing PARMLIB definitions in z/OS MVS Initialization and Tuning Reference.

In addition to the z/OS system symbols, the BPE-defined symbols that are described in the following table can also be specified in the data set name.

Name of symbol	Length of symbol name	Symbol value	Length of symbol value	Example
&BPEUTYPE.	10	Component type	4 (maximum)	`USRID01.GDG.SCI.USRID01.GDG.SCI`
&BPESNAME.	10	Component system name	8 (maximum)	`USRID01.GDG.CQS1CQS.USRID01.GDG.CQS`

The value of the &BPEUTYPE. symbol is the name of the IMS component that is writing to the external trace data set. Possible values for &BPEUTYPE. are:

CQS: Common Queue Server address space
DBRC: Database Recovery Control address space
HWS: IMS Connect address space
ODBM: Open Database Manager address space
OM: Operations Manager address space
REPO: Repository Server (RS) address space
RM: Resource Manager address space
SCI: Structured Call Interface address space

The value of the &BPESNAME. symbol is the system name that is specified by the IMS component. This system name is appended to the end of most messages that are issued by most IMS components that run in a BPE address space. The system name for each IMS component is as follows:

CQS: For CQS address spaces, the system name is the CQS SSN appended with CQS. For example, a CQS with SSN=CQS1 has a system name of CQS1CQS.
DBRC: For DBRC address spaces, the system name is DBRC appended with the IMSID of the DBRC. For example, a DBRC with an IMSID of IMS1 has a system name of DBRCIMS1.
HWS: IMS Connect address spaces do not have a BPE system name. If you specify &BPESNAME. for an IMS Connect address space, the symbol is replaced with a null value. For example, the data set name USRID01.GDG.$&BPESNAME. resolves to USRID01.GDG.$ for an IMS Connect address space.
ODBM: For ODBM address spaces, the system name is the ODBMNAME, as specified on the CSLDIxxx initialization member of the IMS PROCLIB data set, which is appended with OD. For example, an ODBM with ODBMNAME=ODBM1 has a system name of ODBM1OD.
OM: For OM address spaces, the system name is the OMNAME appended with OM. For example, an OM with OMNAME=OM1 has a system name of OM1OM.
RP: For RS address spaces, the system name is the RSNAME, as specified on the FRPCFG member of the IMS PROCLIB data set, which is appended with RP. For example, an RS with RSNAME=ABC1, has a system name of ABC1RP.
RM: For RM address spaces, the system name is the RMNAME appended with RM. For example, an RM with RMNAME=RM1 has a system name of RM1RM.
SCI: For SCI address spaces, the system name is the SCINAME appended with SCI. For example, an SCI with SCINAME=SCI1 has a system name of SCI1SCI.

You cannot override the data control block (DCB) attributes for the data set. The disposition for the data set is new (DISP=NEW).

IOBUFS

Specifies the number of buffers that IMS uses to copy data into the external trace data sets.

The values for this keyword can be 1 - 10. The default value is 2.

SPACE

Specifies the number of units of space to be allocated for the data set.

SPACEUNIT

Specifies the quantity of the space for the data in blocks (BLK), tracks (TRK), or cylinders (CYL).

AVGREC

Determines the size of the data set allocation. Values are:

U: Use the space quantity that is specified on the SPACE operand.
K: Multiply the space quantity that is specified on the SPACE operand by 1024 (1 KB).
M: Multiply the space quantity that is specified on the SPACE operand by 1 048 576 (1 MB).

STORCLAS

Specifies the storage class for the data set.

UNIT

Specifies the unit or device type for the data set.

VOLSER

Specifies the volume for the data set.

To enable the data set to use extended address volumes (EAVs), specify an EAV volume.

Restriction: EAVs are available only in z/OS V1.12 or later.

BPECFG= LANG syntax

The LANG parameter specifies the language that is used for BPE and IMS component message text. ENU is for US English, which is the only supported language.

BPECFG= TRCLEV syntax

The TRCLEV parameter specifies:

The trace level for a trace table.
Optionally, the number of storage pages that are allocated for the trace table.
Whether entries made to a trace table are written to an external data set.

TRCLEV controls the level of tracing (the amount of detail traced) for each specified trace table type. BPE-managed trace tables are areas in storage where BPE, and the IMS component that uses BPE, can trace diagnostic information about events occurring within the address space.

Usage

BPE-managed trace table entries are written either to memory only, or to both memory and external data sets. IMS writes trace entries to external data sets only if you define the data sets to IMS by using the EXTTRACE parameter.

Some trace table types are defined and owned by BPE itself. These are known as system trace tables, and are present in all IMS component address spaces that use BPE. The IMS component can also define its own trace tables. These are known as component trace tables or user-product trace tables, and are only present in address spaces of the defining IMS component. For example, trace table types that are defined by Common Queue Server (CQS) are only present in a CQS address space.

You can share one BPE configuration parameter member of the IMS PROCLIB data set among several different IMS component address spaces. Any TRCLEV statements you code for system trace tables apply identically to all the address spaces that share the member. TRCLEV statements for a particular IMS component trace table are processed only by address spaces running that component. For example, you could have a BPE configuration parameter member of the IMS PROCLIB data set containing TRCLEV statements for BPE, CQS, and Resource Manager (RM) trace table types. When you start a CQS address space, only the BPE and CQS TRCLEV statements are processed. When you start an RM address space, only the BPE and RM TRCLEV statements are processed.

BPECFG= TRCLEV parameters

type

Specifies the type of trace table. A trace table's type refers to the events that are traced into that table. For example, the BPE DISP trace table contains entries that are related to events in the BPE dispatcher.

Specifying an asterisk (*) as the type sets the default trace level (and optionally, the default number of pages per trace table) for all trace table types. If you use an asterisk (*) type, make sure that it is the first TRCLEV statement in your member. You can then code additional TRCLEV statements for specific trace table types to selectively override the defaults.

Recommendation: Code a TRCLEV statement with a type of asterisk (*), specifying a level of at least LOW as your first TRCLEV statement for trace table types. This ensures that at least some tracing is done for all trace tables. Specifying a TRCLEV of asterisk (*) also ensures that any new trace table types that are activated in the future are turned on in your system, even if you have not modified your BPE configuration parameter member to explicitly add a TRCLEV statement.

Trace table types that require explicit commands are not processed if an asterisk (*) is specified. To configure trace table types that require explicit commands, include a separate TRCLEV statement that explicitly identifies the table. For example: TRCLEV=(RCTR,MEDIUM,HWS).

The trace table types for each IMS component supported by BPE are shown below.

BPE trace table types

BPE provides a set of trace table types for tracing processing within BPE functions. These BPE trace table types are present in all IMS component address spaces. TRCLEV statements specifying a component of BPE are processed for all IMS component address space types.

*: Specifying an asterisk (*) sets the default trace level (and, optionally, the default number of pages per trace table) for all BPE-defined trace table types, except for those requiring explicit commands.
AWE: The asynchronous work element (AWE) services trace table shows details of AWE server creation and deletion and AWE processing requests. The default number of pages for this table is 6.
CBS: The control block services trace table traces requests for control block storage. The default number of pages for this table is 6.
CMD: The command trace table traces the first 48 characters of each command that is processed by BPE. The default number of pages for this table is 2.
DISP: The dispatcher trace table traces BPE dispatcher activity. The default number of pages for this table is 8.
ERR: The error trace table traces error events within a BPE address space. The default number of pages for this table is 2.
Restriction: You cannot set the level for the ERR trace table. 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. You can, however, specify the number of pages for the ERR trace table on the TRCLEV statement.
ERRV: This table contains variable-length BPE error entries that occur within the BPE address space. The default number of pages for this table is 8.
HASH: The hash trace table traces events that are related to BPE hash table services. Currently, only OM, RM, and SCI address spaces request hash table services. For address spaces that do not use the BPE hash table services, this TRCLEV statement is ignored. The default number of pages for this table is 8.
LATC: The latch trace table traces BPE latch management (serialization) activity. The default number of pages for this table is 8.
SSRV: The system services trace table traces general BPE system service calls. The default number of pages for this table is 4.
STG: The storage service trace table traces storage service requests. The default number of pages for this table is 8.
USRX: The user exit routine trace table traces activity that is related to exit routines (for example, loads, calls, or abends). The default number of pages for this table is 4.

CQS trace table types

CQS provides a set of trace table types for tracing processing within the CQS address space. These CQS trace table types are present only in a CQS address space. TRCLEV statements specifying a component of CQS are ignored for any other address space type.

*: Specifying an asterisk (*) sets the default trace level (and, optionally, the default number of pages per trace table) for all CQS-defined trace table types, except for those requiring explicit commands.
CQS: The CQS trace table traces general activity that is not related to a specific structure. The default number of pages for this table is 4.
ERR: The error trace table traces error events within a CQS address space. The default number of pages for this table is 4.
Restriction: You cannot set the level for the ERR trace table. 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. You can, however, specify the number of pages for the ERR trace table on the TRCLEV statement.
INTF: The interface trace table traces activity in the interface between a CQS and its client. The default number of pages for this table is 8.
OFLW: The overflow event trace table includes activity that is related to CQS structure overflow events. CQS defines one OFLW trace table for each structure pair that is defined to CQS. Trace entries in this table are 64 bytes long. The default number of pages for this table is 12.
SEVT: The structure event trace table includes activity that is related to CQS structure events. CQS defines one SEVT trace table for each structure pair that is defined to CQS. Trace entries in this table are 64 bytes long. The default number of pages for this table is 12.
STR: The client event trace table includes CQS client activity events. CQS defines one STR trace table for each structure pair that is defined to CQS. The default number of pages for this table is 8.

DBRC trace table types

A DBRC address space that is using the Base Primitive Environment defines the following values for DBRC-owned trace tables:

*: By specifying an asterisk (*), you can set the default trace level (and optionally, the default number of pages per trace table) for all DBRC-defined trace table types, except for those requiring explicit commands.
ERR: This table is used to trace errors that occur within the DBRC address space. The default number of pages for this table is 2.
Restriction: You cannot set the level for the ERR trace table. 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. You can, however, specify the number of pages for the ERR trace table on the TRCLEV statement.
GRPS: This table is used for DBRC group services message and notification tracing. The default number of pages for this table is 8.
MODF: This table is used for DBRC module flow tracing. The default number of pages for this table is 8.
RQST: This table is used for general DBRC request processing. The default number of pages for this table is 8.

IMS Connect trace table types

IMS Connect defines its own trace tables by using a set of trace table types for tracing processing within IMS Connect functions. These tables are known as component trace tables or user-product trace tables. You can code the following values for IMS Connect-defined trace tables:

*: Specifying an asterisk (*) sets the default trace level (and optionally, the default number of pages per trace table) for all IMS Connect-defined trace table types, except for those requiring explicit commands.
ADPT: Adapter trace table.
CMDT: The command trace table traces IMS Connect command activity. The default number of pages for this table is 2.
CPDR: CICSPORT driver trace table.
CPRT: CICSPORT communication trace table.
ENVT: The interface trace table traces activity in the interface between an IMS Connect and its client. The default number of pages for this table is 2.
ERRV: This table contains variable-length IMS Connect error entries that occur within the BPE address space.
GSVC: General service trace table.
HWSI: The IMS Connect to OTMA driver trace table traces communication activity between IMS Connect and OTMA drivers. The default number of pages for this table is 2.
HWSN: The IMS Connect to local option driver trace table traces communication activity and event between local option driver and IMS Connect. The default number of pages for this table is 2.
HWSO: The IMSplex driver (IPDC) trace table traces communication activity and events between the IMSplex driver and IMS Connect. The default number of pages for this table is 2.
HWSW: The IMS Connect to TCP/IP driver trace table traces communication activity and events between TCP/IP drivers and IMS Connect. The default number of pages for this table is 2.
ICDR: IMS Connect to IMS Connect driver trace table.
ICNC: IMS Connect to IMS Connect communication trace table.
ISCC: ISC communication trace table.
ISDR: ISC driver trace table.
LEPS: Language Environment® (LE) preinitialization services trace table.
MSCC: MSC communication trace table.
MSDR: MSC driver trace table.
ODBM: ODBM communication trace table.
ODDR: ODBM driver trace table.
OMDR: The IMSplex driver (IPDC) trace table traces communication protocol activity (SCI calls). The default number of pages for this table is 2.
OSDR: ODBM socket driver trace table.
OSOC: ODBM socket communication trace table.
OTMA: The OTMA communication driver trace table traces internal communication protocol activity (z/OS cross-system coupling facility calls). The default number of pages for this table is 2.
PCDR: The local option driver trace table traces local option communication protocol activity. The default number of pages for this table is 2.
PCIF: PC interface trace table.
RCDR: RMTCICS driver trace table.
RCIC: RMTCICS communication trace table.
RCTR: The Recorder trace table is used to reroute variable-length recorder trace data to the BPE external trace data set. When the trace level for a Recorder trace table is set to LEVEL(MEDIUM), trace records are written when data is sent to or received from a user message exit. When the trace level is set to LEVEL(HIGH), records are also written each time IMS Connect sends or receives a TCP/IP message or an OTMA message. The Recorder trace table requires explicit commands.
RRSI: RRS interface trace table.
TCPI: The TCP/IP communication driver trace table traces communication protocol activity (TCP/IP calls). The default number of pages for this table is 2.

ODBM trace table types

An ODBM address space that is using the Base Primitive Environment defines the following values for ODBM-owned trace tables:

*: Specifying an asterisk (*) sets the default trace level (and, optionally, the default number of pages per trace table) for all ODBM-defined trace table types, except for those requiring explicit commands.
CSL: The Common Service Layer (CSL) trace table is used for routines that are common to all CSL managers. The default number of pages for this table is 4.
ERR: This table is used to trace errors that occur within the ODBM address space. The default number of pages for this table is 4.
Restriction: You cannot set the level for the ERR trace table. 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. You can, however, specify the number of pages for the ERR trace table on the TRCLEV statement.
ODBM: This table is used for general ODBM processing. The default number of pages for this table is 4.
PLEX: This table is used for ODBM processing for a specific IMSplex. The default number of pages for this table is 8.

OM trace table types

OM provides a set of trace table types for tracing processing within the OM address space. These OM trace table types are present only in an OM address space. TRCLEV statements specifying a component of OM are ignored for any other address space type.

*: Specifying an asterisk (*) sets the default trace level (and, optionally, the default number of pages per trace table) for all OM-defined trace table types, except for those requiring explicit commands.
CSL: The Common Service Layer (CSL) trace table is used for routines that are common to all CSL managers. The default number of pages for this table is 4.
ERR: The error trace table traces error events within an OM address space. The default number of pages for this table is 4.
Restriction: You cannot set the level for the ERR trace table. 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. You can, however, specify the number of pages for the ERR trace table on the TRCLEV statement.
OM: The Operations Manager (OM) trace table traces events that are related to general OM processes. The default number of pages for this table is 4.
PLEX: The IMSplex trace table traces OM processing for a specific IMSplex. The default number of pages for this table is 8.

RM trace tables

RM provides a set of trace table types for tracing processing within the RM address space. These RM trace table types are present only in an RM address space. TRCLEV statements specifying a component of RM are ignored for any other address space type.

*

Specifying an asterisk (*) sets the default trace level (and, optionally, the default number of pages per trace table) for all RM-defined trace table types, except for those requiring explicit commands.

CSL

The Common Service Layer (CSL) trace table is used for routines that are common to all CSL managers. The default number of pages for this table is 4.

ERR

The error trace table traces error events within an RM address space. The default number of pages for this table is 4.

Restriction: You cannot set the level for the ERR trace table. 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. You can, however, specify the number of pages for the ERR trace table on the TRCLEV statement.

REPO

IMSRSC repository trace table traces repository-related processing within the RM address space. The default number of pages for this table is 16.

The RM repository trace can be specified with the BPE DISPLAY and BPE UPDATE TRACETABLE commands for RM address space traces.

Each RM repository trace table entry is 64 bytes long. The macro CSLRTRC contains the mapping of the RM repository trace table records.

RM

The Resource Manager (RM) trace table traces events that are related to general RM processes. The default number of pages for this table is 4.

PLEX

The IMSplex trace table traces RM processing for a specific IMSplex. The default number of pages for this table is 8.

RS trace table types

The IMS repository function provides a set of trace table types for tracing processing within the RS address space. These trace table types are present only in an RS address space.

*: Specifying an asterisk (*) sets the default trace level (and, optionally, the default number of pages per trace table) for all RS-defined trace table types, except for those requiring explicit commands.
DIAG: The DIAG trace table contains diagnostic trace entries for the RS. The default number of pages for this table is 4.

SCI trace tables

SCI provides a set of trace table types for tracing processing within the SCI address space. These SCI trace table types are present only in a SCI address space. TRCLEV statements specifying a component of SCI are ignored for any other address space type.

*: Specifying an asterisk (*) sets the default trace level (and, optionally, the default number of pages per trace table) for all SCI-defined trace table types, except for those requiring explicit commands.
CSL: The Common Service Layer (CSL) trace table is used for routines that are common to all CSL address spaces. The default number of pages for this table is 8.
ERPL: The error parameter list trace table traces a copy of the interface parameter list when an error occurs processing an SCI request or message. The default number of pages for this table is 8.
ERR: The error trace table traces error events within an SCI address space. The default number of pages for this table is 4.
Restriction: You cannot set the level for the ERR trace table. 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. You can, however, specify the number of pages for the ERR trace table on the TRCLEV statement.
INTF: The interface trace table traces IMSplex member interface activity (requests and messages). The default number of pages for this table is 8.
INTP: The interface parameter trace table traces a copy of the interface parameter list during SCI request and message processing. The default number of pages for this table is 16.
PLEX: The IMSplex trace table traces SCI processing for a specific IMSplex. The default number of pages for this table is 8.
SCI: The Structured Call Interface (SCI) trace table traces events that are related to general SCI processes. The default number of pages for this table is 8.

level

Controls how much tracing is done in the specified trace table. Each trace entry that is made has a level that is associated with the entry. Each trace table has a level setting that is controlled by the value for level that you specify on the TRCLEV statement for the table.

A trace entry is written only if the trace entry's level is less than or equal to the table's level setting. For example, if the trace entry level is MEDIUM, the trace entry is added to the trace table only if the table's level is MEDIUM or HIGH. Thus, the level you specify controls the volume (number) of trace entries that are written to a given table.

A low setting of the level parameter results in fewer trace entries being made to the table. The trace table does not wrap as quickly as with a higher setting (which means that diagnostic information remains available for a longer time), and the performance impact is minimized. However, the trace information is not as detailed as with higher settings, so the captured information might not be sufficient to solve a problem.

A high setting of the level parameter results in more trace entries being written to the table. This can provide additional diagnostic information for solving a problem; however, the trace table tends to wrap more frequently, and higher settings can cause additional CPU usage.

Choose one of the following for the level parameter:

NONE: No tracing.
Recommendation: Do not specify NONE because no tracing, not even tracing for error conditions, is done for the specified table.
ERROR: Only trace entries for error conditions are made. ERROR is the default.
LOW: Low-volume tracing (key component events). This is the minimum recommended trace level setting for normal operation.
MEDIUM: Medium-volume tracing (most component events).
HIGH: High-volume tracing (all component events).

ims_component

Specifies the IMS component that defines the trace table type. Possible values are:

BPE: Indicates that the table is a BPE-defined (system) trace table. BPE trace tables exist in all IMS component address spaces that run with BPE.
CQS: Indicates that the table is a Common Queue Server-defined trace table type.
DBRC: Indicates that the table is a DBRC-defined trace table type.
HWS: Indicates that the table is an IMS Connect-defined trace table type.
ODBM: Indicates that the table is an ODBM-defined trace table type.
OM: Indicates that the table is an Operations Manager-defined trace table type.
REPO: Indicates that the table is a Repository Server-defined trace table type.
RM: Indicates that the table is a Resource Manager-defined trace table type.
SCI: Indicates that the table is a Structured Call Interface-defined trace table type.

PAGES=num_pages

An optional parameter that can be used to specify the number of 4 KB pages to be allocated for the table type.

Specify a value from 1 - 32767 pages for this parameter. If BPE is unable to get the amount of storage you requested for a trace table, it tries to get a smaller number of pages to enable some tracing to be done. You can see the actual number of pages BPE obtained for each trace by issuing the DISPLAY TRACETABLE command.

If you do not use this parameter, then the trace table has the default number of pages, as specified under the description of each trace table type.

EXTERNAL=

YES: Specifies that trace entries are written to the external trace data set. However, IMS writes the trace entries only if you define the data set to IMS by using the EXTTRACE statement. If you use the BPE recorder trace facility, you must specify EXTERNAL=YES.
NO: Specifies that trace entries are written only to memory and not to the external trace data set. NO is the default value.

BPECFG= EXITMBR syntax

The EXITMBR parameter specifies the exit list member name. You can specify one EXITMBR= parameter for each IMS component running with BPE, and one EXITMBR= parameter for BPE itself.

BPECFG= EXITMBR parameters

member_name

Specifies the 1- to 8-character exit list member name.

ims_component

Specifies the IMS component whose user exit routines are being defined. Possible values are:

BPE: Indicates the BPE exit routine member name.
CQS: Indicates the Common Queue Server exit routine member name.
DBRC: Indicates the DBRC exit routine member name.
HWS: Indicates the IMS Connect exit routine member name.
ODBM: Indicates the Open Database Manager (ODBM) exit routine member name.
OM: Indicates the Operations Manager (OM) exit routine member name.
RM: Indicates the Resource Manager (RM) exit routine member name.
SCI: Indicates the Structured Call Interface (SCI) exit routine member name.

BPECFG= STATINTV syntax

The optional STATINTV parameter specifies the time interval, in seconds, between calls to the BPE statistics exit or exit routines. You can set STATINTV from 1 to 2147483647 (2³¹-1). The default STATINTV value is 600 (10 minutes).

Usage

Specify a STATINTV value of 60 or more to avoid possible performance problems due to frequent exit routine calls.

BPECFG= CONDRSB syntax

Note: This information provides only general descriptions of the types and portions of workloads that are eligible for execution on Specialty Engines (for example, zIIPs, zAAPs, and IFLs) (“SEs”). IBM® authorizes customers to use IBM SEs only to execute the processing of Eligible Workloads of specific Programs expressly authorized by IBM as specified in the “Authorized Use Table for IBM Machines” provided at www.ibm.com/systems/support/machine_warranties/machine_code/aut.html (“AUT”). No other workload processing is authorized for execution on an SE. IBM offers SEs at a lower price than General Processors/Central Processors because customers are authorized to use SEs only to process certain types and/or amounts of workloads as specified by IBM in the AUT.

In IMS 15.5 ("V15.5") and later, certain processing in the IMS Connect address space, the IMS Open Database Manager (“ODBM”) address space, and in the IMS Common Queue Server (“CQS”) address space, as specified below may, when enclave SRB execution is enabled by a user, be executed under enclave service request blocks (“SRBs”). Enclave SRB execution may be enabled as unconditional;¹ or it may be enabled as conditional, based on the presence of at least one zIIP during address space initialization. When enclave SRB execution is enabled, V15.5 will direct z/OS to authorize such work to be processed on an available zIIP.

Except as otherwise described below, the following IMS Connect and ODBM processing can execute under an enclave SRB in V15.5:

Processing of IMS Connect address space SOAP message threads for SOAP messages arriving via TCP/IP
Processing of IMS Connect and ODBM address space Distributed Relational Database Architecture™ (“DRDA”) threads for DRDA requests arriving via TCP/IP.
Processing of IMS Connect address space Multiple System Coupling (“MSC”) threads for MSC messages arriving via TCP/IP
Processing of IMS Connect address space Intersystem Communication ("ISC") threads for ISC messages arriving via TCP/IP
Processing of ODBM address space threads for requests arriving through the CSLDMI API
Processing of CQS address space threads that process CQSREAD and CQSBRWSE requests (CQSREAD and CQSBRWSE are requests used by CQS clients such as the IMS control region to read and browse data in the CQS message queue and resource structures)

Note that any user exits called by the above processing will not execute under an enclave SRB. User exits are always given control in TCB mode, and such exit instructions are not authorized to be processed on a zIIP. Also note that certain processing cannot, due to technical restrictions, execute under enclave SRBs. Such processing includes calling z/OS Resource Recovery Services (“RRS”), IMS DL/I call processing, and z/OS supervisor calls (“SVCs”). IMS switches from SRB mode into TCB mode to perform such processing, and thus such processing will not execute on a zIIP.

The CONDSRB parameter allows you to specify how BPE manages conditional SRB threads. Using this parameter, you can request BPE to:

Always run such conditional SRB threads in SRB mode, even if there are no zIIPs online
Never run such conditional SRB threads in SRB mode, even if there are zIIPs online
Conditionally run such conditional SRB threads in SRB mode only when there are zIIPs online

The syntax of the parameter is as follows:

The first parameter of CONDSRB specifies BPE’s behavior for threads in address spaces belonging to the IMS component indicated by the second CONDSRB parameter. There are three possible values for this first parameter:

NEVER

BPE will never run the conditional SRB threads in SRB mode; it will always run them in TCB mode. This is the default behavior, and applies if no CONDSRB statement is coded for an applicable IMS Connect, ODBM, or CQS address space.

Running on a zIIP in SRB mode can reduce software license charges. However, SRB-mode execution is more restrictive than TCB mode. There can be additional processing overhead involved if a thread running in SRB mode has to switch back to TCB mode to perform some processing that is not supported in SRB mode. Additionally, if you have IIPHONORPRIORITY=NO specified in the z/OS IEAOPTxx SYS1.PARMLIB member, ready zIIP-eligible work will wait for a zIIP processor when one is not immediately available, even if there is a standard processor available that could process the work.

Thus, you can use the NEVER setting of CONDSRB to avoid SRB-TCB mode switching overhead, and to force work that could have been zIIP-eligible to run instead on standard processors. No execution on zIIPs will occur for the specified IMS component (for example, IMS Connect, ODBM, or CQS).

For additional information about the IIPHONORPRIORITY parameter, see z/OS MVS Initialization and Tuning Reference (SA22-7592).

ALWAYS

BPE will always run conditional SRB threads in SRB mode, even if there were no zIIPs present on the system when BPE services were started (which is typically the time you started the job or started task for the IMS component address space).

If you do not have a zIIP available, you still might want to run the threads in SRB mode. z/OS provides the ability to project the amount of CPU you could have executed on a zIIP had one been installed. You request this projection via the PROJECTCPU parameter of the IEAOPTxx SYS1.PARMLIB member. (See z/OS MVS Initialization and Tuning Reference (SA22-7592) for more information.) For this projection to be effective, you must also tell BPE to run the threads in SRB mode always, even when there is no zIIP online.

COND

BPE will run the conditional SRB threads in SRB mode if there was at least one zIIP online at the time BPE services were started. Otherwise, BPE will run the threads in TCB mode, and no utilization of a zIIP for such threads will occur.

The second parameter of CONDSRB specifies the IMS component address space type to which the CONDSRB statement applies. Possible values are:

CQS: Common Queue Server
HWS: IMS Connect
ODBM: Open Database Manager

Note that the CONDSRB statement may be coded for other IMS component address space types; however, no zIIP processing of threads in these address spaces will occur, and the CONDSRB statement will be ignored. Only the specific threads identified in this topic are eligible for execution on a zIIP when using IMS V15.5 and later.

BPECFG= examples

A sample BPE configuration data set for BPE is shown in the example below. This example shows a BPE configuration data set that can be shared by IMS Connect, CQS, CSL, and DBRC. It contains definitions for traces for:

BPE
CQS
DBRC
IMS Connect
ODBM
OM
RM
RS
SCI

It also contains user exit routine list member specifications.

*********************************************************************
*  CONFIGURATION FILE FOR BPE                                       *
*********************************************************************

LANG=ENU                         /* Language for messages       */
                                 /* (ENU = U.S. English)        */
STATINTV=420                     /* STATS user exit interval    */
                                 /* = 420 seconds (7 minutes)   */

#
# Definitions for BPE system traces
#

TRCLEV=(*,LOW,BPE)               /* Set default for all BPE     */
                                 /* traces to LOW.              */
TRCLEV=(AWE,HIGH,BPE)            /* AWE server trace on high    */
TRCLEV=(CBS,MEDIUM,BPE)          /* Ctrl blk serv trc on medium */
TRCLEV=(DISP,HIGH,BPE,PAGES=12)  /* Dispatcher trace on high    */
                                 /* with 12 pages               */

# 
# Definitions for IMS Connect traces
#
TRCLEV(RCTR,MEDIUM,HWS,EXT=YES)   /* Starts recorder trace      */
                                  /* facility                   */


# Definitions for CQS traces
#

TRCLEV=(*,MEDIUM,CQS)            /* Set default for all CQS     */
TRCLEV=(STR,HIGH,CQS)            /* traces to medium            */
                                 /* but run STR trace on high   */

# DBRC: 

TRCLEV=(*,LOW,DBRC)              /* DEFAULT DBRC TRACES TO LOW */
TRCLEV=(RQST,HIGH,DBRC) 		      /* DBRC GENERAL TRACE ON HIGH	 */
TRCLEV=(MODF,MEDIUM,DBRC)        /* MODULE FLOW TRACE ON MEDIUM*/

#
#
# DEFINITIONS FOR ODBM TRACES - SET DEFAULT FOR ALL ODBM TRACES     
# TO LOW, THEN SELETIVELY OVERRIDE THOSE THAT NEED A DIFFERENT      
# LEVEL.                                                            
#                                                                   
                                                                    
TRCLEV=(*,LOW,ODBM)                  /* DEFAULT ODBM TRACES TO LOW */
TRCLEV=(CSL,HIGH,ODBM)               /* CSL TRACE ON HIGH          */
TRCLEV=(ODBM,HIGH,ODBM)              /* ODBM GENERAL TRACE ON HIGH */
TRCLEV=(PLEX,HIGH,ODBM)              /* IMSPLEX TRACE ON HIGH      */
#
#
# Definitions for OM traces
#

TRCLEV=(*,MEDIUM,OM)             /* Set default for all OM      */
                                 /* traces to medium            */

# DEFINITIONS FOR REPOSITORY SERVER TRACES
TRCLEV=(DIAG,HIGH,REPO,PAGES=300)    /* DIAG TRACE ON HIGH     */


#
# Definitions for RM traces
#

TRCLEV=(*,MEDIUM,RM)             /* Set default for all RM      */
                                 /* traces to medium            */
TRCLEV=(REPO,HIGH,RM,PAGES=300)  /* Repo trace on high          */

#
# Definitions for SCI traces
#

TRCLEV=(*,MEDIUM,SCI)            /* Set default for all SCI     */
                                 /* traces to medium            */
TRCLEV=(INTF,HIGH,SCI)           /* Intf call trace on high     */
TRCLEV=(INTP,HIGH,SCI)           /* Intf parmlist trace on high */

#
# User exit list PROCLIB member specifications
#

EXITMBR=(BPEEXIT0,BPE)           /* BPE user exit definitions   */
EXITMBR=(DBREXIT0,DBRC)          /* DBRC user exit definitions  */
EXITMBR=(CQSEXIT0,CQS)           /* CQS user exit definitions   */
EXITMBR=(OMEXIT00,OM)            /* OM user exit definitions    */
EXITMBR=(RMEXIT00,RM)            /* RM user exit definitions    */
EXITMBR=(SCIEXIT0,SCI)           /* SCI user exit definitions   */
EXITMBR=(CSLEXDM0,ODBM)          /* SPECIFY PROCLIB DATASET     */
                                 /* MEMBER CSLEXDM0 AS ODBM'S   */
                                 /* USER EXIT LIST MEMBER       */

A sample member of the IMS PROCLIB data set with generic and specific EXTTRACE entries is shown in the example below.

You can use z/OS symbolic substitution parameters in the data set name of the BPE external trace GDG data set. This makes a single EXTTRACE specification unique to each address space. For example, you can use the symbol &JOBNAME. in the data set name; it is replaced by the actual address space job name when a BPE address space starts and allocates the external trace data set.

Sample BPE configuration member for a single IMS Connect address space

LANG=ENU           /* LANGUAGE FOR MESSAGES     */               
                   /* (ENU = U.S. ENGLISH)      */               
#                                                                
# DEFINITIONS FOR IMS CONNECT TRACES                             
# HWS:                                                           
TRCLEV=(ENVT,MEDIUM,HWS,EXTERNAL=YES)                            
TRCLEV=(HWSO,HIGH,HWS,EXTERNAL=NO)                               
TRCLEV=(PLEX,HIGH,ODBM)                                          
TRCLEV=(OMDR,LOW,HWS,EXTERNAL=YES)                               
TRCLEV=(OTMA,HIGH,HWS,EXTERNAL=YES)                              
                                                                 
# External trace definitions:                                    
EXTTRACE(GDGDEF(DSN(IMSTESTL.BPETHWS) UNIT(SYSDA) VOLSER(000000)
SPACE(5) ) COMP(HWS) )  /* EXTTRACE specific to IMS Connect address space */

Sample BPE configuration with multiple EXTTRACE statements

A sample BPE member of the IMS PROCLIB data set with multiple EXTTRACE statements is shown in the example below.

LANG=ENU           /* LANGUAGE FOR MESSAGES     */                    
                   /* (ENU = U.S. ENGLISH)      */                    
                                                                      
#                                                                     
# DEFINITIONS FOR SYSTEM TRACES                                       
#                                                                     
TRCLEV=(*,LOW,BPE,EXTERNAL=NO)                                        

# CQS:                                                                
                                                                      
TRCLEV=(CQS,MEDIUM,CQS,EXTERNAL=YES)                                  
TRCLEV=(ERR,HIGH,CQS,EXTERNAL=NO)                                     
TRCLEV=(INTF,LOW,CQS,EXTERNAL=YES)                                    
TRCLEV=(STR,HIGH,CQS,EXTERNAL=YES)                                    
TRCLEV=(OFLW,HIGH,CQS,EXTERNAL=YES)                                   
TRCLEV=(SEVT,HIGH,CQS,EXTERNAL=YES)                                   
                                                                      
# SCI:                                                                
                                                                      
TRCLEV=(ERR,HIGH,SCI,EXTERNAL=NO)                                     
TRCLEV=(INTF,LOW,SCI,EXTERNAL=YES)                                    
TRCLEV=(INTP,HIGH,SCI,EXTERNAL=YES)                                   
TRCLEV=(SCI,MEDIUM,SCI,EXTERNAL=YES)                                  
                                                                      
# OM:                                                                 
                                                                      
TRCLEV=(*,LOW,OM,EXTERNAL=YES)     /* SET ALL TABLES TO LOW TRACING */
                                                                      
# ODBM:                                                               
                                                                      
TRCLEV=(*,LOW,ODBM,EXTERNAL=YES)   /* SET ALL TABLES TO LOW TRACING */
                                                                      
# DBRC:
                                                                      
TRCLEV=(*,MEDIUM,DBRC,EXTERNAL=YES) /* SET ALL TABLES TO MEDIUM TRACING */
                                                                      
# External trace definitions:                                         
                                                                      
EXTTRACE(GDGDEF(DSN(IMSTESTL.BPETCQS) UNIT(SYSDA) VOLSER(000000)      
SPACE(5) ) COMP(CQS) )  /* <------ EXTTRACE for CQS                 */
                                                          
EXTTRACE(GDGDEF(DSN(IMSTESTL.BPETDBRC) UNIT(SYSDA) VOLSER(000000)      
SPACE(5) ) COMP(DBRC) ) /* <------ EXTTRACE for DBRC                */ 
                                                          
EXTTRACE(GDGDEF(DSN(IMSTESTL.BPETSCI) UNIT(SYSDA) VOLSER(000000)      
SPACE(5) ) COMP(SCI) )  /* <------ EXTTRACE for SCI                 */
                                                                      
EXTTRACE(GDGDEF(DSN(IMSTESTL.BPETOM) UNIT(SYSDA) VOLSER(000000)       
SPACE(5) ) COMP(OM) )   /* <------ EXTTRACE for OM                  */
                                                                      
EXTTRACE(GDGDEF(DSN(IMSTESTL.BPETODBM) UNIT(SYSDA) VOLSER(000000)     
SPACE(5) ) COMP(ODBM) )   /* <------ EXTTRACE for ODBM              */

Sample BPE configuration using symbolic parameters for EXTTRACE statements

A sample BPE member of the IMS PROCLIB data set with EXTTRACE statements using symbolic parameters is shown in the example below.

#                                                         
# DEFINITIONS FOR SYSTEM TRACES                           
#                                                         
TRCLEV=(*,LOW,BPE,EXTERNAL=NO)                            
                                                          
# SCI:                                                    
                                                          
TRCLEV=(ERR,HIGH,SCI,EXTERNAL=NO)                         
TRCLEV=(INTF,LOW,SCI,EXTERNAL=YES)                        
TRCLEV=(INTP,HIGH,SCI,EXTERNAL=YES)                       
TRCLEV=(SCI,MEDIUM,SCI EXTERNAL=YES)                      
                                                          
#OM:                                                      
                                                          
TRCLEV=(*,LOW,OM,EXTERNAL=YES)                            
                                                          
#ODBM:                                                    
                                                          
TRCLEV=(*,LOW,ODBM,EXTERNAL=YES)                          
                                                          
#DBRC:
TRCLEV=(*,MEDIUM,DBRC,EXTERNAL=YES)                       
                                                          
#RM:                                                      
                                                          
TRCLEV=(CSL,HIGH,RM,EXTERNAL=YES)                         
TRCLEV=(ERR,HIGH,RM,EXTERNAL=NO)                          
TRCLEV=(PLEX,LOW,RM,EXTERNAL=YES)                         
TRCLEV=(RM,MEDIUM,RM,EXTERNAL=YES)                        
                                                          
# External trace definitions:                             
# Use symbolic symbols in the DSN, SMS testing 
/* EXTTRACE with symbolic data set name BPE&JOBNAME     */
EXTTRACE(GDGEF(DSN(IMSTESTL.BPE&JOBNAME) STORCLAS(SNPSTOR)
SPACE(20) AVGREC(K) DATACLAS(SNPDATA) ) )                 
                                                          
/* EXTTRACE statement specifically for RM address space */
/* to allow it to have a name and characteristics       */
/* different from the generic specification, above.     */
EXTTRACE(GDGDEF(DSN(IMSTESTL.RMTRACE) STORCLAS(SNPSTOR)
SPACE(30) AVGREC(K) DATACLAS(SNPDATA)) COMP(RM)  )

¹ In an unconditional status, the user may enable such processing to be executed in enclave SRB mode when no zIIP is online or part of the user's System z® environment. But, of course, no zIIP utilization could result. A user might request enclave SRB execution even in the absence of zIIPs, to allow the system to project how much work is eligible to run on zIIP and probably would if there were zIIP capacity available. See the PROJECTCPU parameter of the IEAOPTxx SYS1.PARMLIB member in z/OS MVS Initialization and Tuning Reference (SA22-7592) for further information.