C H A P T E R  15

Batch Processing

Sun MTP supports two batch environments:

C language batch programs are supported using the C-ISAM interface. See Executing C Language Batch Programs.

Note - Features noted as non-Sun MBM are valid only in the standard batch environment.

This chapter contains the following topics:

Configuring the Batch Environment

Limited resources are allocated to batch processing. Sun MTP gives first priority to foreground transactions, such as online transactions started at terminals. If resources are still available, background transactions are started. Background transactions can be report programs started at printers or transactions started when a transient data queue reaches its trigger level. Finally, if resources are still available, batch programs are started.

Before executing batch programs, you must:

Setting the KIXBTCH Environment Variable

Set the KIXBTCH environment variable in your region's setup file. If you have multiple $KIXBTCH directories, separate them with colons. The directory or directories pointed to by $KIXBTCH must be on the same file system as the $KIXSYS directory.

These directories are searched in order, at a set interval, for either COBOL programs or shell scripts. The COBOL programs have .int or .gnt file extensions. Shell scripts must be executable. See Setting the VCT Batch Fields for information about setting the batch search interval.

Note - $KIXBTCH is used only for a non-Sun MBM environment.

Supporting Multiple $KIXBTCH Environments

If you are running batch jobs from multiple $KIXBTCH directories and need to set different search intervals for each directory, set $KIXBTCH in your region setup file using the format:

export KIXBTCH=directory1[starttime1-endtime1] [:directory2[starttime2-endtime2]]:...


directory1, directory2, ...

Directories where batch jobs or shell scripts are located. At least one directory must be present for batch processing to be in effect. All batch directories must be in the same file system as the $KIXSYS directory.

starttime1, endtime1, ...

Time(s), in 24-hour format (hhmm). Controls when to search this directory. All times are optional; start time must be earlier than end time. If the current time is not between the start and end time, the directory is bypassed.

A single time is considered a start time; the end time defaults to 2400. Search intervals over midnight are not allowed.

Example: Your batch environment requires two $KIXBTCH directories. The first is a directory for local programs running in an inventory region. The second is a directory that receives payroll time sheet programs downloaded nightly from a CICS mainframe system. To achieve the best performance, you want the local directory, /inv/batch, searched every two minutes, and the download directory, /pay/times, searched only once, after the nightly download. Set $KIXBTCH in the region setup file as follows:

export KIXBTCH=/inv/batch:/pay/times[0300-0400]

Setting the VCT Batch Fields

Several fields in the VCT control how batch programs execute. Open the VCT from the Table Manager-Standard Tables menu.

  FIGURE 15-1 VSAM Configuration Table

Screen shot showing the VCT.[ D ]

The following fields control the number of foreground transactions, background transactions, and batch programs that Sun MTP can execute, as well as the batch search interval.

Transaction servers

The total number of transaction servers available to the region. Because a transaction server is required to execute any transaction or batch program, this field also defines the maximum number of transactions and programs that can execute concurrently.

This field is used to determine if transaction servers are available.

Maximum background tasks

Set to the maximum number of background transactions and programs that can execute concurrently.

This field limits the number of transaction servers assigned to lower priority tasks.

Maximum batch jobs

Set to a value that establishes the number of transaction servers that can only be used to execute batch transactions.

The sum of Maximum background tasks and Maximum batch jobs must be equal to or less than the number of transaction servers.

Batch search interval

Controls how often the region inquires for batch programs awaiting execution. Set to any number of seconds from 1 to 9999. The default is 120 seconds.

The Connect to batch node and Node Dir fields indicate whether Sun MBM is connected to Sun MTP for batch processing. Refer to the Sun Mainframe Transaction Processing Software Configuration Guide for information about configuring the region to work with Sun MBM.

Batch Tasks

You can perform a variety of tasks in the batch environment:

Handling Errors in Batch Shell Scripts

A batch shell script can contain a series of Sun MTP-supplied utilities (for example, unikixvsam or unikixbld), operating system commands, third party utilities, control statements, environment setting statements, and other statements.

When using Sun MTP-supplied utilities in a batch script, you must capture the return status, which can be examined to determine whether the next step in the utility or script should be executed. If the error condition is not critical, control can continue to the next step. Otherwise, exit from the script with the status.

If the error condition raised by the Sun MTP utility is not properly handled, an implicit rollback is executed in the next Sun MTP utility. If the offending utility is the last step in the script, the transaction processor (unikixtran) will perform an implicit rollback.

Executing COBOL Batch Programs

This section describes how to execute COBOL batch programs that access VSAM datasets.

Accessing Data Files From COBOL Batch Programs

The Sun MTP file organization is designed for compatibility with the VSAM access method used by CICS. This file organization is separate from the normal file organization that comes with COBOL. A single program can access both file organizations:

When using a batch COBOL program, the ASSIGN and ORGANIZATION clauses of the SELECT statement and the RECORD clause of the file description entry help to determine which file organization is used.

The possible formats for the SELECT statement ASSIGN clauses are:

