ECB Resource Monitor PUT10 Enhancements on z/TPF

The latest changes to the entry control block (ECB) resource monitor on IBM® z/Transaction Processing Facility (z/TPF) give the users more flexibility to define and retrieve resource usages in the system. This article gives an introduction to the enhancements in APAR PJ40979. It also provides a tutorial on how to configure your system and take advantage of the new features.

Share:

Gabriel Nieves (gnieves@us.ibm.com), Software Engineer, IBM

photo of Gabriel NievesGabriel Nieves is a Software Engineer at the TPF Development Lab in Poughkeepsie, New York. He received a Bachelor of Science degree in Computer Engineering from the New Jersey Institute of Technology in 2012.



11 June 2014

Also available in Chinese Russian

Introduction

IBM® z/Transaction Processing Facility, Enterprise Edition (z/TPF), Version 1.1 (5748-T15), is a high-performance operating system specifically designed to provide high availability for demanding, high-volume, real-time transaction processing for business-critical applications. z/TPF runs on IBM zSeries® servers, which offer an infrastructure for transaction processing with high quality-of-service demands.

The ECB resource monitor is a centralized facility on z/TPF that tracks the use of various system resources for each entry control block (ECB) and executes a specific action when an ECB exceeds an assigned resource limit. APAR PJ40979 expands the functionality of the ECB resource monitor by giving the user the ability to create multiple grouped monitoring limits, called named limit sets (LSETs), which are kept on the z/TPF system. System actions for passing a limit can now be set for individual resources. In addition, new APIs allow for the application program to apply the named limit set to an ECB’s resource limit table (RLT) and retrieve the resource count table (RCT) of the ECB.

Managing Named Limit Sets with the ZECBM command

The changes to the ECB resource monitor in APAR PJ40979 allow the user to manage collections of LSETs by using the ZECBM command. Previously, the ECB resource monitor maintained just one set of default resource limits that were initialized to all ECBs. A new LSET is created in the file copy of the RLT by using the ZECBM CREATE LSETNAME command (Figure 1). In z/TPF's database, a fixed record is a static file storage that is used for a specific purpose and that is accessible using a record type and ordinal number to determine its file address. A pool record is part of a group of file storage that does not have a specific purpose. The application requests a pool record when it needs to expand a specific database. The file copy of the RLT is a fixed record with a record type #IBMM4 ordinal #ECBRM1. When a new LSET is created, a pool record is used to manage its data and chained to the file copy of RLT.

As with the system default set, a LSET can have separate values for its file copy and core copy. The core copy of RLT is located in main storage and referenced by the symbolic label CMMRLT using the CINFC macro. The ZECBM REFRESH LSETNAME command copies over the LSET from the file copy to the core copy of the RLT. A 4K system heap block is used to store a LSET that is chained to the core copy of RLT. A named limit set must be stored in the core copy for it to be used by the ECBMC macro for changing the resource limits of an ECB. The ZECBM DISPLAY LSETNAME command is used to view the file and core copies of the LSET on the console.

Figure 1. Creating and displaying new named limit set
output of the ZECBM REFRESH LSETNAME command

A new LSET has its resource limits either assigned to use the system default values or copied from an existing named limit set. Unless the named limit set is created from an existing LSET using the CSETNAME parameter in the ZECBM CREATE command, all of the values are set to use the default values of the RLT. This is indicated by asterisks as the resource limits when the named limit set is displayed on the console. These resource limits can be changed by using the ZECBM SET LSETNAME command (Figure 2). The ZECBM SAVE LSETNAME command complements the REFRESH option by saving the core copy of the LSET into the file copy. The resource limits can be changed to use the system default values using the ZECBM REMOVE command.

Figure 2. Copying an existing named limit set
commands for copying a named limit set

An ECB is initialized using the limit values from the core copy of the RLT. A named limit set must be moved from the file copy to the core copy before an ECB can be configured to use the LSET. The ZECBM DISPLAY LSET command lists all named limit sets on both the file and the core copies. The DEFAULT set is actually the system default RLT of the copy; the DEFAULT set cannot be deleted or changed using the LSETNAME option. It is important to note that while a LSET may exist in only the file copy, deleting a named limit set removes the LSET from both file and core copies (Figure 3). This can be done by using the ZECBM DELETE LSETNAME command.

