Sun Mainframe Batch Manager Software, Release 10.0.1
Updated User Documentation

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

Note: The acronym CR followed by a number stands for Change Request.

Important Operating Information

   Do not use the "batch_shut" or "batch_start" commands. These commands are 
   used internally by the bam process for starting and stopping nodes. If you
   invoke these commands directly, thread and class configuration information 
   is lost. To manually start or stop a node from the command line (or from a 
   script), you must use the "bam startbatch" or "bam stopbatch" commands.
   Using these "bam" commands ensures that the thread and class configuration
   information is retained. (CR 6254928)

--------------------------------
MBM 10.0.1p8   -  117630-08
--------------------------------
Fixed Problems

1. A fix to CR 6254197, which corrects a problem where the Sun MBM sortx
   utility abended if the SORTIN and SORTOUT files were the same, resulted in
   a documentation change. The second rule in the section "sortx Usage Rules" in
   Chapter 7 of the Sun MBM Migration Guide is no longer true. The new rule is:

   If the input file is a file system (FS) file, you can direct the output file
   to the input file. If the sort is successful, the input file is replaced with
   the output results of the sort. If the sort fails, the input file remains
   unchanged.

2. A fix to CR 6254199, which corrects a problem where the Sun MBM sortx
   utility abended if the SORTIN was not specified, resulted in an additional
   rule for the section "sortx Usage Rules" in Chapter 7 of the Sun MBM 
   Migration Guide. The new rule is:

   If the SORTIN file is missing or not defined (there is no DD_SORTIN), Sun MBM
   defines SORTIN as /dev/null, and the sort continues. The result of the sort
   is an empty SORTOUT file.

3. A fix to CR 6321122, which relates to the integration of Sun MBM with
   SyncSort, resulted in the following documentation changes.

   SyncSort provides native support for Sun MTP VSAM files. Therefore, if
   your subsystem has jobs that must sort VSAM files, you must ensure that
   the version of Sun MTP configured with SyncSort is the same version of Sun 
   MTP that you are configuring with your subsystem. For example, if you
   identified the patch 8 version of Sun MTP 8.0.1 when you installed SyncSort,
   you must use the same version of Sun MTP when you build your subsystem.

   The Sun MBM Migration Guide for Release 10.0.1 (and earlier) contains a
   sample script that shows how to use Syncsort with Sun MTP VSAM files. This
   script was needed with versions of SyncSort earlier than version 3.6.5 to
   support Sun MTPVSAM files. If you are using a minimum release of SyncSort
   version 3.6.5, use the SyncSort directives to sort VSAM files, not the sample
   script. The following examples show the how the SyncSort SYSIN directives can
   be included as either instream data or as an external file.

   Example 1: Instream data
    Note the use of the keyword INDEXED for the VSAM file in the sort directive.
    When using instream data, a backslash is required before the dollar sign of
    variable names so that the UNIX shell does not strip the dollar sign.

   ASSGNDD ddname='SORTIN' dataset='ESDSV01' filename='ESDSV01' type='VS' 
   disp='i-o'

   ASSGNDD ddname='SORTOUT' dataset='ESDSV01SEQ' filename='$FMROOT/ESDSV01SEQ' 
   recsize='200' recfmt='mfrcdv' disp='o' normal='k' abend='d'

   ASSGNDD ddname='SYSIN' type='INSTREAM'  << !
   /infile \$DD_SORTIN INDEXED
   /fields           f1 1 10 character
   /keys             f1
   /outfile \$DD_SORTOUT \$SYNCFMT_SORTOUT \$LRECL_SORTOUT SEQUENTIAL OVERWRITE
   /statistics
   /end
   !

   Example 2: SYSIN file

   ASSGNDD ddname='SORTIN' dataset='ESDSV01' filename='ESDSV01' type='VS' 
   disp='i-o'

   ASSGNDD ddname='SORTOUT' dataset='ESDSV01SEQ' filename='$FMROOT/ESDSV01SEQ'
   recsize='200' recfmt='mfrcdv' disp='o' normal='k' abend='d'

   ASSGNDD ddname='SYSIN' dataset='syncsortin' filename='$FMROOT/syncsortin'

   The SYSIN file contents are shown below. 
     Note - When SYSIN is defined in an external dataset, not as instream data,
     backslashes are not required before the dollar sign on variable names.

   /infile $DD_SORTIN INDEXED
   /fields           f1 1 10 character
   /keys             f1
   /outfile $DD_SORTOUT $SYNCFMT_SORTOUT $LRECL_SORTOUT SEQUENTIAL OVERWRITE
   /statistics
   /end