When VSAM files are accessed, Sun MTP file processing is invoked if the RECORD clause is formatted correctly.

A shell script that is executing the batch program can override name if you use the EXTERNAL option on the ASSIGN clause. With this option, Sun MTP uses the name parameter to search for an environment variable named dd_name or DD_name. The value of this environment variable is then used.

When a file is to be opened by more than one file description concurrently, you must use different names of the file description entries in the program. To direct these entries to the same physical file requires the EXTERNAL option of the ASSIGN clause.

Although Sun MTP supports an online application's VSAM sequential files, namely, Entry-Sequenced Data Sets (ESDS) formatted files, Sun MTP batch programs cannot directly access these files.

Note - Support for batch processing of native ESDS files is provided by Sun MBM.

procedure icon  To Process an ESDS File

1. Unload the ESDS file by creating a sequential file in either sequential, line sequential, or record sequential format.

Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide.

2. Execute the batch program using the new sequential file.

The batch program uses Micro Focus to access the file, not VSAM.

3. Restore the sequential file to its VSAM organization.

Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide.

At this point, online programs can access the file as a VSAM protected file.

During the period when the ESDS file is a sequential file and is being updated by the batch program, other programs should not access the original VSAM file. If access is required during this time, it should be read-only.

Because Sun MTP VSAM is multiuser, additional commands are provided that allow the batch program to commit or rollback any updates. These commands are described in Controlling Data Integrity.

Compiling Batch COBOL Programs

The following table describes options and directives you can use when compiling batch COBOL programs. For a complete description of compilation options and directives, refer to the COBOL documentation.

TABLE 15-1 Options and Directives for Compiling Batch COBOL Programs




-C ibmcomp


Compiler directive for COBOL

Required. Allocates data with the same sizes as the OS/VS COBOL compiler on an IBM 370-compatible computer.

-C assign"external"

Compiler directive for COBOL

Required for the Sun MBM product, or if you are using DD filename in standard batch.

-C defaultbyte"32"

Compiler directive for COBOL

Required. Controls how storage is initialized. This is storage that is declared in a COBOL program and does not have a value statement associated with it. For batch programs, this directive is set to 32 to ensure that storage is set to spaces.



Generate intermediate code with an .int extension

Use this option for development or for I/O intensive programs. This compiles faster than producing a .gnt file.

-C sequential"record"

Compiler directive for COBOL

For COBOL2 batch programs.



Generate executable program with a .gnt extension

The .gnt file executes much faster than an .int or .idy file. If using the program in a production environment, use this option.



Generate Animator output with the .idy extension

Animator is used to debug batch programs. Server Express can animate .gnt, .idy, and .int files.


Use Sun MTP for file access



Compiler directive for COBOL

Binary fields are treated the same as in IBM COBOL.

The following example shows a script that compiles all batch programs within a directory. This script also captures log files that indicate an error or successful completion.

CODE EXAMPLE 15-1 Script to Compile All Batch COBOL Programs in a Directory
for i in `ls *.cbl`
	echo about to compile `basename $i .cbl`.cbl
	echo about to compile `basename $i .cbl`.cbl >> COMPALL.err
	cob <options and directives> `basename $i .cbl`.cbl
	if [ $ReturnCode -ne 0 ]
		echo "Error detected during cob of `basename $i .cbl`" >> COMPALL.err
		echo "Compile completed for `basename $i .cbl`" >> COMPALL.err

Executing Programs Using Standard Batch

In the standard batch environment, Sun MTP executes jobs automatically after they are copied into $KIXBTCH. Each program and shell script is started as resources become available. If no resources are available, the programs and shell scripts wait.

Sun MTP can execute COBOL programs or shell scripts. Shell scripts are a series of commands that can call COBOL programs, but are not required to call them. COBOL executables have file extensions of .gnt or .int. File names of shell scripts might or might not have an extension. Make sure the program or shell script is executable.

procedure icon  To Execute a Program

single-step bulletCopy the program to the $KIXBTCH directory.

The program will be executed based on the batch search interval

caution icon

Caution - Copy--do not move--programs or shell scripts into $KIXBTCH. After the batch job starts, the programs or scripts are deleted from $KIXBTCH.

Programs and shell scripts must be executed by the user ID that started the region. All output is written to the terminal of the user ID that started the region.

If the shell script or COBOL program references VSAM datasets, the dataset name is the 8-character name specified in the FCT. Programs can reference datasets using absolute or relative file names. If relative file names are used, they are relative to the current directory. For batch files, this is the $KIXSYS directory.

If the shell script or COBOL program references other files, the name must be specified as indicated in the COBOL documentation.

If executing a COBOL program inside a shell script, the program must be executed using the unikixvsam COBOL runtime system. Refer to the Sun Mainframe Transaction Processing Software Reference Guide for the format and options of unikixvsam.

See also Debugging Batch COBOL Programs.

Executing Programs From Sun MBM

If the region is connected to Sun MBM, it only executes jobs that are submitted to Sun MBM using the unikixjob command. Refer to the Sun Mainframe Batch Manager Software User's Guide for additional information about this command.

