Sun Mainframe Transaction Processing Software, Release 8.0.0
Updated User Documentation

This file contains updates to the user documentation
released with MTP 8.0.0. If there are no documentation
updates for a patch release, it is so noted.

--------------------------------
MTP 8.0.0p2    -   112750-02
--------------------------------

Sun MTP 8.0.0p2

1. The Release Notes contained question marks rather than the appropriate text 
for the description of the kixbms -A enhancement (BugId 4783941). The first 
sentence of the "kixbms" section on page 10 of the Sun MTP Software Release
Notes (part number 816-5335-10) should be as follows:

A new option has been added to support the XINIT option of the DFHMDF macro.

2. The following sections in Appendix A of the Sun MTP Software Configuration 
Guide (Revenue Release version) incorrectly identify the keypad multiply key 
as a lowercase j (j). The correct symbol is the asterisk (*). (BugId 4778203)

NCD-101 Key Keyboards
VT-type Keyboards
Sun Keyboards
Default X Keyboards
Desktop Terminal Keyboards 

3. The following restriction applies when using a Sybase database (BugId 
4783228).

  A Sun MTP region connecting to a Sybase database can only provide Sybase
  interface support for either COBOL or C. If you need to access a Sybase 
  database from both C and COBOL programs, you must create two regions, 
  one for C and one for COBOL.

4. Added support 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 in the RETURN command. Other uses of the INPUTMSG 
and INPUTMSGLEN options have not been validated. (BugId 4769267)

  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.

5. Added support for the EXEC CICS INQUIRE TSQUEUE command. Not all options are 
supported. The kixclt translator issues warning messages for unsupported 
options. (BugID 4769270)

  - The supported options are:

    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 count of 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 name of the queue.
    
    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 you are using Sun MTP Secure and an external security manager, note
    the following addition to Table 8-4 in the Sun MTP Administrator's 
    Guide. The TSQUEUE resource is subject to security checking. Therefore,
    it should be added to the table in the Resource Name column. The 
    EXEC CICS INQUIRE TSQUEUE command should be added to the Command
    column of the table, and Read should be added to the Permissions
    column.
  

6. Added support for options to the EXEC CICS INQUIRE TDQUEUE command. 
(BugId 4769346)

  In addition to the currently supported options, the following options are
  now supported:

  ATIFACILITY(cvda) - Supported for intrapartition 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
  Destination Control Table (DCT). Note that 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


7. The documentation for the EXEC CICS INQUIRE TASK and the 
EXEC CICS INQUIRE TASK LIST command (documented in the Sun MTP Developer's 
Guide) contains errors (BugId 4787620). The corrected documentation is as 
follows:

  INQUIRE TASK(data-value)
        [FACILITY(data-area)]
        [FACILITYTYPE(cvda)]
        [PROCESSID(data-area)]
        [RUNSTATUS(cvda)]
        [STARTCODE(data-area)]
        [TRANSACTION(data-area)]
        [USERID(data-area)]

  This command retrieves information about a specified user 
  task. User tasks are those associated with user-defined 
  transactions or with MTP-supplied transactions that are 
  usually invoked by an operator.

  FACILITY - Returns a 4-character string representing the 
  name of the facility associated with the named task. If the 
  task was initiated from a terminal, the name of the terminal 
  is returned. If the task was initiated by a destination 
  trigger level, the name of the associated transient data 
  queue is returned. Otherwise, a null value is returned.

  FACILITYTYPE - Returns a CVDA value indicating the type of 
  facility that initiated the task. Possible values are:

    DEST - task was initiated by a destination trigger level
    
    TASK - task was initiated by another task

    TERM - task was initiated from a terminal

  PROCESSID - Returns a 32-bit binary value indicating the 
  process id of the process (unikixtran) running the 
  transaction associated with the task. Sun MTP-specific option.
 
  RUNSTATUS - Returns a CVDA value indicating whether the task 
  is running. The only supported value is RUNNING.

  STARTCODE - Returns a 2-character string indicating how the 
  task was started. Possible values are:

    D  - DPL request. Program cannot issue I/O requests against 
         its principal facility, nor issue any syncpoint requests.
    DS - DPL request. Same as above, except program can issue 
         syncpoint requests.
    QD - Transient data trigger level
    S  - START command without data
    SD - START command with data
    TD - Terminal input
    QB - Batch request

  TASK - Specifies a task number, in 4-byte packed-decimal format.

  TRANSACTION - Returns a 4-character string containing the 
  name of the transaction (if any) associated with the task. 
  Blanks are returned if there is no associated transaction.

  USERID - An 8-character string identifying the user 
  currently associated with the task.

  The TASKIDERR condition occurs if the specified task cannot 
  be found.


  INQUIRE TASK LIST LISTSIZE(fullword binary data-area)
        [RUNNING]
        [SUSPENDED]
        [SET(pointer)]

  The INQUIRE TASK LIST command returns a list of user tasks as defined 
  to the system. Task states must be specified explicitly.
  
  LISTSIZE - Returns a fullword binary field giving the number of tasks 
  in the categories you included in your inquiry. Required parameter.
  
  RUNNING - Lists only tasks that are actually running (not suspended).
  This includes the issuing task.
  
  SUSPENDED - Lists only tasks that are currently suspended (tasks waiting
  for some event or condition). This excludes the issuing task.
  
  SET - Address of a list of 4-byte packed-decimal task numbers. Each entry 
  in the list identifies a task in one of the requested categories. If 
  there are no tasks in the requested categories, the SET pointer contains 
  a null value.
  
  Note: If neither RUNNING nor SUSPENDED is supplied in the command, all
  tasks are included in the task list.

