Tips for debugging TPX Batch Administration Facility errors

Products

• TPX - Session Management
• Vman Session Management for z/OS

Issue/Introduction

The TPX batch job has ended in a non-zero return code.  Here are some tips on how to assess and debug this situation. The Batch component of TPX allows you to report on and update information in the TPX Administration database (VSAM files). See Batch Administration.

Environment

Release: 5.4
Component: TPX for Z/OS

Resolution

Items to check:

• Review JESMSGLG, JESJCL and JESYSMSG for JCL errors within the batch job.
• Review LOG DD output of the TPX batch job (not the TPX started task):
  
  • Identify which SYSIN statements are generating the errors/messages.
  • Check the Message Reference area shown below for details on TPXLxxx log messages.
  • If you cannot find the LOG output, check the JESJCL to identify the SYSOUT class.  You may need to add a LOG DD override to your JCL with SYSOUT=* to send the LOG to the same JES output class as the JESMSGLG.
• Are all brackets matched pairs?
  
  • Since TPX batch does not require continuation characters to use more than one line for a SYSIN statement, a missing bracket can have perplexing results such as RC 24 or COND CODE 0024 with no additional messages for clues.
  • For example, a missing open bracket will cause TPX to continue scanning for the expected parameter list.  This can result in REQUIRED PARAMETER LIST MISSING or UNKNOWN COMMAND errors.  
• Do any values need to be enclosed within single quotes?
  
  • If variable values include blanks or special characters, try enclosing extract values within single quotation marks.
  • Report statements require the use of single quotes.  Refer to the Format Your Reports area below in the TPX Session Management 5.4 Guide.
• Is the non-zero return code valid for the situation?
  
  • For example, if you extract on PROFILES AND ALL SESSIONS your extract file will contain the profile record and one or more profile session records.  If you then UPDATE PROFILESESSION using the extract file, TPX will attempt to update every extracted record. You may have an error flagged on the update of the profile record if the variable being updated only exists in the session records and not on the profile record.  This would be an acceptable non-zero return code, usually RC 8.

General tips:

• When creating a TPX batch job, start with simple extract parameters until successful then build upon those. For example, extract one userid or profile to validate that the JCL and PROC work as expected.
• Use REPORTs
  
  • Prior to making any changes to a file, run an EXTRACT and REPORT using that extracted file to ensure that you will process what you expect.
  • EXTRACT/REPORT before and again after any UPDATE or DELETE to verify the changes that you intended to make match the end result.
• Ideally, test your TPX batch jobs on a test TPX system prior to making the changes in production.
• ALWAYS back up your production VSAM files prior to making extensive or even simple, yet sensitive changes via batch.  
  
  • It is a best practice to stop the TPX started task when taking VSAM backups.  This will ensure that there are no changes made during the time the backup is running.  You will need to weigh the impact of stopping the started task against the impact of the change or potential need for fallback.
• Search "TPX batch example" for existing knowledge documents that may be similar to what you are trying to accomplish.  These can also inspire you to the things that can be accomplished with TPX batch processing
• Batch Administration examples can be found in the HLQ.CB0VSRC PDS. There is in index member $BATADMN listing the examples and what they do.

Additional Information

Product Documentation:
TPX 5.4 Batch Administration
TPX 5.4 Message Reference Guide
TPX 5.4 Batch Reporting - Format your Reports