z/TPFDF PUT 10 Enhancements
DanJacobs 0600007UGV Visits (1754)
z/TPFDF PUT 10 Enhancements
Several enhancements to the z/TPFDF product are available and included with z/TPFDF PUT 10.
PM72950 - Support files with over 100 million fixed file ordinals
With APAR PM72950, various ZFCRU and ZUDFM commands have been adjusted so that these utilities properly handle nine digit ordinal numbers (that is, they can handle up to 1 billion fixed file ordinals in a file). In addition, z/TPF APAR PJ40632 has adjusted the z/TPF recoup status output to properly display ordinal values with 9 significant digits. PJ40632 does NOT need to be installed in order for PM72950 to be installed.
PM81536 - Validate record IDs upon release and improve OPR-DB0100
With the ID parameter on the z/TPF RELFC macro, applications have the ability to specify a verification record ID that is compared to the ID in the record to be released. If the record IDs do not match, a system error is issued and the return is not processed. z/TPFDF is a middleware package that should provide such functionality. That is, it should ensure the correct file ID exists in a pool record before it releases that pool file address. In most parts of z/TPFDF, the block has already been accessed and its ID has been verified before z/TPFDF issues a RELFC on its file address. Therefore, an additional ID check on the RELFC API that is used internally is not needed in those cases. However, there are some routines in large logical record (LLR) and B+Tree processing where file addresses were released without accessing them first.
With APAR PM81536, these routines have been enhanced to validate the file ID before releasing the records in case those records are in use by another database. z/TPFDF LLR release processing has been updated to issue a find and wait on LLIBs and LLDBs to ensure the file ID is valid before releasing the blocks either directly or asynchronously. If an error is encountered, informational dump OPR-DB0189 is issued and the block is not released. The dump is issued only once per LLIB, but the loop to release additional file addresses continues. B+Tree processing has been updated to issue a find and wait on B+Tree nodes to ensure the file ID is valid before releasing the blocks. If an error is encountered, an OPR-DB0189 is issued and the block is not released.
These enhancements provide improved data integrity and diagnostics for database errors.
PM77843 - Improve accuracy of data collection counters
APAR PM77843 improves the accuracy of several z/TPF macro counts in z/TPFDF data collection by updating the z/TPFDF central database routines. For example, all occurrences of CRUSA macros were replaced with a LEVTA call followed by a RELCC call to ensure that the true number of RELCC macro calls are accurate. Similarly, rlcha() calls in B+Tree and LLR routines were replaced with a find/relfc/relcc loop to be able to count the actual number of relfc calls. All of these routines can now modify multiple data collection counters in the heart of the code processing rather than simply at the beginning of the routine. Finally, data collection segments were updated to more accurately calculate the data collection run time.
When running a z/TPFDF data collection after the APAR is loaded, you may notice that several data collection counts may experience (potentially significantly) different values compared to a similar data collection taken before the APAR is loaded.
The following counts may be higher:
CFILE, PFILE, RELFC, DETAC, ATTAC, GETCC, RELCC, CFIND, PFIND, BTFND, LRFIL, LRFND
The following counts may be higher or lower, depending on the application profile:
The following counts may be lower because some of the application programming interface (API) calls previously included in these counts are now included in one of the previously listed counts:
This should be taken into account when you compare results from a data collection run that was done before this APAR is applied to results from a run that was done after this APAR is applied.
PM83026 - C API improvements
APAR PM83026 provides new functionality in the z/TPFDF C APIs in the following areas: T-type LRECs and key lists.
z/TPFDF assembler applications can add, read, and delete T-type LRECs without directly manipulating the underlying W-type (work) file. However, corresponding APIs were not available for use by C/C++ applications.
Using APIs to work directly with t-type files in C/C++ applications provides the following benefits:
APAR PM83026 enhances the key list facility by providing two new C/C++ APIs have been provided:
These APIs save the actual search argument values instead of saving a reference to (address of) the key search argument variable. This allows applications, if they choose to use these APIs, to continue to use key search argument values without needing to be concerned with where the search argument variable was defined. The APIs take the same parameters as the dfkey() and dfkey_nbr() APIs, respectively.
APAR PM88915 addresses this need by introducing new z/TPFDF APIs that read data from an existing z/TPFDF database and write the data to the z/TPF file system.
One new assembler API and two new C/C++ APIs have been provided:
These APIs are similar to the existing DBDSP and dfdsp APIs in that keys are optionally provided and then z/TPFDF processing will select potentially multiple or all LRECs in a subfile to be processed on a single API call. The biggest difference is that instead of simply sending the data to the console, z/TPFDF writes the output to a file system file, which gives the user many more options for processing the data.
Several other parameters can be provided to customize how the data is processed. This includes:
For example, an application could specify that only certain information for all LRECs for a particular customer be copied from a z/TPFDF subfile to the file system, with each LREC separated by a comma.
Several new structured programming macro (SPM) equates (such as DBFSYS_OK) and C/C++ error checking functions (such as DFFSYS_OK) are also provided to interrogate the new return codes, which are set in SW00RT5.
In addition, a new customizable equate (#DF_MAX_FSYS) has been introduced in macro ACPDBE that allows you to limit the size (in bytes) of the file written to the file system.
PM89556 - SDO Metadata Enhancements
This APAR provides various enhancements to service data objects (SDO) metadata processing.
z/TPF APAR PJ41246 is a co-requisite APAR for z/TPFDF APAR PM89556.
These APARs have some migration considerations.
For All Users:
After applying this APAR, you should enter the ZUDFM MLS command to keep the MLS database current with z/TPFDF system file information. Existing MLS information can still be used with this APAR applied, and any MLS information generated with this APAR applied can still be used if this APAR is fallen back.
For SDO Users
If you have DSECTs with labels greater than 20 characters and want to create new metadata for those DSECTs, make sure you enter the ZUDFM MLS command to rebuild MLS information for your database before entering the ZUDFM METADATA CREATE command.
The metadata created by the ZUDFM METADATA CREATE and ZUDFC SDO STOP commands is now saved in the z/TPF file system in UTF-8 format instead of EBCDIC. This metadata should now be FTP'ed off of z/TPF (and transferred back to z/TPF, as necessary) without performing any translation (that is, binary mode should be used instead of ASCII mode). If using the z/TPF Loader to load the metadata to the online file system, the ATOE parameter should not be used. If the wrong transfer mode is used, a ZUDFM METADATA VALIDATE command will detect the problem by generating a message similar to the following:
CSMP0097I 13.42.54 CPU-B SS-BSS SSU-HPN IS-0
UDFM0532E 13.42.54 database METADATA VALIDATION FAIL
REASON: FILE ORGANIZATION NOT VALID FOR FIELD 84
UDFM0541E 13.42.54 database METADATA VALIDATION COMPLETED WITH 1 ERROR(S)
Any metadata that is stored on the z/TPF system that was created before this APAR is applied will not be able to be used with SDO applications or ZUDFM commands. You must re-load the metadata in the correct format to the z/TPF system. Attempting to use existing metadata with an SDO application will result in an error similar to the following:
DFED1002E 15.18.24 readData() CALL FAILED
TEXT=Error converting metadata to EBCDIC
If you have existing metadata that was generated without this APAR and FTPed off of z/TPF in ASCII mode, you can still use this metadata on the z/TPF system by transferring it back to z/TPF in binary mode.
If you use the z/TPF Toolkit to view the metadata files online in the z/TPF file system, make sure that the *.xml file type for Remote Systems Files has a File Transfer Mode set to XML or Binary.
If you need to fallback this APAR, any metadata that was created while this APAR was loaded can still be used if it is FTP'ed back to z/TPF in ASCII mode.
PM97115 - Improve z/TPFDF error handling if a device is not operational
When a device is not operational (that is, IDECSUD is set to equate CXSGNO, or x’88’, after a FIND macro), a DB0100 system error would be generated. If the application attempted to continue to access the device while it was not operational, streaming OPR-DB0100 system errors might occur because every access on that device would fail. In this situation, these system errors are not helpful. It would benefit system resource availability to suppress these system errors.
With APAR PM97115, z/TPFDF system error processing was updated so that in the DB0100 processing, if the value of IDECSUD is CXSGNO (x'88'), dump processing is skipped.