SNA Services: Adjust to the relocation of the VTAM internal trace table

Description: Starting with z/OS V1R13, the VTAM internal trace (VIT) table is relocated from ECSA to HVCOMMON and the VIT data space is eliminated. As a result, be aware of the following changes starting in z/OS V1R13:

Tip: By applying the PTF of APAR OA41908 (z/OS V1R13) and APAR OA42180 (z/OS V2R1), the output from DISPLAY BFRUSE command was enhanced to include the current HVCOMM storage usage, maximum storage usage counters and constant of 2048 megabytes for the HVCOMM storage limit for the VTAM Internal trace (VIT) table.

Element or feature:

Communications Server.

When change was introduced:

z/OS V1R13.

Applies to migration from:

z/OS V1R12.

Timing:

Before the first IPL of z/OS V2R1.

Is the migration action required?

Yes, if one or more of the following conditions are true:

If automation of the MODIFY TRACE command exists and the command specifies SIZE in pages or DSPSIZE, and the failure of that command is unacceptable.
If automated applications that parse retired messages not finding any of the newly retired messages is unacceptable.

Target system hardware requirements:

None.

Target system software requirements:

None.

Other system (coexistence or fallback) requirements:

None.

Restrictions:

Valid SIZE values are 4M-2048M inclusive.
If you specify a SIZE value that is larger than the default value, z/OS will perform paging on portions of the VIT table. Before you specify a large SIZE value, ensure that you have sufficient real or auxiliary storage to contain the entire VIT. Failure to ensure sufficient storage might result in an auxiliary storage shortage. If an SVC dump is taken that includes common storage, the size of the dump data set also increases. You must also take the increase in the size of the dump data set into consideration.

System impacts:

Moving the VIT to HVCOMMON can make up to 999 pages of ECSA available to other applications or subsystems.

Related IBM Health Checker for z/OS check:

None. The VIT associated health checks have been removed. See Update your check customization for modified IBM Health Checker for z/OS checks for more information.

Steps to take: Follow these steps:

Migrate your VTAM start lists:
Although the VTAM internal trace (VIT) table size is now specified in megabytes and the DSPSIZE parameter is no longer valid, you are not forced to update your VTAM start lists before using z/OS V1R13. If you use a nonzero DSPSIZE value in your start list, your tracing capacity will be diminished unless you perform these migration tasks. You should convert your SIZE value to megabytes and delete your DSPSIZE specification.
Migrate your automated MODIFY TRACE commands:
Unlike the VTAM start lists, the migration of any automation of the MODIFY TRACE command that specifies the value of the SIZE parameter in pages or the DSPSIZE parameter is required before using z/OS V1R13 if the failure of that command is unacceptable. If you fail to perform this migration effort, the automated command will be rejected, the size of the table will remain unchanged, and any other modifications specified on the command (for example, opt=all) will be ignored.
Migrate your TRACE option or MODIFY TRACE command when they specify the SIZE parameter, the DSPSIZE parameter, or both parameters:
1. If DSPSIZE=0 is specified, delete the specification. If the SIZE parameter is also specified or you want a table size larger than 4 megabytes, proceed to steps 2, 3, and 4.
2. If DSPSIZE is not specified, specify the SIZE value as the number of megabytes you want in your trace table (4 megabytes minimum, for example, SIZE=4M). Regardless of the size of the VIT, only a few megabytes are backed by 64-bit real storage. This range of fixed pages is dynamically shifted as VIT records are written. The migration task is complete for this start list or automated command.
3. If the DSPSIZE parameter is specified and the SIZE parameter is not, change DSPSIZE to SIZE and change the value to the number of megabytes you want in your trace table (4 megabytes minimum). If you want to retain the equivalent of what was specified for DSPSIZE, specify the SIZE value as the DSPSIZE value and append '0M'. For example, DSPSIZE=1 is equivalent to SIZE=10M. The migration task is complete for this start list or automated command.
4. If the DSPSIZE and SIZE parameters are both specified, delete the DSPSIZE specification and change the value of the SIZE parameter to the number of megabytes you want in your trace table (4 megabytes minimum). If you want to retain the equivalent of what was specified for the DSPSIZE parameter, change the value of the SIZE parameter to the DSPSIZE value and append '0M'. For example, DSPSIZE=3 is equivalent to SIZE=30M.
Migrate applications that parse retired messages:
If you have automation that parses the output from the MODIFY TRACE, DISPLAY TRACE, or DISPLAY STATS command, you might need to update them because the VIT size is now reported in megabytes. Also, you will no longer see DSPSIZE reported as the VIT data space has been removed.
In addition, numerous messages are retired because they no longer apply. As a result, perform the following steps:
- If you run automation that parses the output of the MODIFY or DISPLAY TRACE command, change the automation to process megabytes instead of pages.
  Previous message: IST315I VTAM INTERNAL TRACE ACTIVE - MODE = INT, SIZE = size PAGES
  
  Updated message: IST315I VTAM INTERNAL TRACE ACTIVE - MODE = INT, SIZE = size MB
- If you run automation that parses the output of the DISPLAY STATS command, change the automation to process megabytes instead of pages.
  Previous message: IST1227I 2 999 = VIT TABLE SIZE
  
  Updated message: IST1227I 2 4 = VIT TABLE SIZE
  
  Also, you will no longer see the following message because the VIT data space has been removed:
  
  IST1227I 163 0 = VIT DATA SPACE TABLE SIZE
- If you run automation that parses any of the following messages, delete the automation because the messages are either retired or no longer used for the VIT.
  IST318I VTAM INTERNAL TRACE ACTIVATION FAILED -- UNABLE TO FIX STORAGE
  
  IST495I type HAS BEEN SET TO value
  
  IST1659I DATA SPACE dspname DSPSIZE = dspsize actsize
  
  IST1741I DATA SPACE SDUMPX FAILED WITH RETURN CODE code REASON reason
  
  ISTH003I The VTAM Internal Trace (VIT) table size is at the maximum value, which provides optimal trace information for problem determination
  
  ISTH004E VTAM Internal Trace (VIT) table size of vit_size is too small
  
  ISTH007I VTAM Internal Trace (VIT) dataspace size is at the maximum value, which provides optimal trace information for problem determination
  
  ISTH008E VTAM Internal Trace (VIT) dataspace size of dspsize is too small
  
  IVT5602I DATA SPACE SDUMPX FAILED WITH RETURN CODE code REASON reason
Other automation:
If you have automation that parses for or specifies the character string ISTITDS1, which prior to z/OS V1R13 was the name of the data space containing the VIT data space, you might want to modify that automation because the data space will no longer be created. This is highly recommended if you have SLIP traps that dump the VIT data space.
Note:
- Failure to remove the DSPNAME for non-existent data spaces can result in an error message but should not preclude the running process.
- Check for dump commands that use DSPNAME=('VTAM'.ISTITDS1) and remove the DSPNAME parameter. Note that VTAM uses additional data spaces, so you should not remove any DSPNAME parameter that specifies a wildcard data space name.
- Because FFST dumps do not include data spaces, they are not affected.

Reference information: For information, see the following:

See TRACE for MODULE, STATE (with OPTION), or VTAM internal trace in z/OS V2R1.0 Communications Server: SNA Resource Definition Reference for additional information about specifying the size of the VTAM internal trace (VIT) table using the VTAM TRACE start option.
See MODIFY TRACE command in z/OS V2R1.0 Communications Server: SNA Operation for additional information about specifying the size of the VTAM internal trace (VIT) table using the MODIFY TRACE command.