8. A new environment variable is available for configuring the properties of
the Java(tm) virtual machine (JVM(tm)) used by the unikixadmin daemon. The
tuning options described in this section apply to very large Sun MTP 
configurations. (BugId 4770645)

   Tuning the unikixadmin Daemon for Large Sun MTP Configurations
   
   In certain cases, it might be necessary to define properties to the
   Java virtual machine used by the unikixadmin daemon. Typically, this
   occurs when the administration framework is enabled for a large Sun MTP
   configuration. A large configuration is defined as one consisting of
   several thousand resources, such as 5,000 programs or maps and 10,000
   endpoints.
   
     Defining Properties to the unikixadmin JVM
     
     When it becomes necessary to configure the JVM to support a large
     overhead, the ADMIN_JVM_OPTIONS environment variable is used to
     propagate options to the JVM instance created by unikixadmin. JVM 
     command-line options normally supplied as part of the "java" command
     can be specified by means of the ADMIN_JVM_OPTIONS environment variable.
     Include this environment setting in your region's setup file. If you
     are using multiple objects, make sure to separate the options with
     a space. Each option must be enclosed in single quotes as shown in
     the following examples.
     
     For example, to increase the size of the memory space used to hold 
     Java objects, you must define the size of the Java heap using the 
     '-Xms<n>' and '-Xmx<n>' options. For example, if the size of the 
     Java object pool must be increased to a maximum of 512 MBytes, set 
     the ADMIN_JVM_OPTIONS environment variable as follows:
     
       export ADMIN_JVM_OPTIONS='-Xmx512m'
       
     Configuring the Cache Life Span
     
     The unikixadmin daemon maintains a cache representing the Sun MTP
     resources under management. By default, the cache has a life span of 
     one second. After the cache life span has expired, the cache is
     considered to be stale and a subsequent request for data results in
     a cache refresh. In large configurations, the cost of performing the 
     cache refresh might be expensive. In this case, it is a good idea to 
     increase the life span of the cache. Determine the cache life span in 
     the following way:
     
       1. Calculate the total number of resources in the region (maps,
          programs, terminals, transactions, and so on).
       2. Round up the figure to the next multiple of 5,000.
       3. Use one second for each 5,000 resources.
      
     For example, if the region has 2,000 programs and maps and 5,000
     terminals, set the cache life span to a value of two seconds. To
     set the cache life span, use the cache_lifespan property of the JVM in
     the ADMIN_JVM_OPTIONS environment variable as follows:
     
       export ADMIN_JVM_OPTIONS='-Dcache_lifespan=2'
       
9. In previous releases of the software, an ABORT.prt file would be created
if a region terminated abnormally. Now, if a region crashes, the unikixmain
process executes the kixsnap command automatically, which gathers trace
and dump information. All the information that was written to ABORT.prt is 
now written to the kixsnap snapshot files, and the ABORT.prt file is no
longer created. (BugId 4777171) This software change caused the following
error message to change:

    KIX0157F Writing abort dump to $KIXSYS/ABORT.prt

    has been changed to 

    KIX0157I Executing %s command

      Description: The Sun MTP region is executing the UNIX command
      executable or script specified in the %s variable.
      
      Solution: Informational message; no user action is needed.
      
