| Sun Mainframe Transaction Processing Software Release Notes for AIX Platforms
|
   
|
This chapter briefly describes the changes and enhancements made to the Sun MTP software since the original release of 8.0.0. Most of these changes and enhancements were documented in the updated_user_doc.txt file that shipped with the intervening patch releases. The topics in this chapter are:
VSAM Buffers
Sun MTP has been enhanced to increase the limit on the number of shared buffers that can be configured for a region. Refer to the "Configuration Guidelines" chapter of the Sun Mainframe Transaction Processing Software Configuration Guide for information about shared memory utilization and limits. Note that:
- The VSAM Configuration Table (VCT) field for the number of shared buffers now allows a 6-digit value.
- In the Sun Mainframe Transaction Processing Software Administrator's Guide,
Table 1-2, Sun MTP Resource Definition Limits, indicates that the limit for VSAM buffers is 9,999. This enhancement removes that limitation. However, because the VSAM buffer area is part of Sun MTP's 4-Gbyte addressability, the number of buffers is limited by memory requirements, such as the operating system, Sun MTP, and user applications. Refer to Table 4-3 in the Sun Mainframe Transaction Processing Software Configuration Guide for information about calculating the number of shared buffers for your region.
Support for Micro Focus Sequential Files Larger Than Two Gbytes
To enable the use of Micro Focus sequential files that are greater than 2 Gbytes in size, you must refer to the Server Express documentation for file handler configuration information.
Initializing Static Variables for C Shared Objects
An enhancement to control the initialization of static variables for C language shared objects has resulted in the following documentation changes.
- A new environment variable, KIX_PGM_MODE, has been added. If KIX_PGM_MODE is set to KIX_PGM_MODE=TXSERIES, C programs (shared objects) will get an initial image every time the program is invoked.
If the C programs do not initialize the static variables in the programs, use of this environment variable causes Sun MTP to load a fresh copy of the program each time it is invoked.
|
Note - Setting this environment variable might cause performance degradation.
|
- If you use the CEDA transaction or dfhusdup utility to define program resources, you can now use the RESIDENT option, which is implemented only for C programs, in the following way:
- If RESIDENT is set to YES, the shared object (program) remains attached to the process.
- If RESIDENT is set to NO, every time the program is invoked, the shared object is removed and opened.
|
Note - This implementation of the RESIDENT option is unique to Sun MTP. It is different from the implementation on the mainframe or the implementation in TxSeries on open systems.
|
For example, use the CEDA transaction to define program ABCD01 as non-resident:
CEDA DEFINE GROUP(PAYROLL) PROGRAM(ABCD01) RESIDENT(NO)
|
Source Debuggers Supported on 3270 Clients
Sun MTP has been enhanced to support the use of TN3270 clients and IBM 3270 terminals with source debuggers (Animator and C language) to debug online programs. Refer to the updated version of Chapter 14 in the Sun Mainframe Transaction Processing Software Developer's Guide for information about using this new feature.
C Language Feature to Reduce Virtual Memory Usage
To avoid running out of virtual memory you can set a new environment variable, KIX_PGMTXN_MODE to the value TXSERIES. This setting closes any C language application shared objects when the transaction ends.
|
Note - This environment variable only affects C programs that are defined as type K in the Processing Program Table (PPT).
|
SIT Security
The RDBMS password in the System Initialization Table (SIT) is now encrypted when you save the table to the disk. This ensures that users who have read permission to the sit.tbl file cannot view the database password.
|
Note - Sun MTP will continue to support the old format of the table until the next major release of the software.
|
Application Dump Facility
The Sun MTP application dump facility has been enhanced to include additional diagnostic information in the .prt file that is created when a transaction aborts:
- Memory (local and shared) acquired by means of an EXEC CICS GETMAIN call
- The program stack in reverse order, displaying the program name, working storage, and COMMAREA (if present).
As a result of this enhancement, the documentation on the application dump facility in Chapter 13 of the Sun Mainframe Transaction Processing Software Troubleshooting and Tuning Guide has changed. The changes are as follows:
- In the section "Application Dump Facility," in the list of items contained in the formatted dump file, add the following bullet item:
- Program stack in reverse order.
- Add the following information at the end of the section "Enabling and Disabling the Dump Facility:"
To enable the dumping of shared memory acquired by means of an EXEC CICS GETMAIN call, you must set the environment variable KIXGETMAINDMP. For example, to set the variable in the region setup file:
KIXGETMAINDMP=1;export KIXGETMAINDMP
|
- In the section "Dump File Output," replace the first bullet item ("The dump file displays...") with the following:
- Working storage will be displayed for each program in the stack.
- The COMMAREA will be displayed for programs that have been linked via an EXEC CICS LINK call.
- The GETMAIN SHARED segments represent a region-wide list of memory acquired by means of an EXEC CICS GETMAIN SHARED call.
- The GETMAIN LOCAL segments represent a list of local memory acquired by the transaction process by means of an EXEC CICS GETMAIN call.
- Replace Code Example 13-1 with the following example:
CODE EXAMPLE 4-1 Dump File-- COBOL (1 of 3)
10/29/2003 11:21:32.000 unikixtran0 Formatted Dump File
EXEC CICS ABEND called with ABCODE(NEST)
Transaction: NST9 has abended in Program: NESTABC
Failure occurred in Sun MTP code
CICS Command Level Trace:
Function ABEND CID# 00000086 Incomplete
Function LINK CID# 00000091 Condition Successful
Function GETMAIN CID# 00000090 Condition Successful
Function GETMAIN CID# 00000085 Condition Successful
Current address on heap (36dd48)
Address of Shared Memory (ee000000)
Address of Max Core (ee000000)
Address of Threshold Memory (edf80000)
****************** Exec Interface Block ******************
EIBTIME 0112131c EIBSYNC 00
EIBDATE 0103302c EIBFREE 00
EIBTRNID NST9 EIBRECV 00
EIBTASKN 0000002c EIBSEND 00
EIBTRMID C000 EIBATT 00
DFHEIGDI 0000 EIBEOC 00
EIBCPOSN 0004 EIBFMH 00
EIBCALEN 0009 EIBCOMPL 00
EIBAID 27 EIBSIG 00
EIBFN 0e0c EIBCONF 00
EIBRCODE 000000000000 EIBERR 00
EIBDS EIBERRCD 00000000
EIBREQID EIBSYNRB 20
EIBRSRCE EIBNODAT 00
EIBRESP 00000000
EIBRESP2 00000000
********************************* CWA ********************************
No Common Work Area present
********************************* TCTUA ******************************
TCTUA LENGTH = 255
ee201ee0 00000000 20202020 20202020 20202020 20202020 * *
ee201ef0 00000010 20202020 20202020 20202020 20202020 * *
ee201f00 00000020 20202020 20202020 20202020 20202020 * *
ee201f10 00000030 20202020 20202020 20202020 20202020 * *
ee201f20 00000040 20202020 20202020 20202020 20202020 * *
ee201f30 00000050 20202020 20202020 20202020 20202020 * *
ee201f40 00000060 20202020 20202020 20202020 20202020 * *
ee201f50 00000070 20202020 20202020 20202020 20202020 * *
ee201f60 00000080 20202020 20202020 20202020 20202020 * *
ee201f70 00000090 20202020 20202020 20202020 20202020 * *
ee201f80 000000a0 20202020 20202020 20202020 20202020 * *
ee201f90 000000b0 20202020 20202020 20202020 20202020 * *
ee201fa0 000000c0 20202020 20202020 20202020 20202020 * *
ee201fb0 000000d0 20202020 20202020 20202020 20202020 * *
ee201fc0 000000e0 20202020 20202020 20202020 20202020 * *
ee201fd0 000000f0 20202020 20202020 20202020 202020 * *
********************* GETMAIN SHARED MEMORY **************************
LENGTH=10
ee1ff7c0 00000000 73737373 73737373 7373 *ssssssssss *
********************* GETMAIN SHARED MEMORY **************************
LENGTH=10
ee1ff760 00000000 73737373 73737373 7373 *ssssssssss *
********************** GETMAIN LOCAL MEMORY **************************
LENGTH=10
3656c8 00000000 6C6C6C6C 6C6C6C6C 6C6C *llllllllll *
********************** GETMAIN LOCAL MEMORY **************************
LENGTH=10
364ae0 00000000 6C6C6C6C 6C6C6C6C 6C6C *llllllllll *
****************************** PROGRAM STACK **************************
PROGRAM: NESTABC
WORKING STORAGE
36bcf0 00000000 20202020 20202020 * *
PROGRAM: NEST2L
WORKING STORAGE
36b390 00000000 20202020 20202020 4E455354 324C2020 * NEST2L *
36b3a0 00000010 20202020 20202020 * *
COMMAREA
COMMAREA LENGTH: 9
368e38 00000000 4E455354 354C2020 20 *NEST5L *
PROGRAM: NEST5L
WORKING STORAGE
3669f8 00000000 20202020 20202020 0000000A 20202020 * .... *
COMMAREA
COMMAREA LENGTH: 9
365cd0 00000000 4E455354 394C2020 20 *NEST9L *
PROGRAM: NEST9L
WORKING STORAGE
3669f8 00000000 20202020 20202020 0000000A 20202020 * .... *
COMMAREA
No commarea present
|
CICS API Support
This section describes changes to the support for the EXEC CICS API. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide for additional information about supported commands.
EXEC CICS ASKTIME
The description of the EXEC CICS ASKTIME command in the Sun Mainframe Transaction Processing Software Developer's Guide has changed.
- The general description of the command should be as follows:
ASKTIME updates the fields EIBDATE and EIBTIME in the EXEC Interface Block (EIB) with the current date and time. ABSTIME returns a double word value that is the time, in milliseconds, since 00:00:00.000 hours on January 1, 1900 rounded to the nearest hundredth of a second.
- The following statement only refers to non-Sun platforms:
"On some platforms, the three least significant digits of this value (the milliseconds) are always zero."
With the corrected code, the three digits might be zero, but it will be because that is the time when the code executed, or as the result of rounding.
EXEC CICS INQUIRE FILE
Support has been added for the KEYLENGTH and KEYPOSITION options to the EXEC CICS INQUIRE FILE command.
|
Option
|
Description
|
|
KEYLENGTH(data-area)
|
Returns a fullword binary field indicating the length of the record key for a file associated with a VSAM KSDS dataset.
- If the file is closed and the key length is not defined in the file definition, the value returned is 0 (zero).
- If the file is closed and a key length is defined on the file definition, the value from the file definition is returned.
- If the file is open, the key length value is returned from the associated dataset.
|
|
KEYPOSITION(data-value)
|
Returns a fullword binary field indicating the starting position of the key field in each record relative to the beginning of the record. The start is made at position 0. If there is no key, or if the file is not open, a value of zero for the key position is returned.
|
EXEC CICS INQUIRE TDQUEUE
Support has been added for the following options to the EXEC CICS INQUIRE TDQUEUE command:
|
Option
|
Description
|
|
ATIFACILITY(cvda)
|
Supported for intrapartition transient data queues (TDQs) only. Returns a value indicating whether a terminal is associated with the queue. The value NOTERMINAL means there is no terminal associated with the queue. The value TERMINAL means there is a terminal associated with the queue. The value NOTAPPLIC means that the queue is not an intrapartition queue.
|
|
ATITERMID(data-area)
|
Supported for intrapartition TDQs only. If a terminal is associated with the queue, returns the terminal's 4-character name. Otherwise, it returns blanks. The terminal name is defined in the Intrapartition Destinations screen of the Sun MTP Destination Control Table (DCT).
|
|
INDIRECTNAME(data-area)
|
Sun MTP always returns blanks.
|
|
IOTYPE(cvda)
|
Supported for extrapartition TDQs only. Returns a value indicating the queue's I/O type. The value INPUT means input. The value OUTPUT means output. The value NOTAPPLIC means the queue is not an extrapartition queue.
|
|
RECORDFORMAT(cvda)
|
Supported for extrapartition TDQs only. Returns a value indicating whether the queue has fixed or variable-length records. The value FIXED means fixed-length records. The value VARIABLE means variable-length records. The value NOTAPPLIC means the queue is not an extrapartition queue.
|
|
RECORDLENGTH(data-area)
|
Supported for extrapartition TDQs only. Returns the record length in bytes for queues with fixed-length records, and the maximum record length for queues with variable-length records.
|
|
RECOVSTATUS(cvda)
|
Supported for intrapartition TDQs only. Returns a value indicating the recovery type. The value LOGICAL means the queue is recoverable. The value NOTRECOVERABLE means the queue is not recoverable. The value NOTAPPLIC means the queue is not an intrapartition queue.
|
|
REMOTENAME(data-area)
|
Supported for remote TDQs only. Returns the 4-character name of the remote queue. This is the value of the RmtName field in the Remote Destinations screen of the DCT. If a remote queue is not defined, blanks are returned
|
|
REMOTESYSTEM(data-area)
|
Supported for remote TDQs only. Returns the 4-character name of the system where the remote queue is located. This is the value of the SysID field in the Remote Destinations screen of the DCT. The remote system must also be defined in the System Entries portion of the Terminal Control Table (TCT).
|
The following option is not supported:
RDBACK
EXEC CICS INQUIRE TSQUEUE
INQUIRE TSQUEUE(data-value)
[LOCATION(cvda)]
[NUMITEMS(data-area)]
[RECOVSTATUS(cvda)]
The EXEC CICS INQUIRE TSQUEUE is supported with the exceptions noted. INQUIRE TSQUEUE returns information about the specified temporary storage queue.
|
Option
|
Description
|
|
LOCATION(cvda)
|
Returns a value indicating where the temporary storage queue is located. A value of AUXILIARY means that the queue is in permanent storage. A value of MAIN means that the queue is in main memory.
|
|
NUMITEMS(data-area)
|
Gives the number of items in the queue.
|
|
RECOVSTATUS(cvda)
|
Returns the recovery status. A value of RECOVERABLE means the queue is recoverable. A value of NOTRECOVERABLE means the queue is not recoverable.
|
|
TSQUEUE(data-value)
|
An 8-character queue name.
|
To browse through all of the temporary storage queues in the region, use the following options on the INQUIRE TSQUEUE command:
|
Option
|
Description
|
|
START
|
Starts the browse operation.
|
|
AT(data-value)
|
Used with the START option to identify the name of the resource that is the starting point for the browse operation.
|
|
NEXT
|
Retrieves the next resource.
|
|
END
|
Stops the browse operation.
|
If an INQUIRE TSQUEUE NEXT command is unable to acquire enough local memory, a response code of NOSTG is returned. This response code is specific to Sun MTP and corresponds to error message KIX7707F. See New Messages for a description of this message.
The following options are not supported:
|
FLENGTH
|
LASTUSEDINT
|
MAXITEMLEN
|
|
MINITEMLEN
|
TRANSID
|
|
|
Note - If you are using Sun MTP Secure and an external security manager, note the following addition to Table 8-4 in the Sun Mainframe Transaction Processing Software Administrator's Guide. The TSQUEUE resource is subject to security checking. Therefore, it must be added to the table in the Resource Name column. The EXEC CICS INQUIRE TSQUEUE command must be added to the Command column of the table, and Read must be added to the Permissions column.
|
EXEC CICS RETURN
Support has been added for the INPUTMSG and INPUTMSGLEN options to the EXEC CICS RETURN command. These options are supported only when the TRANSID and IMMEDIATE options are also specified on the RETURN command. Other uses of the INPUTMSG and INPUTMSGLEN options have not been validated.
|
Option
|
Description
|
|
INPUTMSG(data-area)
|
The data to be passed to the transaction identified in the TRANSID option.
|
|
INPUTMSGLEN(data-value)
|
Indicates the length of the data in INPUTMSG.
|
New Environment Variables
Refer to the appropriate section for information about these new environment variables.
Enhancements to Utilities and Commands
This section briefly describes the new utilities in Sun MTP Release 8.0.1 and new support in existing utilities. Detailed information about the utilities is provided in the Sun Mainframe Transaction Processing Software Reference Guide.
kixsalvage Utility
The kixsalvage utility has been enhanced to include the -T option, which dumps records from all segments of a spanned VSAM file in parallel.
|
Note - Because the syntax of the kixsalvage command was incorrectly documented in the Sun Mainframe Transaction Processing Software Reference Guide, complete documentation is included here.
|
The kixsalvage utility scans and dumps all salvageable data from a corrupted VSAM file to a new file or files. By default, the data is written out in the Sun MTP recordv format. Refer to Chapter 3 in the Sun Mainframe Transaction Processing Software Administrator's Guide for a definition of the recordv format. As an alternative, use the -c option to specify the Micro Focus variable record output format. In both cases, you must sort the output file or files.
Format to scan files:
kixsalvage [-s] [-v] datasetname
Format to salvage files:
kixsalvage [-2 | -c] [-T | -l size] [-v] [-r] [[-o outputfile]...] datasetname
|
Option
|
Description
|
|
-2
|
Writes a 2-byte record header instead of the default 4-byte record header. This option is incompatible with the -c option.
|
|
-c
|
Writes the output file in the Micro Focus variable record format.
|
|
-l size
|
Indicates the maximum length, in bytes, for an output file. You can modify the size with G, K, and M, indicating GB, KB, and MB, respectively. If you specify a value that is too small, you might end up with too many output files or exceed the number of allowed output files.
The -l option is ignored if the -T option is used.
|
|
-s
|
Performs a scan only to display the number of blocks and records that are salvageable. This enables you to determine the number and size of output files that are required. Use this information to determine if the file is worth salvaging.
|
|
-v
|
Activates the verbose flag. With the verbose flag set, the program writes a line of data to the screen for each record that is salvaged.
|
|
-r
|
Converts the data to machine format. Only for use on reverse- byte systems.
|
|
-T
|
Dumps all the file's data segments in parallel. When using the -T option, you must specify an output file (-o option) for each segment of the spanned file. If the count of output files is not correct, kixsalvage terminates with an error. See Example 4.
Do not use the -T option with the -l option.
|
|
-o outputfile
|
Identifies the output file name(s); up to eight names.
- If an output file name is not supplied on the command line, kixsalvage uses the name of the input dataset and appends the suffix .slvgnnn. See Example 1.
- If an output file name is supplied on the command line, kixsalvage uses that name.
- If kixsalvage has to generate additional output files, it adds the .slvgnnn suffix to the additional files. See Example 2.
- If the -l option is used, and the number of output files specified on the command line cannot hold the salvaged data, kixsalvage generates additional files using the name of the last output file specified and appends the .slvgnnn suffix to these additional files. See Example 3.
The format of the suffix is *.slvgnnn, where nnn is a 3-digit value from 000-999.
|
|
datasetname
|
Indicates the file name of the dataset to salvage. This parameter is required.
|
The following command-line examples show how kixsalvage generates its output files:
Example 1: This command does not use either the -o or -l options.
The kixsalvage utility generates an output file named ACCTFIL.slvg000.
Example 2: This command does not use the -o option.
$ kixsalvage -l1M ACCTFIL
|
The kixsalvage utility generates the following output files to hold the number of one-megabyte files needed to dump the entire dataset:
ACCTFIL.slvg000
ACCTFIL.slvg001
ACCTFIL.slvg002
ACCTFIL.slvg003
|
Example 3: This command does not have enough user-specified files to accommodate the number of one-megabyte files needed to dump the entire dataset.
$ kixsalvage -l1M -oacctfil1 -oacctfil2 ACCTFIL
|
Therefore, kixsalvage generates the following output files:
acctfil1
acctfil2
acctfil2.slvg000
acctfil2.slvg001
|
Example 4: This command illustrates the use of the -T option.
$ kixsalvage -T -o /p1/acctfil -o /p2/acctfil \
-o /p3/acctfil -o /p4/acctfil \
-o /p5/acctfil -o /p6/acctfil \
-o /p7/acctfil -o /p8/acctfil \
ACCTFIL
|
In this example, the ACCTFIL dataset is a very large eight-segment spanned file. Each output file (named acctfil) is directed to a different directory, which can be on a different disk or file system, as follows:
/p1/acctfil
/p2/acctfil
/p3/acctfil
/p4/acctfil
/p5/acctfil
/p6/acctfil
/p7/acctfil
/p8/acctfil
|
When using the -T option, each segment of the spanned file is processed by a separate process, which enhances performance.
kixsnap Utility
|
Note - The kixsnap command syntax has not changed.
|
There are two major changes to the kixsnap utility:
- The kixsnap utility also executes the Sun MBM ebmsnap utility, if the Sun MTP region is associated with a Sun MBM node.
- The name and packaging of the kixsnap utility output file has changed.
To ensure that the output of the kixsnap command contains all relevant information about the region, run the kixsnap command as the user ID of the user that started the region.
The kixsnap utility now generates a file in one of the following packages, depending on the compression utility it finds on your system:
- snapshot.mmdd_hhmmss.tar.gz
- snapshot.mmdd_hhmmss.tar.Z
- snapshot.mmdd_hhmmss.zip
When you execute the kixsnap command, a message indicating the location and name of the snapshot file is displayed. For example:
$ kixsnap
Writing snapshot to /users/payroll/sys/debugkix/snapshot.0226_083312.tar.gz
|
|
Note - When a system crash occurs, the kixsnap utility is executed automatically. However, it might not be able to display the directory and file name. You can search for the file in the $KIXSYS/debugkix directory, the $KIXSYS directory, or in the directory specified in the KIXSNAPDIR environment variable, if you set that variable for your region.
|
Make sure to send the snapshot file to your authorized service provider for analysis.
unikixbld Utility
There are two enhancements to the unikixbld utility.
Duplicate Records
Previously, unikixbld would build without error a VSAM dataset that had "duplicates not allowed" specified in the File Control Table (FCT) for the alternate key dataset, even when duplicate alternate keys existed in the input data.
Now, unikixbld recognizes the duplicate condition, stops the build, and writes error messages to the unikixmain.err file.
The following example shows some of these error messages:
CODE EXAMPLE 4-2 Duplicate Record Error Messages
04/08/2003 11:48:39 unikixbld0 :KIX9169E Duplicate alt key VSAM dataset:ACCTIX
altkey dataset:ALT3
58 58 58 58 58 58 58 58 58 34 41 41 41 41 41 41 'XXXXXXXXX4AAAAAA'
41 'A...............'
41 41 41 41 41 41 41 41 41 30 'AAAAAAAAA0......'
04/08/2003 11:48:39 unikixbld0 :KIX1169E [build] Build failed for VSAM Alternat
e Index
04/08/2003 11:48:39 unikixbld0 :KIX9169E Duplicate alt key VSAM dataset:ACCTIX
altkey dataset:ALT2
47 52 45 45 4E 46 49 45 4C 44 20 20 31 30 30 30 'GREENFIELD..1000'
32 '2...............'
47 52 45 45 4E 46 49 45 4C 'GREENFIEL.......'
04/08/2003 11:48:39 unikixbld0 :KIX1169E [build] Build failed for VSAM Alternat
e Index
|
Support for mfrcdv Record Format
The unikixbld utility has been enhanced to support the mfrcdv format for the following:
- Multiple input files with the -m option (merge)
- Multiple output files
- Replace and reuse arguments
The unikixbld utility no longer issues the following fatal error message:
KIX1228F -m option is only used for line, record or recordv format
|
unikixmain Command
The following options have been added to the unikixmain (kixstart) command.
-O Option
-O TDINTRA=[NOEMPTY|EMPTY]
This option specifies whether recoverable intrapartition TD queues are to be discarded at region startup. If the option is not specified, the default is NOEMPTY.
Valid arguments are:
|
Argument
|
Description
|
|
EMPTY
|
Indicates to discard the queues.
|
|
NOEMPTY
|
Indicates that the records on the queues are to be retained. This is the default.
|
-q Option
-qvalue
This option overrides the default block size (512 bytes) for temporary storage queues that are written to memory. The valid values for the -q option are: -q1 for 1-Kbyte blocks, -q2 for 2-Kbyte blocks, -q4 for 4-Kbyte blocks, -q8 for 8-Kbyte blocks, -q16 for 16-Kbyte blocks, and -q32 for 32-Kbyte blocks. See Managing Temporary Storage Queues for more information.
| Sun Mainframe Transaction Processing Software Release Notes for AIX Platforms
|
817-5614-10
|
|
Copyright © 2004, Sun Microsystems, Inc. All rights reserved.