Executing Batch Programs Using Online Transactions

Batch programs can be started by online transactions that write shell scripts to an extrapartition transient data queue (TDQ) of type JOB. Any TDQ writes to the specified queue are written to a file that is again passed to the JOB queue.

Once you've defined the TDQs in the Destination Control Table (DCT), the kixjob shell script is used to interface to the JOB queue. kixjob is called when a transaction issues a syncpoint after it has written to a JOB queue. This syncpoint can be issued explicitly by using the EXEC CICS SYNCPOINT command or implicitly when a transaction terminates.

Note - If the region is connected to Sun MBM, refer to the Sun Mainframe Batch Manager Software Configuration Guide for information about using kixjob.

Executing Batch Jobs With Multiple Steps

You must use shell scripts to execute batch jobs with multiple steps. The shell scripts can specify the order in which programs run and allow the batch job to pass files from program to program, delete files, and copy files.

Passing Parameters to unikixvsam Programs

Note - This feature is specific to a non-Sun MBM environment.

When a unikixvsam program starts, parameters can be passed to the program either in a card file or through the command line. If the program is reading a card file through a standard COBOL input file, create the card file using a text editor. You must ensure that the COBOL SELECT statement specifies a line sequential organization. One method of creating parameter cards is to use the echo command:

$ echo "Parameter card data"> parm_data

This creates a single record line sequential file named parm_data that contains the text PARAMETER CARD DATA.

A second method of passing parameter data to a program is on the program invocation. When executing the program, pass the parameters as shown in the following command:

$ unikixvsam PGM00112 "Parameter card data"

The program must then define the parameter card format in the LINKAGE SECTION and add a PROCEDURE DIVISION USING clause.

The format of the program is as follows:


unikixvsam reserves an area up to 160 bytes for each parameter and allows up to five parameter areas.

Note - The COBOL ACCEPT FROM CONSOLE statement is not supported. You can change this statement using the examples shown in this section.

Setting Return Codes

Note - This feature is specific to a non-Sun MBM environment.

Micro Focus enables you to set return codes in a COBOL program. The return codes are passed to a called program or the calling shell script by setting the OS/VS COBOL option. The method for setting return codes is as follows:


The operating system truncates the special register RETURN-CODE to a single byte. Therefore, if the RETURN-CODE variable is set to 257 in the COBOL program, the shell script receives the value 1.

unikixvsam further defines this variable. If the value is between 0 and 127, just the value is returned. If the value is greater than 127, all VSAM updates that are not committed are rolled back.

To test the value of the return code in a Korn shell script, use the $? construct, which enables you to control which program in the runstream to execute next.

The following example tests the return code for the COBOL program RAM59. If the return code indicates that an error occurred, the echo command is executed and the exit command terminates execution of the shell script with the return code as a parameter.

unikixvsam RAM59 "RAM0599"
if [$cond -ne 0]
		echo "RAM59 ERROR CODE = $cond"
		exit $cond

Executing PL/I Batch Programs

You must use Sun MBM to execute PL/I batch programs.

Executing C Language Batch Programs

Note - This feature is specific to a non-Sun MBM environment.

Sun MTP supports the execution of C language batch programs that access VSAM files with the C-ISAM interface. Before executing C batch programs, you must compile them. You can only execute the programs on a system running the same version of Sun MTP as the system where the programs were compiled. See Chapter 16 for more information about C-ISAM functions.

procedure icon  To Compile a C Language Batch Program

1. Set the UNIKIX environment variable to the region where this program will execute.

2. Include the isam.h header file in your C program.

The file is located in the $UNIKIX/src/CICS_structures directory.

3. Execute the following command, either on the command line or in a script file, to compile the program and create the executable.

$ cc input-filename.c -o output-filename $UNIKIX/lib/libbcisam.a

4. Make sure that there are execute permissions on the file.

procedure icon  To Execute the Program

1. Create a shell script.

$ vi cbat01.sh

2. In the script, type the path name and batch program name.


3. Save the script and exit the editor by typing :wq.

4. Make the script executable by setting the permissions.

$ chmod 777 cbat01.sh

5. Copy the shell script to the $KIXBTCH directory, from which it will be automatically executed.

$ cp cbat01.sh $KIXBTCH

Using unikixbld to Access VSAM Files From a Batch Job

The unikixbld utility manipulates VSAM files from a batch job running in a region. You can write programs to perform these functions, but it is usually more convenient to use this utility. unikixbld performs the following functions:

Note - unikixbld has options that enforce IDCAMS REPRO behavior.

Refer to the Sun Mainframe Transaction Processing Software Reference Guide for more information about unikixbld.

The following table shows the unikixbld formats used to perform specific functions.

TABLE 15-2 unikixbld Functions



Initialize a VSAM dataset

unikixbld -d dataset -i

Build one or more non-VSAM files from a VSAM dataset

unikixbld -t s -d dataset -s filename

[-s filename [-s filename [...]]] [-r format]
bytes [K|M|G]] [-v n_rec]