--------------------------------
MBM 10.0.1p7   -  117630-07
--------------------------------
Fixed Problems

1. A fix to CR 6265013 resulted in a new error message. This fix corrects a 
   problem which could cause mvstrans to dump core when a procstep.stepname
   exceeded 17 characters.

   MV0692(W) Line=#%3.3d. Label %s is too long. It will be truncated to %d
   characters.

     Description: The specified label exceeded the maximum number of characters
     allowed. The label will be truncated to the maximum number of characters
     shown in the message.

     Solution: On the specified line in the JCL, shorten the label name so that 
     the length doesn't exceed the maximum number of characters.

2. If you are using CoSORT Version 8, you must set the sort options as described
   here. The information in the Sun MBM Migration Guide only applies if you are
   using CoSORT Version 7 and earlier. (CR 6288254)

   You must include all sort parameters, in their proper order, in the SYSIN
   (either a file or INSTREAM). Sun MBM no longer concatenates parameters for 
   the "sortcl" invocation. As of CoSORT Version 8, CoSort is invoked as 
   follows:

      sortcl /SPEC=$DD_SYSIN

   Note - If the SYSIN containing the sort parameters is INSTREAM, you must
   "escape" the dollar sign character of environment variables by using the
   backslash character (\).  For example: 

      /INFILE(\$DD_SORTIN)


--------------------------------
MBM 10.0.1p6   -  117630-06
--------------------------------
1. The description of the SYS1.LINKLIB entry in the File_Map has been expanded
   to include the following paragraph (CR 6249758).

   After the File_Map is created, you can manually update the SYS1.LINKLIB
   entry to add more directory paths to search for program exeuctables. Use
   colons to separate each directory path. For example:

     SYS1.LINKLIB;__LIB;FS;/app1/pgm/cobol1:/app1/pgm/cobol2;;0;

   Note - The field that contains the path name, or concatenated path names, for
   SYS1.LINKLIB, can alternatively be an environment variable (for example,
   $MYPATHS), which can contain one or more path names (separated by a colon if
   more than one). The value of the environment variable must be resolved at
   runtime through one of the job execution environment files (for example,
   $SETUP or $USER_SETUP).

2. Sun MBM now allows you to use GDGs with symbolic parameters in their names
   (CR 6248420).

   If the value of the symbolic parameter can vary in different job steps or
   jobs, you must update the File_Map as described in the following procedure, 
   so that the correct dataset can be located at execution time.

   Note - The procedure is required only if the variable in the GDG file name
   can be expanded to multiple dataset names and those dataset names have
   different maximum generations or different file attributes.

   The following example shows MVS JCL in the procedure called by the job. 
   
     //JOB1   JOB
     //STEP0001 EXEC PROC=TESTPROC,GDGFIL=GDG11
     //STEP0002 EXEC PROC=TESTPROC,GDGFIL=GDG22

   The following example shows MVS JCL in the procedure called by the job. The
   symbolic parameter, &GDGFIL, specified on the DSN parameter, defines a GDG.

     //TESTPROC PROC GDGFIL=
     //PSTP000 EXEC PGM=IEFBR14
     //SYSUT1 DD DSN=&GDGFIL(+1),DISP=OLD
     //PSTP001 EXEC PGM=IEBCOPY
     //SYSUT1 DD DSN=&GDGFIL,DISP=OLD
     //SYSUT2 DD DSN=NEWFILE,DISP=(NEW,KEEP,KEEP)
  

   o To Configure the File_Map for GDGs Referenced by Symbolic Parameters

   1. Run mvstrans in validation mode to create the entry for the GDG in the
      File_Map.

      Using the example JCL, execute the following command:
        $ mvstrans TESTPROC -v

     The resulting entry in the File_Map is:
        &GDGFIL;MASTERCAT;FS;/test/data/${GDGFIL};;9;

   2. Run mvstrans in translation mode to generate the macro job and
      procedure scripts.

   3. Determine the values with which &GDGFIL can be expanded.

      In this example, the values are GDG11 and GDG22.

   4. Add the expanded entries to the File_Map and set the maximum
      generations to the correct value.
        GDG11;MASTERCAT;FS;/test/data/GDG11;;52;
        GDG22;MASTERCAT;FS;/test/data/GDG22;;7;

   5. Delete the original entry in the File_Map.

      This is the entry that was created in Step 1, and it is not needed.

   When the job is executed, if the File_Map entry is not found using the
   name &GDGFIL, the ASSGNDD macro searches the File_Map using the expanded
   value, GDG11 or GDG22 in this example.