10. This release provides support for the Oracle(r) 9.2.0 client, and allows
you to run the Oracle RDBMS on a C language-only platform. (BugId 4784573)

11. Changes to the COBOL and C Primer setup files resulted in the
following changes (BugId 4789466).

    Each primer directory ($UNIKIX/test/primer/cobol and $UNIKIX/test/primer/C)
    now contains its own kixprimer setup file, which sets the environment for
    the sample application.
    
    The section "Defining a Region's Environment" in Chapter 2 of the Sun MTP
    Configuration Guide states that the kixprimer setup script is located in 
    the $UNIKIX/bin directory. This sentence should be removed.
    
12. A fix to BugId 4787102 requires a documentation addition. When 
configuring terminals in the 3270 Devices portion of the Terminal 
Control Table, be aware that the Host Name and Port Number fields 
on the Host & Port screen are applicable only for terminals that 
access the region by means of the TPS PU4/5 server software 
(unikixtrin process). These fields are ignored for all other 
terminal definitions.

13. The unikixmain process has been enhanced to handle signals (BugId 4765627).
This resulted in a new error message:

    KIX3830E Received signal [s%] when system was in [%s] mode
    
      Description: The specified signal was received when the system was
      in the specified mode. The modes are as follows:
      
         ABORT - Indicates that the region was in shut immediate mode.
         
         NORMAL, BATCH, QUIESCE, SHUT - Indicates the region mode.
         
         TRANS CLEANUP, MESSAGE CLEANUP, BUFFER CLEANUP, ROLLBACK - These
         modes indicate whether unikixmain was doing cleanup work for an
         aborted transaction processor.
         
       Solution: No user action is needed.

14. Enhancements to Sun MTP product resulted in the following new and 
changed error messages.

    New error messages:
       
    KIX7561I Killing process %d
     
      Description: The kixhashut utility is killing the specified process.
       
      Solution: Informational message; no user action is needed.
       
    KIX7562I Removing IPC %d %d 

      Description: The kixhashut utility is removing IPC [m|s|q] 
      <IPC id number>.
       
      Solution: Informational message; no user action is needed
       
    KIX7563I System shutdown was %s within normal shut down period

      Description: If %s is COMPLETED, then the region completed the
      transactions and the region is coming down. If %s is NOT COMPLETED, 
      some transactions are still being executed; they will be aborted.
       
      Solution: Informational message; no user action is needed

    KIX7564I System shutdown completed, check and release system resources 

      Description: The time allocated for the region to come down has 
      expired. Now force kill the process and remove any remaining 
      processes and IPC resources.
    
      Solution: Informational message; no user action is needed
       
   The following error message has changed:
    
    KIX8602E Job terminating abnormally with shutdown=%s interrupt=%s system=%s

      Description: The job was terminated with one or more of the following
      conditions being TRUE:

        shutdown=TRUE, if the region was brought down immediately or it 
        went into a panic state
          
        interrupt=TRUE, if a signal was sent to terminate the job
          
        system=TRUE if region was stopped.
        
       Solution: Internal error or operator-requested termination.
       
     KIX7504E kixdump did not have permission to send signal to unikixmain
     process, pid number [%d]

       Description: The user who executed kixdump did not have permission to
       find out if the unikixmain process exists.

       Solution: The kixdump utility must be submitted by a user who has
       the privileges to send a signal to the unikixmain process of the
       region. 
       
15. In previous releases of Sun MTP, the kixstop command did not properly
adhere to the normal shutdown and immediate (panic) shutdown process.
(Bug Id 4809230)

With this fix, any command to bring down the region normally (kixstop, 
CEMT PERFORM SHUT, and PF3 on the main menu) will wait for all  
transactions to complete before bringing down the region. If there is a 
long-running transaction or a conversational transaction, the region will
wait until these transactions are finished. At this point, the only way 
to bring down the region is to execute the kixclean command.

If you want the old functionality of either kixstop (which forced the region to
stop by aborting running transactions), CEMT PERFORM SHUT, or PF3
(where these commands immediately shut down the region), you must use one of
the following commands:
   - kixstop -i
   - CSMT SHUT,YES
   - CEMT PERFORM SHUT IMMEDIATE
   