Build a VSAM dataset from one or more non-VSAM files

unikixbld -t v -d dataset -s filename

[-s filename [-s filename [...]]] [-f percent] [-r format]
[-m] [-M
altkey_mem] [-v n_rec]

Rebuild the index portion of a VSAM dataset

unikixbld -t x -d dataset [-v n_rec]

Rebuild VSAM alternate index files for a VSAM primary file

unikixbld -t a -d dataset [-M altkey_mem] [-v n_rec]

Update VSAM files

unikixbld -d dataset -p [reuse|noreuse]
[-k {replace|noreplace}] -W nnn -V

Using kixfile to Manage VSAM Datasets From a Batch Job

kixfile is a batch utility that enables you to dynamically change the status of a VSAM dataset, including its associated alternate datasets. You can use kixfile on a dataset to:

Refer to the Sun Mainframe Transaction Processing Software Reference Guide for a description of the format and options of kixfile.

Using dfhusdup to Define and Report Resources

dfhusdup is the batch utility used to define and report the resources in the system definition file (DFHUSD). It also used to initialize the DFHUSD file. Refer to the Sun Mainframe Transaction Processing Software Reference Guide for a description of the format and options of dfhusdup. Also refer to the Sun Mainframe Transaction Processing Software Configuration Guide for information about alternate resource definition.

You can enter comments in the batch file by typing an asterisk (*) in the first column of the line. If the command, attribute, or attribute type continues to the next line, you must type an asterisk in column 72.

Example: This example shows the use of the asterisk to denote a comment and the continuation of a command in a batch file.

*Define a program
	es program)

The following examples show some ways to use the dfhusdup utility.

Example: The following dfhusdup command, which is executed from a script, specifies a file named load. This file contains the commands to initialize, define, and list resources. All messages generated by the dfhusdup utility are redirected to the file loadout.

dfhusdup USD=READWRITE PAGESIZE=50 CMDFILE=load > loadout

The contents of the file load are:

*Resource definitions for Sales Department
	ales program)
	es add screen)
	es delete screen)
	es modify screen)

Example: The following script shows how to use the CMDFILE=stdin argument and how to delete resources.

dfhusdup USD=READWRITE CMDFILE=stdin <<!
*To delete an old program and mapset from the resource file

Example: The following script shows how to copy resources from one group to another.

dfhusdup USD=READWRITE CMDFILE=stdin <<!
*To copy group 'sales1' resources to new group 'sales2'

Sun MTP Batch Utilities That Do Not Affect VSAM Datasets

There are two batch utilities that do not affect VSAM datasets:

Statistical Information About VSAM Batch Jobs

Statistical information is available for the unikixvsam, unikixbld, and kixfile utilities, as well as for the unikixjob utility in Sun MBM. You can use these statistics to help diagnose performance problems you might encounter when executing batch jobs.

Each utility displays the following statistical information on your monitor. (Actual values will be displayed.)

Command Executed: "command and parameters"
Batch Process 99999 Start Time hh:mm:ss End Time hh:mm:ss Elapsed Time 9.99 secs
System CPU Time 9.99 secs User CPU Time 9.99 secs

Each utility has a set of arguments you can enter on the command line that display additional statistics.

Refer to the Sun Mainframe Transaction Processing Software Reference Guide for the command syntax to display these statistics. Refer to the Sun MBM documentation for information about the unikixjob utility.

The following examples show the output of the various options:

command arguments -X VSTIME

Total time in VSAM: 9.99 secs Time in O/S calls in VSAM: 9.99 secs VSAM code execution time 9.99 secs

command arguments -X WTIME

Buffer wait time: 9.99 secs I/O Wait Time: 9.99 secs Semaphore Wait Time 9.99 secs

command arguments -X LIO

Logical File I/O Statistics
File Reads Writes Rewrites Deletes Startbrs Endbrs Resetbrs Unlocks Readnexts Readprevs
ABC     9    9        9       9        9      9       9        9       9         9

command arguments -X PIO

Physical File I/O Statistics
File          Reads      Writes     Allocs
ABC            9          9            9

Note - The performance impact of using the options to gather and display statistical information is negligible.

Overriding the Batch Search Interval

To run a batch program immediately, overriding the batch search interval set in the VCT, use the CBCH transaction. CBCH starts the batch program as if it were a foreground transaction.


CBCH batch-program



Name of batch program or shell script to start.

If you specify only a program name, the program executes from the directory that is relative to $KIXSYS. If your program is located in a directory that is not subordinate to $KIXSYS, use the full path and file name.

Note - You cannot use CBCH to override the batch search interval if the region is connected to Sun MBM.

Maintaining Data Consistency

VSAM RC (read consistency) allows batch programs to acquire exclusive record locks for files that are opened in I-O mode.

VSAM RC offers the following benefits:

Read the following topics if you are planning to use VSAM RC:

Programs that do not require read consistency can request a record for read only, referred to as a dirty read, which is the default VSAM behavior and the behavior of previous versions of the software. Without VSAM RC, resources must not be shared among batch programs and batch and online programs.

