tpf_ownerc: Get information about physical block or system heap storage use

This function gets the current number of storage blocks that are in use for supported physical block types or the current amount of system heap storage (in bytes) that is in use based on a specified set of owner names or block type.

Last updated

  • Changed in 2019.
  • Changed for PUT15.
  • Changed for PUT07 (information only; no code change).
  • Changed for PUT06 (information only; no code change).
  • Added for PUT00.

Format

#include <tpf/sysapi.h>
int tpf_ownerc(struct t_iowner **area, t_iowner_name *owner, 
               t_iownerblk blktype, int high);
area
Points to a pointer field that is updated on return from tpf_ownerc to hold the address of the output information storage area. The output storage is allocated from ECB heap storage and must be released by the caller by using the free C function. The output storage contains the following information:
  • 4-byte number of owner names returned
  • 8-byte reserved area
  • Each owner name has the following information for physical block type information:
    • 8-byte high-level qualifier (padded with blanks)
    • 8-byte mid-level qualifier (padded with blanks)
    • 16-byte low-level qualifier (padded with blanks)
    • Number of input/output blocks (IOBs) that are in use and have the specified owner name
    • Number of entry control blocks (ECBs) that are in use and have the specified owner name
    • Number of system work blocks (SWBs) that are in use and have the specified owner name
    • Number of extended system work blocks (XWBs) that are in use and have the specified owner name
    • Number of common blocks that are in use and have the specified owner name
    • Number of 4-KB frames that are in use and have the specified owner name
    • Number of 1-MB frames that are in use and have the specified owner name.
  • Each owner name has the following information for system heap information:
    • 8-byte high-level qualifier (padded with blanks)
    • 8-byte mid-level qualifier (padded with blanks)
    • 16-byte low-level qualifier (padded with blanks)
    • Number of KBs of 31-bit system heap storage that are in use with the specified owner name
    • Number of KBs of 64-bit system heap storage that are in use with the specified owner name
    • Number of KBs of recoverable system heap that are in use with the specified owner name
owner
Specifies a pointer to a 32-character area that contains the owner name selection criteria. This criteria identifies the set of owner names for which storage information will be returned. The owner name contains three parts:
  • 8-byte high-level qualifier, which must be EBCDIC characters that can be printed and padded with blanks. The qualifier cannot start with a blank character or a wildcard character (asterisk (*)).
  • 8-byte mid-level qualifier, which must be EBCDIC characters that can be printed and padded with blanks.
  • 16-byte low-level qualifier, which must be padded with blanks.
Note:
  1. Characters that cannot be printed are replaced by a period (.) in any display of the ECB owner name.
  2. The owner name selection criteria can include a single wildcard character. The wildcard character must be the last non-blank character in the selection criteria.
  3. Specify NULL to indicate that no owner name selection criteria is required; this does not apply when the blktype parameter is set to IOWNERBLK_ALL.
blktype
Specifies the physical block type or system heap storage that information is requested for. Specify one of the following values:
  • IOWNERBLK_ALL (information for common blocks (CMBs), ECBs, 4 KB frames (FRMs), 1 MB frames (FRM1MBs), IOBs, SWBs, and XWBs)
  • IOWNERBLK_CMB
  • IOWNERBLK_ECB
  • IOWNERBLK_FRM
  • IOWNERBLK_FRM1MB
  • IOWNERBLK_IOB
  • IOWNERBLK_SWB
  • IOWNERBLK_SYSHEAP
  • IOWNERBLK_XWB
high
Specifies the number of owners (based on the highest number of blocks or system heap storage owned) to be included in the output for the resources that are specified in the blktype parameter. If the value is 0, all owners are included in the output. If the blktype parameter is set to IOWNERBLK_ALL, this parameter is ignored.

Normal return

TPF_OWNERC_OK is returned.

Error return

TPF_OWNERC_ERROR is returned. The reason for the error is set in errno.
ETPF_OWNERC_BADHIGH_ERR
A count specified for the high parameter was less than 0.
ETPF_OWNERC_BLKTYPE_ERR
An incorrect block type was specified for the blktype parameter.
ETPF_OWNERC_ECBHEAP_ERR
tpf_ownerc processing could not allocate the required ECB heap storage.
ETPF_OWNERC_MAXHIGH_ERR
A count specified for the high parameter exceeded the maximum allowed value (TPF_OWNERC_HIGH_MAX).
ETPF_OWNERC_NO_OWNER_ALL_ERR
A NULL pointer was specified for the owner parameter but the blktype parameter was set to IOWNERBLK_ALL.
ETPF_OWNERC_OWNER_ADDRESS_ERR
A pointer to an owner name was not an addressable storage location.
ETPF_OWNERC_OWNER_NAME_ERR
The name that was specified for the owner parameter is blank or is a wildcard character.
ETPF_OWNERC_SYSHEAP_ERR
tpf_ownerc processing could not allocate the required system heap storage.
ETPF_OWNERC_WILDCARD_ERR
The wildcard character was specified incorrectly for the owner parameter name.

Programming considerations

  • ECB heap storage is allocated to hold owner information and must be released by the caller by using the free function; otherwise, the ECB heap storage is not released until the ECB exits.
  • This function can affect z/TPF system performance, so use it carefully.
  • ECB owner names are case sensitive and IBM® reserves all owner names that begin with uppercase or lowercase I (I or i).

Examples

None.