As a result of this fix, the following sections in the Sun MTP Administrator's
Guide and Configuration Guide are no longer accurate.

   In the Administrator's Guide, in Chapter 2: 
   
   - In the section "CSMT," the description of the CSMT SHUT,YES transaction
     should be "Shuts down the region and forces all the users to log off.
     Active transactions are rolled back."
     
   - In the section "Setting the System State," the CEMT SET SYSTEM SHUT
     and CEMT SET SYSTEM SHUT IMMEDIATE transactions are not implemented.
   
   In the Configuration Guide, in Chapter 3:
   
   - In the section "Shutting Down the Sun MTP Server," the description of 
     step 1 ("Invoke the CEMT PERFORM SHUTDOWN transaction ..."), should be
     "Transactions that are active will be allowed to complete normally. 
     No new transactions are allowed to be submitted. No new users can 
     log in."


--------------------------------
MTP 8.0.0p1    -   112750-01
--------------------------------

1. Added support for the KEYLENGTH(data-area) and KEYPOSITION(data-area) 
   parameters to the EXEC CICS INQUIRE FILE command. (BugId 4744167)

2. New error message (BugId 4751419)

KIX0557W Both "-A" and "-B" specified in MTP startup parameters. Possible 
conflict.

Description: Warning message indicating that you used both the -A and -B 
             options to unikixmain (or kixstart) when starting the region.

Cause: When a DBCS conversion table file is specified at region startup 
       (using -B), the first 256 entries in the file represent the single-byte
       character set (SBCS) conversion characters. Therefore, if you also 
       specify the -A option, the SBCS conversion table built from the DBCS
       file will be overwritten. This can cause a mismatch between the 
       double-byte and single-byte character sets.

Solution: Do not use both the -A and -B options when starting a region.

3. Documentation did not include information about compiling C++ programs. 
   (BugId 4767661)

The Sun MTP application run unit is built using the C compiler and loader. If 
an application program is written in C++, you must use the C++ compiler (usually
the CC command), and the required loader to build shared objects that can be
loaded by the transaction servers. The include files provided in the 
$UNIKIX/src/CICS_structures directory are the same for C++ programs.

For example, to build a C++ shared object from the acct00.ccs program, execute 
the following commands:

        kixclt acct00.ccs
        CC -Bdynamic -Kpic -c -Xt -I$UNIKIX/src/CICS_structures -o acct00.0
                 acct00.c
        ld -G -o acct00.so acct00.o

4. Improved error messages to provide information about a region's classpath 
   and library path settings. (BugId 4627246)

KIX0539I has been changed to write the following types of messages to the 
unikixmain.log file:

10/16/2002 10:25:37 unikixtran0 :KIX0539I Java ClassPath has these entries:
10/16/2002 10:25:37 unikixtran0 :   /pkgs/MTP8.0.0/lib/dfjcics.jar
10/16/2002 10:25:37 unikixtran0 :   /pkgs/MTP8.0.0/lib/transMQJMS.jar
10/16/2002 10:25:37 unikixtran0 :   /pkgs/MTP8.0.0/lib/transutil.jar
10/16/2002 10:25:37 unikixtran0 :   /opt/mqm/java/lib/com.ibm.mqjms.jar
10/16/2002 10:25:37 unikixtran0 :   /opt/mqm/java/lib/com.ibm.mq.jar
10/16/2002 10:25:37 unikixtran0 :   /opt/mqm/java/lib/jms.jar

KIX0540I has been changed to write the following types of messages to the 
unikixmain.log file:

10/16/2002 10:25:37 unikixtran0 :KIX0540I Java LibPath has these entries:
10/16/2002 10:25:37 unikixtran0 :   /pkgs/MTP8.0.0/lib
10/16/2002 10:25:37 unikixtran0 :   /opt/mqm/java/lib

5. If you want to write your own security exits, as documented in the Sun 
Mainframe Transaction Processing Software Administrator's Guide, you must use
the source file kxsec_exitsTMPL.c, not kxsec_exits.c. Using (and remaking) the
kxsec_exits.c file (which is the one the documentation says to modify) can 
cause unpredictable errors, and might cause a security breach. (BugID 4760779)

6. Fix to BugId 4753378 removes the restriction described in the Release Notes 
for Release 8.0.0 in the section "User ID Restriction for Batch Jobs With an
ESM Enabled", which contained information about 'kixfile' and 'unikixbld'
requiring KIXSECDFLTUSER to have resource permissions to run.

7. Fix to BugId 4758504 eliminates the known problem on the CBCH transaction 
that was described in the README file that shipped with Release 8.0.0.

8. Fix to BugId 4768957 eliminates the known problem related to unikixstrt 
permissions that was described in the README file that shipped with 
Release 8.0.0. Follow the procedures in the Sun Mainframe Transaction 
Processing Software Installation Guide for setting the permissions on 
unikixstrt.