If you are using Sun MBM to access VSAM files, you must take into consideration the value of the RLS parameter on the DD JCL statement. Refer to the Sun MBM documentation for information about the RLS parameter.


Prior to Release 7.1, batch programs could not acquire an exclusive record lock when a READ was issued. When the program requested a READ, the record was acquired without any locks. When the program issued a REWRITE or DELETE, the record was read again with a lock and the next operation was executed. This implementation did not provide any protection to the record between the READ and the REWRITE or DELETE requests, leaving it vulnerable to an update or deletion.

With VSAM RC, the batch program can read a record with an exclusive lock and VSAM RC will hold this record on behalf of the batch program. New requests for a lock on the same record, whether an online transaction or another batch program, are queued until the batch program that owns the lock releases it.

Limitations of VSAM RC

Be aware of the following limitations when implementing VSAM RC for your applications:

Note - Micro Focus Server Express does not support COMMIT and ROLLBACK verbs. You must use kixvsam in your programs. See Controlling Data Integrity for more information.

Application Design Issues

If your application does not require any of the VSAM RC features, you can continue to use your existing online and batch execution model. If you are migrating from a release prior to Release 7.0, you must convert your VSAM catalog. See Programs Without API Locks.

If your application requires the sharing of resources among batch programs and online transactions, consider the following issues:

The batch window is the time when the online system is quiesced and the batch programs are updating files and printing reports. If the time allocated for batch is not enough, identify programs and batch steps that can run in parallel to reduce the batch window.

Identify the resources that are shared by batch programs. Include all the files opened in I-O mode by all the participating batch programs that run concurrently. For example, if ProgramA updates File1 and File2, and ProgramB updates File2 and File3, enable VSAM RC for File1, File2, and File3. This provides a safeguard against some other batch program or online transaction accessing one of the files. If some of the batch programs have VSAM RC enabled for files and some do not, data integrity cannot be guaranteed.

The following example shows how two batch programs, C and D, share the account file. If you do not enable VSAM RC for shared files, your batch programs perform dirty reads, which can result in data inconsistency. In this example a bank account has a balance of $1000. ProgramC, which uses VSAM RC, must debit $100 from this account and ProgramD, which does not use VSAM RC, must credit $500 to the account. This sequence of events can occur:

1. ProgramC reads the account balance, which is $1000, and locks the record.

2. ProgramD reads the account balance, which is $1000 (dirty read because VSAM RC is not used).

3. ProgramD increases the balance by $500 and writes $1500, but must wait for ProgramC to release the record.

4. ProgramC reduces the balance by $100, leaving a balance of $900.

5. ProgramC writes out a balance of $900 and releases the record because of a COMMIT or the end of the program.

6. ProgramD writes out a balance of $1500.

This sequence of events results in a $1500 account balance. If step 6 occurred before step 5, the account balance would show $900. The actual account balance should be $1400. If ProgramC completes its work before ProgramD does its work, or vice-versa, the correct balance results.

When batch programs are executed in a single thread, or with exclusively locked files, they own all the resources. If VSAM RC is enabled, you can execute batch programs in parallel. Execution time should improve, although perhaps not as much as you might expect. For example, in a batch job, Step1 and Step2 each take one hour to complete. When run in parallel, these steps should theoretically take one hour to complete. In reality, Step2 might have to wait for some resources acquired by Step1 to be released. In another scenario, if Step1 has an exclusive lock on a record and an online transaction requests that record, the online transaction must wait until the record is released. Depending on how long the online transaction waits, the user's response time might increase.

During a typical batch execution process, files are periodically backed up before they are updated. If the updating steps fail and the batch job is restarted with certain options, the backed-up files are restored and the update process begins again. If you use VSAM RC, this procedure changes and you cannot use the backed-up files as a starting point, because the files might contain records updated by online transactions or different batch programs.

If recovery is enabled, you must also consider the following:

To maintain data integrity from a batch program, you must enable recovery on the files. VSAM uses approximately 300 bytes of shared memory for every locked resource (record). For every record updated by a batch program, VSAM acquires a lock. Because batch programs typically update large numbers of records, there can be a large number of locks, resulting in a significant increase in shared memory size.

Note - The memory is reused after the program or transaction issues a COMMIT.

The recovery file is a fixed-size circular file, which is used to store the before-images of the records and block split information. Because batch programs can have a large number of uncommitted records, you might need to increase the size of the recovery file.

Changing Existing Batch Programs for VSAM RC

Existing batch programs typically expect all the required resources to be available before executing. If you are using VSAM RC, modify your batch programs to handle the following:

A deadlock is a situation where two programs are each waiting for the other program to release a record. For example, Program1 has an exclusive lock on Record1 and wants Record2, and Program2 has an exclusive lock on Record2 and wants Record1. VSAM detects this kind of situation and returns an error. In COBOL, the program status is set to 9D. Modify your batch programs to handle deadlocks by having them issue a ROLLBACK to release all the locked records and undo all changes since the start of the program or the last COMMIT.