3. Sun MBM supports IBM WebSphere MQ in a VSAM subsystem environment 
   (CR 6246688). MQ from Sun MBM is run in client mode only, because there is 
   no support for two-phase commit.
   
   Prerequisites:
   - Build a Sun MTP region with MQ support. You must use Micro Focus Server
     Express as your application language. Refer to the Sun MTP Developer's
     Guide for information about integrating MQ.
   - Identify the values used in the Sun MTP region for the MQSERVER and 
     MQSERIES environment variables. The MQSERVER variable is required by MQ and
     contains information about the channel, protocol, host, and port number 
     that attaches to MQ; for example, CHANNEL1/TCP/myhost(10200). The MQSERIES
     variable identifies where MQ is installed.

   Build a Sun MBM subsystem and associate it with the region built with 
   MQ support.
   - When choosing your subsystem options, choose MQ on the Third Party Packages
     screen. Make sure Micro Focus is selected as your application language.
   - When you build the subsystem, you are prompted for the values of the 
     MQSERVER and MQSERIES variables. Make sure they are the same values used
     when you built the Sun MTP region. You are also prompted for the $UNIKIX
     and $KIXSYS values of the region. Make sure to provide the values for the
     region that you built with MQ support.

   Make sure that your Sun MTP region is configured to connect to the Sun MBM 
   node. Refer to the Sun Mainframe Transaction Processing Software 
   Configuration Guide.

   
--------------------------------
MBM 10.0.1p5   -  117630-05
--------------------------------
1. An enhancement was made to message IP4305(I) so that it contains the 
   subsystem name (CR 5075543). The new error message is:

   IP4305(I) Start of job %s on subsystem %s at %s

     Description: The message indicates the name of the job, the subsystem where
     the job is executing, and time the job was started.

     Solution: Informational message; no user action is needed.

--------------------------------
MBM 10.0.1p4   -  117630-04
--------------------------------
1. During the build of a VSAM subsystem, BAM now automatically adds the
   $UNIKIX/local/bin directory to the subsystem's $SETUP file. (CR 4763832)

2. MBM now supports Oracle 10g (CR 6180933).

3. A fix to CR 4996484, which related to the use of the -D and -E options to
   the dostrans translator, resulted in a change to the example documented in
   the release notes for Sun MBM 10.0.1. The corrected example is as follows:

   Original JCL:

     //JOB tstinstop
     //EXEC PGM=IDCAMS,PARM='TEST'
       $dollar test with -E
       &ampersand test with -D
     /&

   Executing the dostrans tstintop -f -D -E command results in the following
   macro statements:

     BEGINJOB
     ASSGNDD ddname='SYSIN' type='INSTREAM' << !
      $dollar test with -E
      \${ampersand} test with -D
     !
     EXECPGM pgmname='IDCAMS' stepname='STEP0001' parm='TEST'
     ENDJOB

4. In previous versions of Sun MBM, the current working directory was deleted
   at the end of a job. This also deleted any core files that might have been
   created and saved in hat directory, which meant that the core file was no
   longer available for an alysis.
   This patch release changes this behavior (CR 5110259). Now, core files are 
   saved to the mbmwk/corefiles directory in the user's work directory. By 
   default, the user's work directory is the user's home directory. For example,
   if the user's home directory is /users/john1, the core files are saved in
   the directory /users/john1/mbmwk/corefiles. There are two formats for the
   name of the core file.
   If the core file was generated at the end of the job, its format is:
     core_${EBMSYS}_${JON}_${PID}
   If the core file was generated during the job, either by a macro or a
   utility, its format is:
     core_${EBMSYS}_${JOBNAME}_${JON}_${PID}

   Note: You can change the user's work directory in BAM, or by editing the
   $EBMHOME/.install file. Refer to the MBM Configuration Guide for more 
   information.

   There are new error messages related to this fix. The IP messages are issued
   if the core file is generated and moved at the end of the job. The MA 
   messages are issued if the core file is generated and moved during a job by
   a macro or utility.

   IP4560(I) core file found and moved to %s

     Description: The core file was saved to the specified directory.

     Solution: Informational message. Use the path information to locate the
     core file and, if necessary, provide it to your authorized service provider
     for analysis.

   IP4561(E) Error core file name in '%s' would exceed PATH_MAX

     Description: The core file was not moved to the specified directory, 
     because, if it were, the full path and file name would exceed the limit
     permitted by your operating system.

     Solution: Change the user's work directory so that its path name is 
     shorter.

   IP4562(E) Error '%d' moving core file '%s'

     Description: The core file could not be moved to the specified directory.

     Solution: Use the specified UNIX error number to determine the cause of the
     problem. There might be permission problems writing the the specified 
     directory.

   IP4563(E) Error '%d' creating directory '%s'

     Description: The specified directory could not be created.

     Cause: This error can occur if Sun MBM cannot create the corefiles 
     subdirectory.

     Solution: Use the specified UNIX error number to determine the cause of the
     problem. There might be permission problems writing the the specified 
     directory.

   MA1126(I) core file found and moved to %s

     Description: The core file was saved to the specified directory.

     Solution: Informational message. Use the path information to locate the
     core file and, if necessary, provide it to your authorized service 
     provider for analysis.

   MA1127(E) Error core file name in '%s' would exceed PATH_MAX

     Description: The core file was not moved to the specified directory, 
     because, if it were, the full path and file name would exceed the limit
     permitted by your operating system.

     Solution: Change the user's work directory so that its path name is 
     shorter.

   MA1128(E) Error '%d' moving core file '%s'

     Description: The core file could not be moved to the specified directory.

     Solution: Use the specified UNIX error number to determine the cause of the
     problem. There might be permission problems writing the the specified 
     directory.

   MA1129(E) Error '%d' creating directory '%s'

     Description: The specified directory could not be created.

     Cause: This error can occur if Sun MBM cannot create the corefiles 
     subdirectory.

     Solution: Use the specified UNIX error number to determine the cause of the
     problem. There might be permission problems writing the the specified 
     directory.