9. Change to software changes how resource names are prefixed when using 
Sun MTP Secure and an external security manager. (BugId 4763941)

Previously, the application name configured in the System Initialization Table
(SIT), was used as the prefix on all ESM resource access check calls. Because
this approach was incompatible with how CICS prefixes resource names with its 
ESM (RACF), customers with existing CICS/RACF-prefixed resource names would
not be able to directly migrate to MTP Secure (ESM). The change made in this
fix uses the UNIX user ID that started the region as the prefix and adds a "."
to it to form the resource name prefix.

10. If your region contains .lst files for the SNT, PCT, PPT, and FCT that were 
created with versions of Sun MTP prior to this release, AND you do not use 
groups, do not import the .lst files into this release. To ensure that your
.lst files work with this release, do either of the following:

 - In the Table Manager, open each of these tables and export them using
 this release of the software.
        
 OR
        
 - Open each of the existing .lst files (snt.lst, pct.lst, ppt.lst,fct.lst) 
 in a text editor. Locate the group name field. If it does not contain a 
 group name, type at least one space between the back-to-back commas. Do this
 for each entry. Then save the .lst file. Examples are as follows:
        
 In the snt.lst file, the group field is the fourth from the left:
 aaabco,aaabco,abc,,F~YkoiqvotH_\,8000000000000000,0f0f3f,hi ,D,88,,X,11984,N
 Correct it to:
 aaabco,aaabco,abc, ,F~YkoiqvotH_\,8000000000000000,0f0f3f,hi ,D,88,,X,11984,N

 In the fct.lst file, the group field is the eighth from the left:
 TEMPSTG,TEMPSTG,KIXSYS,VSAM,KSDS,C,V,,Y,N,N,,0,0,
 Correct it to:
 TEMPSTG,TEMPSTG,KIXSYS,VSAM,KSDS,C,V, ,Y,N,N,,0,0,

 In the pct.lst file, the group field is the 11th from the left:
 BATCH000,,CBCH,0,1,DEF,N,0,,,,Y,,KIXDFLT
 Correct it to:
 BATCH000,,CBCH,0,1,DEF,N,0,,, ,Y,,KIXDFLT 

 In the ppt.lst file, the group field is the sixth from the left:
 BATCH000,B,,,,,,,F,
 Correct it to:
 BATCH000,B,,,, ,,,F,

(BugId 4744995, and duplicate bug 4744609)

11. Fix to BugId 4738818 resulted in improving two existing error messages and 
adding two new messages to better inform the user about possible problems when
attempting to display a mapset.

  KIX0404T Map set %s unable to load from disk.
  
   Description: Sun MTP was unable to load the physical mapset specified by
   the CICS command from disk.
  
   Solution: Ensure the KIXMAPS environment variable is correct, and check
   that the file is on disk and is not empty.
  
  KIX0405T Map set %s not found in PPT.
  
   Description: The mapset specified in the CICS command does not have an
   entry in the Processing Program Table (PPT).
  
   Solution: Define the mapset in the PPT.
  
  KIX0438T Map set %s is currently disabled.
  
   Description: The mapset specified in the CICS command has been 
   disabled.
  
   Solution: Enable the mapset using the system transaction 
   CEMT SET PROGRAM <mapset> ENABLED.
  
  KIX0439T Map set %s user not authorized to load this map
  
   Description: External security is active and the
   current user does not have the required permissions to load the 
   specified mapset.
  
   Solution: If you want this user to be able to access the mapset, 
   grant the user the required permissions.

12. Fixes to the kixcnvtbl80 utility resulted in the following documentation 
changes. (BugId 4776256)

  Installation Guide - Migrating Tables (page 36)

   To Convert Tables

     Remove step 2 (Delete unikix.dir and its contents, if it exists.)
     Remove step 3 (Delete rdo.dir and its contents, if it exists.)
     Remove step 6 (Re-apply unikix or rdo changes)

    kixcnvtbl80 will now convert the unikix.dir and rdo.dir subdirectories
    automatically if they exist, so the above steps are not necessary.

  Reference Guide - kixcnvtbl80 - Convert Tables (page 22)

   Remove the following lines:
     kixcnvtbl80 creates the $KIXSYS/unikix.dir and $KIXSYS/rdo.dir 
     if they do not already exist.

   This no longer occurs. Those directories are created automatically
   when the region starts, so kixcnvtbl80 does not need to do it.
    