If a file is shared by batch programs or by batch and online programs, the file must be in a sharable mode. If the file is locked exclusively, a kixfile command must be issued to remove the exclusive lock. If the file mode is batch-only or online read-only mode, you must change the mode to remove the file constraints.

If you want a batch program to use selective record locking, you can use ANSI COBOL extensions.

If recovery is enabled, also consider the following:

If a batch program updates 1000 of the 2000 records in a file, other programs must wait until the batch program finishes using the 1000 records. This can cause delays in response time and can affect resources, such as shared memory. To avoid this, modify your batch programs to issue periodic COMMITs to release the records for other programs. Make sure to issue the COMMITs so that you maintain data integrity. For example, a batch program updates account balances offline. It subtracts $100 from a checking account file and adds it to a savings account file. If you issue the COMMIT after subtracting the money from the checking account file, the corresponding information is not reflected in the savings account file. If the customer closed the savings account, the online program might delete the savings account file record by the time the batch program tries to add the $100 to the savings account file.

If a program issues periodic COMMITs and the program aborts, it must account for the committed records when it restarts. For example, a program updates records in a VSAM inventory master file from a new_items sequential file, issuing a COMMIT after updating every 1000 records. If the program aborts after updating 4200 records, it must be able to restart updating the records from record number 4001.

Programs Without API Locks

Most batch application programs do not use the ANSI COBOL features for locking. These features (collectively called application program locking mechanisms) include, but are not limited to, LOCK MODE IS AUTOMATIC and LOCK MODE IS MANUAL clauses in the SELECT statement, and READ WITH LOCK and READ WITH NO LOCK statements in the PROCEDURE DIVISION.

If your programs do not use application program locking mechanisms, read this section. If you have or plan to have application program locking mechanisms, also read Programs With API Locks.

At the cluster (file) level in the VSAM catalog, the Batch Read-locking field specifies whether batch VSAM reads should lock the record being read. If the field is Y, batch VSAM reads for the dataset will lock the record. If the field is N, batch VSAM reads for the dataset will not lock the record.

If you are upgrading from a release prior to Release 7.0, you must decide on the value of the Batch Read-locking field when you convert your VSAM catalog (using the kixcnvtcat72 utility). Your choice is propagated to all the converted file definitions. You can subsequently change the value using the File Manager. When you add new files to the catalog, you must specify Y or N for the Batch Read-locking field. Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for information about managing the VSAM catalog.

  FIGURE 15-2 Specifying Read-locking in the VSAM Catalog

Screen shot showing a cluster entry in the VSAM catalog.

Note - To keep the batch VSAM read-locking functionality provided by previous releases of the software, set the Batch Read-locking field to N for all files.

If you want to override the cluster-level read-locking specification for specific job steps, you can manipulate two environment variables:

KIX_READLOCKON=dataset 1:dataset 2:dataset 3:""..:dataset N

KIX_READLOCKOFF=dataset 1:dataset 2: dataset 3:""..:dataset N

If a dataset is listed in the KIX_READLOCKON environment variable, VSAM RC reads for the dataset will lock the record being read, regardless of the value of the cluster-level flag. If a dataset is listed in the KIX_READLOCKOFF environment variable, VSAM RC reads for the dataset will not lock the record being read, regardless of the value of the cluster-level flag. If the dataset is listed in both the KIX_READLOCKON and KIX_READLOCKOFF environment variables, an error is raised when the batch application program opens the dataset.

Because these environment variables are used to override the cluster-level specification, it is superfluous to list a dataset in $KIX_READLOCKON if its read-locking field in the VSAM catalog contains Y. Likewise, if a dataset has an N in the VSAM catalog (no locking), it is not necessary to list it in $KIX_READLOCKOFF.

The following table summarizes the locking behavior of batch VSAM reads based on the cluster-level settings and the environment variables.

TABLE 15-3 Locking Behavior Based on Cluster Setting and Environment Variable




Dataset is listed in




Dataset is listed in


No Lock

No Lock

Dataset not listed in either environment variable


No Lock

Programs With API Locks

ANSI COBOL provides methods for application programs to specify locking behavior when records are read. In addition to a plain READ, application programs can specify a READ WITH LOCK and READ WITH NO LOCK. According to the API, READ WITH LOCK locks the record being read and READ WITH NO LOCK does not lock the record. The locking behavior of a plain READ depends on whether LOCK MODE IS AUTOMATIC or MANUAL. LOCK MODE is specified in the SELECT clause. MANUAL does not lock a plain READ and AUTOMATIC does.

The read-locking behavior of application programs that specify LOCK MODE depends on the LOCK MODE, the API, the cluster-level settings in the VSAM catalog, and the environment variables that override the cluster-level settings. API locking is enabled only if read-locking is enabled based on the rules specified in Programs Without API Locks.

The following tables summarize the locking behavior of application programs that use ANSI COBOL locking mechanisms.

TABLE 15-4 ANSI COBOL Locking When Cluster is Set to Y




Dataset listed in