--------------------------------
MBM 10.0.1p3   -  117630-03
--------------------------------
None

--------------------------------
MBM 10.0.1p2   -  117630-02
--------------------------------
1. Special Characters in SyncSort Control Statements (BugId 5045333)

A dollar sign ($) has specific meaning, at times, to the UNIX shell, as well as
to the Sun MBM engine. Therefore, use the following guidelines if the character
is being used in SyncSort parameters such as: /derivedfield  d1 "$".

- If the SYSIN file for the SyncSort parameters is a disk file, to maintain a
  $ character, you must either enclose the dollar sign in double quotes, or 
  use a single escape character (backslash) before the dollar sign. 
  
  For example, either format is acceptable:
  
  /derivedfield d1 "$"
  /derivedfield d1 \$
  
- If the SYSIN is instream, you must use three escape characters before the
  dollar sign, or enclose an escaped dollar sign in double quotes.
  
  For example, either format is acceptable:
  
  /derivedfield d1 \\\$
  /derivedfield d1 "\$"
  

2. A fix to BugId 5080773 resulted in the following new documentation:

   User utilities can be used to encapsulate any user-specific functions within
   macro execution. 
   
   All user utilities must assign a numeric return status in the file 
   status.${JON}. The status code must be in the range of 0-255. 
   
   For example, if the user utility is to return a zero or non-zero status 
   depending on the existence of the file named myfile, the setting of the
   exit status in a UNIX shell script would be similar to the following:
   
     ...
     if(-f myfile)
     then
        echo 0 > status.${JON}
     else
        echo 1 > status.${JON}
     fi
     ...

   A zero value indicates that the utility ended normally. A non-zero value 
   indicates that the utility ended abnormally and the job step will abort.

   The EXECPGM macro initializes the COND-CODE with a value of 255 before 
   calling user utilities. If the value in the status.${JON} file is not set
   to zero on normal termination, the step will abort due to the initial 
   non-zero value (255).

   The value set in the status.${JON} file will be the COND-CODE value of the 
   step.
   

3. A fix to BugId 5050041, which related to spurious messages that were 
   displayed if all GDG occurrences did not exist, resulted in the following
   new error message:

   MA2139(S) Internal error: Copy failed
   From file: %s
   To file: %s
   Return status: %d
 
     Description: An internal error was detected while attempting to copy a
     temporary work file.

     Solution: Contact your authorized service provider.

4. A fix to BugId 5088282 resulted in a new error message, which alerts you to
   a missing file in a concatenated dataset that is being processed by the
   IEBGENER utility.
   
   MA2568(S) Error accessing file: %s, errno=%d
   
     Description: While trying to perform an I/O on the specified file, a
     system error occurred. The operation is not specifically identified. In
     the error message, %s is the name of the file being operated on. It can
     also be a list of concatenated file names delimited by colons.
     
     Solution: Determine the type of error that occurred by mapping the 
     errno value in the message to the list of UNIX errors in the errno.h
     include file. For example, an errno=2 maps to "File not found". It 
     would indicate that the file named in the message was not found for
     an open or stat operation. In the case of a concatenated file list, 
     you must evaluate each file in terms of the error condition to
     determine which file caused the error. Verify that the file exists and 
     rerun the job.

--------------------------------
MBM 10.0.1p1   -  117630-01
--------------------------------
None

