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.
BPE 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.
BPE Verb-Resource Type Command Syntax .--------------------------. V | >>-verb--resourcetype----+----------------------+-+------------>< | .-,-----. | | V | | '-keyword(---value-+-)-'
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.
Some parameters on BPE commands support wildcard characters for pattern matching. For such parameters, you can use the following wildcard characters:
The following examples illustrate some uses of wildcard characters.
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:
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 |
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:
Use this command to display the current attribute settings for the requested trace tables.
>>-+-DISPLAY-+--+-TRACETABLE-+----------------------------------> '-DIS-----' '-TRTAB------' .-,---------------------. V | >--NAME(---+-trace_table_name--+-+-)--+------------------+----->< '-trace_table_name*-' '-OWNER(-+-BPE-+-)-' +-CQS-+ +-OM--+ +-RM--+ '-SCI-'
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:
You can display CQS-defined trace tables only for CQS address spaces. These CQS-defined trace table types are available:
You can display OM-defined trace tables only for OM address spaces. These OM-defined trace table types are available:
You can display RM-defined trace tables only for RM address spaces. These RM-defined trace table types are available:
You can display SCI-defined trace tables only for SCI address spaces. These SCI-defined trace table types are available:
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).
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:
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
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
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
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
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
Use this command to change the trace level setting for the requested trace tables.
>>-+-UPDATE-+--+-TRACETABLE-+-----------------------------------> '-UPD----' '-TRTAB------' .-,---------------------. V | >--NAME(---+-trace_table_name--+-+-)--+------------------+------> '-trace_table_name*-' '-OWNER(-+-BPE-+-)-' +-CQS-+ +-OM--+ +-RM--+ '-SCI-' >--+---------------------+------------------------------------->< '-LEVEL(-+-NONE---+-)-' +-ERROR--+ +-LOW----+ +-MEDIUM-+ '-HIGH---'
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:
You can update CQS-defined trace tables only for CQS address spaces. These CQS-defined trace table types are available:
You can update OM-defined trace tables only for OM address spaces. These OM-defined trace table types are available:
You can update RM-defined trace tables only for RM address spaces. These RM-defined trace table types are available:
You can update SCI-defined trace tables only for SCI address spaces. These SCI-defined trace table types are available:
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).
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.
The UPDATE TRACETABLE command output consists of message BPE0032I indicating that the command has completed:
BPE0032I UPDATE TRACETABLE COMMAND COMPLETED
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
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
Use this command to display both the version of the IMS component that is using BPE, and the version of the BPE in use.
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.
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
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
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).
Use this command to display attributes for all modules associated with the specified user exit types.
>>-+-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----'
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:
User exit types are defined in all CQS address spaces, as specified by OWNER(CQS), and include the following:
User exit types are defined in all OM address spaces, as specified by OWNER(OM), and include the following:
User exit types are defined in all RM address spaces, as specified by OWNER(RM), and include the following:
User exit types are defined in all SCI address spaces, as specified by OWNER(SCI), and include the following:
Related Reading:
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).
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:
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.
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.
The maximum value that can be displayed in this field is 999999. If the active count exceeds this value, 999999 is displayed.
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.
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.
yyyy-mm-dd hh:mm:ss.th
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.
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.
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.
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
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
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
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
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.
Recommendation: Code and link edit all user exit modules as re-entrant to avoid this problem.
Recommendation: Place a version number in the static work area, so that your exits can easily tell when they are using a back-level data structure within this work area.
Recommendation: Ensure that your user exits avoid long WAITs, and avoid issuing services that might WAIT.
>>-+-REFRESH-+--+-USEREXIT-+------------------------------------> '-REF-----' '-USRX-----' .-,------------------------. V | >--NAME(---+-user_exit_type_name--+-+-)--+------------------+-->< '-user_exit_type_name*-' '-OWNER(-+-BPE-+-)-' +-CQS-+ +-OM--+ +-RM--+ '-SCI-'
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:
User exit types are defined in all CQS address spaces, as specified by OWNER(CQS), and include the following:
User exit types are defined in all OM address spaces, as specified by OWNER(OM), and include the following:
User exit types are defined in all RM address spaces, as specified by OWNER(RM), and include the following:
User exit types are defined in all SCI address spaces, as specified by OWNER(SCI), and include the following:
Related Reading:
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).
The REFRESH USEREXIT command output consists of message, BPE0032I indicating that the command has completed:
BPE0032I REFRESH USEREXIT COMMAND COMPLETED
Refresh all user exit modules.
Command:
F CQS1,REFRESH USEREXIT NAME(*)
Output:
BPE0032I REFRESH USEREXIT COMMAND COMPLETED
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