READ (No Lock)



READ (Lock)



Dataset listed in


READ (No Lock)



READ (No Lock)



Dataset is not listed in either environment variable

READ (No Lock)



READ (Lock)



TABLE 15-5 ANSI COBOL Locking When Cluster is Set to N




Dataset listed in


READ (No Lock)



READ (Lock)



Dataset listed in


READ (No Lock)



READ (No Lock)



Dataset is not listed in either environment variable

READ (No Lock)



READ (No Lock)



The cluster-level setting takes on a different meaning for application programs that use API locks than for programs that do not.

TABLE 15-4 shows that:

TABLE 15-5 shows that:

Read-Locking Examples

The following examples describe situations where you could consider using read-locking. They are based on the behaviors described in the sections on API locking.

Situation: Your application programs do not contain API locking specifications and you do not require read-locking.

Recommendation: Ensure that the Batch Read-locking field in the VSAM catalog is set to N for all datasets. You do not need to set any environment variables. This scenario is consistent with the dirty read behavior of earlier versions of the software.

Situation: Your application programs do not contain API locking specifications, but you want batch reads to lock the record.

Recommendation: Ensure that the cluster-level setting in the VSAM catalog is set to Y.

Situation: You want to try out batch read-locking for an experimental batch step.

Recommendation: Include the relevant dataset in $KIX_READLOCKON for the batch step, and in the VSAM catalog, set the Batch Read-locking field to N for the dataset.

Situation: You want to enable batch read-locking for most situations, but you want to disable locking for some batch steps.

Recommendation: In the VSAM catalog, set the Batch Read-locking field to Y for all files, and include the relevant datasets in $KIX_READLOCKOFF for the batch steps where you want locking disabled.

Situation: You experimented with batch read-locking and now have a complex combination of environment variable settings and cluster-level settings. Your application programs are running slow and/or hanging and you want to go back to where you were before starting to experiment.

Recommendation: Unset all environment variables and set the dataset Batch Read-locking fields to N in the VSAM catalog.

Situation: Your applications contain API locks, but you do not want them honored.

Recommendation: Ensure that the cluster-level setting in the VSAM catalog is N. If cluster-level setting is Y, add the file name to the KIX_READLOCKOFF environment variable.

Situation: Your applications contain API locks and you want them honored.

Recommendation: Ensure that the cluster-level setting in the VSAM catalog is Y or add the file name to the KIX_READLOCKON environment variable.

Situation: Your applications contain API locks. You do not want the locks to be honored, but you do want batch read-locking.

Recommendation: You must modify your application programs to remove the API locks. You must also ensure that the cluster-level setting is Y, or you must add the file name to the KIX_READLOCKON environment variable.

Controlling Data Integrity

Sun MTP supplies the following additional functions for batch programs to control data integrity:


Undoes any updates that were made before the function and subsequent to any previous SYNCPT command or the start of the program.


Commits all updates. After these updates are committed, future aborts do not affect the updates.

The syntax for these functions is as follows:


Calling Syntax





The following restrictions apply after calling these functions:

When a single COBOL program is executed, by a shell script or directly, a syncpoint is issued when the program terminates. However, if you use a shell script to execute multiple COBOL programs in a single job step, the programs are considered a single run unit and the syncpoint is not issued until the job step completes. Therefore, you must terminate each COBOL program with a GOBACK statement, rather than a STOP RUN statement, to ensure that a syncpoint is issued at the end of each COBOL program, as well as when the shell script terminates.

Note - For COBOL programs running under Sun MBM, the GOBACK/STOP RUN feature behaves differently. Refer to the Sun Mainframe Batch Manager Software Migration Guide for additional information.

Because the GOBACK statement does not automatically CLOSE open files, your COBOL program must close the files before issuing the GOBACK command.

Using Recovery With Batch Jobs

Batch programs are usually long running. If recovery is in effect, records remain locked until the program that is updating them issues a syncpoint. This can cause users who run online transactions that update the same records to wait for a long time.

If you enable recovery for batch programs, your programs should issue syncpoints at intervals to commit any updates and allow other users to access the updated records. If you use recovery, write your programs so that they are restartable. That is, on a restart, the programs must not try to update records that are already committed.

Note - Recovery is ignored for files opened in OUTPUT mode, even though recovery is enabled. No special processing is done on the file when a SYNCPOINT or ROLLBACK is issued.

Long running programs can create a large recovery file. The region maintains before images in a circular file. When the end of the file is reached, the before images start again at the beginning of the file. Sun MTP ensures that no before image is overwritten if a program or transaction is still active. Instead, when an active before image is about to be overwritten, the program or transaction that wrote the before image is terminated. This requires a recovery file large enough to keep all records updated by any one program or transaction, plus any records updated by any other programs and transactions that are also active.

Therefore, for long running batch programs, turn off recovery. There are two ways to do this; the method you use depends on the batch job's execution environment.

Before starting the batch program, save the files that will be updated. If the batch programs execute correctly, you can delete the saved files. If the programs terminate in error, you can restore the saved files.