Figure 3. Deleting a named limit set
using the ZECBM DELETE LSETNAME command.

Setting Resource Limit Actions by Resource Type

APAR PJ40979 also allows the user to set the resource limit actions for individual resources and rates. The ZECBM SET ACTION command can be used to change the actions for any resource type. Resource limit actions are only established in the system default set, so any ECBs using a named limit set still rely on the core copy of the RLT for the actions. To view the current settings for all of the resources, use the ZECBM DISPLAY ACTION command (Figure 4). An asterisk indicates that the resource or rate uses the system default action for that particular limit. When the ZECBM SAVE and ZECBM REFRESH commands are used to modify the file-/core-copies of the system default set, they also overwrite the resource action settings. The ZECBM RESET command clears the resource limits and actions of the core RLT.

Figure 4. Changing limit actions by resource
commands for changing limit actions

Using Named Limit Sets with the ECBMC macro

The RLT of the ECB can have its value changed to use the named limit set once it has been stored as a core copy on the z/TPF system. The LSET is applied to the ECB by using the ECBMC SET operation with the new LSETNAME parameter. In addition, the optional LSETNFND parameter specifies the address of the next instruction if the named limit set cannot be found. Listing 1 is an example of the ECBMC macro being used to apply the named limit set on the current ECB.

Listing 1. Setting ECB resource limits using named limit set
ECBMC SET,LSETNAME=NAMEDSET,LSETNFND=BADLSET
…
NAMEDSET DC CL8’MYLSET01’

The LSETNAME parameter requires the address of an eight-byte character name of the LSET. If a named limit set is defined with a label less than eight characters using the ZECBM command, the name passed to the ECBMC macro must be padded with blank characters. This can be ensured by always defining the constant for the name as a type-length of CL8. If a resource limit in an LSET is undefined (i.e., set to use the default limit), the value for that limit in the RLT of the ECB remains unchanged. Therefore, it is possible to apply an additional LSET with only a subset of resource limits defined to an ECB without completely overwriting the changes made by other LSETs. Any level indicators reached for a resource limit are not reset even if the applied LSET increases the limit’s value.

For C/C++ programs, the tpf_ecbmc_set_lsetname function can be used to change the resource limits of the current ECB using a named limit set.


Querying Resource Counts in ECB

In APAR PJ40979, the new QUERYRCT parameter for the ECBMC macro retrieves the resource counts from the RCT of an ECB. The received list is storage that is mapped by the DSECT IDCECBM. Because these resource counts are the same values used by the ECB resource monitor, routines can be coded to monitor resources with their own limits and actions. In Listing 2, a new routine path is taken when the FILE resource count exceeds its resource limit established in the RLT of the current ECB. Other possible usages of the queried resource counts include applying a named limit set to the current ECB or changing a new resource limit before a particular resource limit is reached.

Listing 2. Branching routine using queried FILE count and limit set
QRLT    IDCECBM REG=R1
QRCT    IDCECBM REG=R2
ECBMC   QUERY,LIST=(R1)
ECBMC   QUERYRCT,LISTRCT=(R2)
L       R3,QRCT.ECBM_FILE_COUNT   Load FILE resource count
C       R3,QRLT.ECBM_FILE         Has exceeded FILE limit?
JH      NEWPATH                   Yes, proceed to new path
FREEC   BLOCK=R1
FREEC   BLOCK=R2
DROP    QRLT,QRCT

For C/C++ programs, the tpf_ecbmc_query_rct function can be used to query the RCT of the current ECB.


Conclusion

The changes to the ECB resource monitor provided by APAR PJ40979 gives users better management of the resource limits assigned to ECBs. The desired behavior for exceeding a limit can be established based on specific resources. The ability to query the resource counts of ECBs allows not only gauging the resource usages, but also customizing programs to proceed differently based on those resource usages.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=972801
ArticleTitle=ECB Resource Monitor PUT10 Enhancements on z/TPF
publish-date=06112014