The following table summarizes the recovery procedures for batch jobs.

TABLE 15-6 Recovery Procedures for Batch Jobs


Recovery Status


Updating databases from batch jobs


Save the dataset. Before saving the dataset, use kixfile to configure the dataset for online read only
(kixfile -oY filename) or to lock the dataset for exclusive use by the batch job (kixfile -lY filename).

Process the dataset.

If the job fails, restore the saved dataset.


Without syncpoints

Set recovery on.

Process the dataset.

If the job fails, the files are recovered by Sun MTP.

It can take a long time to recover datasets to the beginning of a long running batch job.

With syncpoints

Set recovery on.

Process the dataset.

If the job fails, the files are recovered to the last syncpoint. The batch job is responsible for setting up the environment before restarting the job from the last syncpoint.

Reading databases from batch jobs (no update)

Recovery file is not used when there are no updates.

Performing Fast Writes From a Batch Program

FAST_UNIKIXVSAM is an option that enables fast writes to an open VSAM file from a batch program. To use this option, you must set the FAST_UNIKIXVSAM environment variable in the batch shell script or the Sun MBM macro job script. The value of the environment variable is the dataset name or names as defined in the FCT. Only include those datasets you need to open for output. You must set this environment for each step in the batch shell script or the macro script.

Note - This option is restricted to sequentially sorted output datasets. If a dataset has random output writes, do not include it when setting $FAST_UNIKIXVSAM.

Each dataset name must be uppercase and unique. For multiple datasets, separate each name with a colon. Currently, this option supports 10 open outputs, and you can only open KSDS primary datasets for output in fast mode.

In a batch shell script, set the environment as follows:


For Sun MBM, set the environment in the macro job script as follows:


You can also set the environment in the JCL using the Sun MBM EBMSYSCMD statement as follows. You must then translate the JCL.


When the job executes, the message Opened Dataset datasetname in fast mode is displayed and is also written to the log file. If you do not see this message, the dataset is opened in the conventional mode.

The following error messages might display:

FastOpen Allocate failed = %n

Description: If %n = -1, the dataset is already opened. If %n = -2, the limit of open datasets (10) was exceeded. This message can also be displayed if there is not enough memory to run the application.

Solution: Either reduce the number of open files or increase the process memory.

Mismatch of buffers = %n

Description: The buffers do not match.

Solution: This problem should not occur in normal operation. If it does, contact your authorized service provider.

Debugging Batch COBOL Programs

Note - This section is specific to a non-Sun MBM environment.

Sun MTP provides two tools for debugging batch programs. Each is an option of the unikixvsam COBOL runtime program.

procedure icon  To Compile a Program for Debugging

single-step bulletType the command:

$ cob -ia -C ibmcomp program.cbl

procedure icon  To Debug Using the VSAM Trace Facility

single-step bulletType the command:

$ unikixvsam -d program

The VSAM trace facility sends trace output to the file $KIXSYS/unikixmain.dbg.

The following is an example of the trace output file:

11/03/2001 10:59:38 unikixvsam :
11/03/2001 10:59:38 unikixvsam :A VSAM OPEN was issued for file  DWORK
11/03/2001 10:59:38 unikixvsam :  The command had a status of 00
11/03/2001 10:59:38 unikixvsam :
11/03/2001 10:59:38 unikixvsam :A VSAM WRITE was issued for file  DWORK
11/03/2001 10:59:38 unikixvsam :  The relative key is 1
11/03/2001 10:59:38 unikixvsam :  The command had a status of 00
11/03/2001 10:59:38 unikixvsam :
11/03/2001 10:59:38 unikixvsam :A VSAM CLOSE was issued for file  DWORK
11/03/2001 10:59:38 unikixvsam :  The command had a status of 00
11/03/2001 10:59:38 unikixvsam :

The sample output shows the file access behavior of the COBOL program. It records each time a VSAM call is made to a file, the name of the file, the type of call, the key used and the results of the access. If the program makes a large number of calls, the trace file can quickly become large. Exercise care to avoid using up available disk space. Do not use the VSAM trace facility in a production environment.

procedure icon  To Debug Using Animator

Note - This procedure is specific to a non-Sun MBM environment.

1. Compile the program.

Refer to the COBOL documentation for the options to use for Animation.

2. Create a shell script that uses unikixvsam with the -D option to execute the batch program.

For example, create a shell script named dbbat that contains the line:

unikixvsam -D BATCH001

Your shell script can contain multiple statements like this one.

3. Make the shell script executable:

$ chmod 777 dbbat

4. Start the region.

5. Execute the CEDF,ANIM transaction.

For more information about starting Animator, see To Invoke the Debug Facility.

6. On a blank transaction screen, execute the batch program using the CBCH transaction.

CBCH dbbat

7. Debug the program.

8. When you finish debugging, execute the CEDF ,OFF transaction to turn off animation.

While the shell script is executing, Animator is automatically started each time unikixvsam is invoked with the -D option.

For more information about using Animator, refer to the Animator documentation.

See also Using Animator.