Sun Mainframe Transaction Processing Software Developer's Guide

Sun MTP supports two batch environments:

• Standard batch: Controls batch processing for COBOL programs or files of executable commands (shell scripts).

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

• Sun MBM: Executes batch jobs in a controlled environment. Refer to the Sun MBM documentation for additional information.

This chapter contains the following topics:

• Configuring the Batch Environment
• Batch Tasks
• Overriding the Batch Search Interval
• Maintaining Data Consistency
• Controlling Data Integrity
• Using Recovery With Batch Jobs
• Performing Fast Writes From a Batch Program
• Debugging Batch COBOL Programs

---

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:

• Define the KIXBTCH environment variable, which defines the directory where batch programs are waiting to execute. This applies to a non-Sun MBM environment.
• Set the batch parameters in the VSAM Configuration Table (VCT). See Setting the VCT Batch Fields.

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.

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]]:...

where:

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

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.

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:

• Execute operating system-specific jobs, such as backing up files
• Execute COBOL, C, and PL/I applications that access VSAM datasets
• Use the unikixbld and kixfile utilities to manage VSAM datasets
• Use the dfhusdup utility to manage resources
• Use other batch utilities that do not affect VSAM datasets

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:

• The Micro Focus file organization is accessed for sequential files.
• The Sun MTP file organization is accessed for indexed or relative records.

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:

• Physical sequential files:

ASSIGN TO name ORGANIZATION IS SEQUENTIAL ORGANIZATION IS LINE SEQUENTIAL ORGANIZATION IS RECORD SEQUENTIAL

• VSAM relative files:

ASSIGN TO name ORGANIZATION IS RELATIVE

• VSAM indexed files:

ASSIGN TO name ORGANIZATION IS INDEXED

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

• When the program is invoked, the file to be read is name, which is the dataset to be accessed.
• The name is 1 to 8 characters and is associated to the physical file through the VSAM catalog and the FCT. Because VSAM access requires the VSAM catalog and the FCT, not all of the options available through Micro Focus COBOL for specifying files are available through Sun MTP.

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.

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.

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.

for i in `ls *.cbl`

do

	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

	ReturnCode=$?

	if [ $ReturnCode -ne 0 ]

		then

		echo "Error detected during cob of `basename $i .cbl`" >> COMPALL.err

		else

		echo "Compile completed for `basename $i .cbl`" >> COMPALL.err

	fi

done

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.

Copy the program to the $KIXBTCH directory.

The program will be executed based on the batch search interval

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.

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

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:

LINKAGE SECTION.

01  PARAMETER-AREA.

	05  PARAMETER-LENGTH PIC 9(04) COMP.

	05  PARAMETER-DATA PIC X(80).

PROCEDURE DIVISION USING PARAMETER-AREA.

1000-START.

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

Setting Return Codes

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:

SET RETURN-CODE TO 1.

GOBACK.

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"

cond=$?

if [$cond -ne 0]

then

		echo "RAM59 ERROR CODE = $cond"

		exit $cond

fi

Executing PL/I Batch Programs

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

Executing C Language Batch Programs

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.

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.

1. Create a shell script.

$ vi cbat01.sh

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

batch/bat001

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:

• Builds VSAM files from sequential files
• Builds sequential files from VSAM files
• Initializes VSAM files
• Rebuilds index files from VSAM data files
• Rebuilds alternate index files from VSAM data files
• Merges multiple sequential files into a single VSAM data file

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.

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:

• Set the status to open or closed
• Set the online status to read or read/write
• Set the batch status to batch access only or batch/online access
• Set the lock status to exclusive lock or unlock
• Set permissions to read only or reset to status at startup
• Set the recovery status to enable recovery, disable recovery, or enable use of system cache for the VSAM file, along with disabling recovery
• Print the current dataset status

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

DEFINE GROUP (SALES1) PROGRAM (SAL001) DESCRIPTION (Daily sal*

	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

INITIALIZE

DEFINE GROUP (SALES1) PROGRAM (SAL001) DESCRIPTION (Daily s*

	ales program)

DEFINE GROUP (SALES1) MAPSET (SALAD01) DESCRIPTION (Daily sal*

	es add screen)

DEFINE GROUP (SALES1) MAPSET (SALDE01) DESCRIPTION (Daily sal*

	es delete screen)

DEFINE GROUP (SALES1) MAPSET (SALMF01) DESCRIPTION (Daily sal*

	es modify screen)

LIST ALL OBJECTS

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

DELETE GROUP (SALES1) PROGRAM (OLDPGM)

DELETE GROUP (SALES1) MAPSET (OLDMAP)

!

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'

COPY GROUP (SALES1) TO (SALES2)

!

Sun MTP Batch Utilities That Do Not Affect VSAM Datasets

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

• kixlog provides an interface between the Sun MTP shell scripts and the Sun MTP log files, unikixmain.log, unikixmain.err and unikixmain.dbg. The kixlog utility enables you to place a string in the log file of choice. Refer to the Sun Mainframe Transaction Processing Software Reference Guide for more information.
• kixtran starts an Sun MTP transaction from batch or from the shell prompt. Refer to the Sun Mainframe Transaction Processing Software Reference Guide for more information.

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.

• For unikixvsam, you can display the statistics:
• Time spent in VSAM code (-X VSTIME)
• Wait times (-X WTIME)
• Logical I/O (-X LIO)
• Physical I/O (-X PIO)

• For unikixbld, you can display the statistics:
• Physical I/O (-X PIO)
• Wait times (-X WTIME)

• For kixfile, you can display the time spent in VSAM code (-X VSTIME).

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

---

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.

Format

CBCH batch-program

where:

---

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:

• Data integrity can be maintained while a batch program shares files with online and other batch programs concurrently.
• An application's batch window can be shortened, allowing for longer online availability.

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

• Application Design Issues
• Changing Existing Batch Programs for 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.

VSAM RC

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.

• If recovery is off, the batch program holds the record lock until another VSAM I/O is issued on the file.
• If recovery is on and the batch program updates the record, the lock is held until the next COMMIT, ROLLBACK, or end of the program. If the batch program does not update the record, the lock is held until another VSAM I/O is issued on the file.

Limitations of VSAM RC

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

• VSAM RC only applies to a file (dataset) if it is opened in I-O mode. It is not applicable if the file is opened in INPUT, OUTPUT, or EXTEND mode, even though VSAM RC is enabled.
• The Sun MTP software permits only one record to be available for exclusive locking for each dataset for a program. This is true for files that are opened multiple times using different SELECT clauses that point to the same file. This is very important because if a READ is issued with lock, VSAM holds the record on behalf of the batch program. If a REWRITE or DELETE to a different key is issued, Sun MTP discards the lock on the record and acquires a lock on the record on which the REWRITE or DELETE was issued.
• VSAM RC is not supported on alternate key files, including opening an alternate key file as primary file.
• If you use the ANSI COBOL API, the following options are supported. Using any other options results in an error.
• In a SELECT clause, LOCK MODE IS AUTOMATIC
• In a SELECT clause, LOCK MODE IS MANUAL
• In a READ verb, READ WITH LOCK, READ WITH NO LOCK, READ NEXT WITH LOCK, READ NEXT WITH NO LOCK, READ PREVIOUS WITH LOCK, READ PREVIOUS WITH NO LOCK
• UNLOCK
• COMMIT
• ROLLBACK

• All of the VSAM RC functionality is supported for standard batch. For programs that use C-ISAM, use the VSAM catalog and the environment variable settings to ensure read consistency. Program-level locking in C-ISAM is not supported in this release.

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:

• Batch window

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.

• Shared resources

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.

• Time estimates

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.

• Operational changes

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:

• Shared memory size

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.

• Recovery file size

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:

• Deadlocks

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.

• File sharing

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.

• Selective exclusive record locks

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:

• Periodic release of resources

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.

• Restart of batch steps

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

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.

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.

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:

• When the cluster-level setting is Y or when the dataset is listed in $KIX_READLOCKON, the API is honored.
• When the cluster-level setting is Y, but the dataset is listed in $KIX_READLOCKOFF, the API is not honored.

TABLE 15-5 shows that:

• When the cluster-level setting is N, but the dataset is listed in $KIX_READLOCKON, the API is honored.
• When the cluster-level setting is N, or the dataset is listed in $KIX_READLOCKOFF, the API is not honored.

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:

The syntax for these functions is as follows:

The following restrictions apply after calling these functions:

• If any sequential access was being made to a VSAM dataset, the current record pointers are closed and must be re-established.
• Do not call these functions if any open output datasets are being written.

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.

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.

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.

• Turn off recovery for all datasets for the region by not defining a file or raw FS device in the VCT. Shut down and restart the region to put the change into effect.
• Turn off recovery for specific datasets with the kixfile command. The kixfile command overrides the recovery setting for an individual dataset in the FCT. Refer to the Sun Mainframe Transaction Processing Software Reference Guide for information about kixfile.

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.

---

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.

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:

FAST_UNIKIXVSAM=ACCT1:ACCT2;export FAST_UNIKIXVSAM

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

setenv FAST_UNIKIXVSAM ACCT1:ACCT2

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

//*EBMSYSCMD setenv FAST_UNIKIXVSAM ACCT1:ACCT2

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

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

• The -d option outputs a trace of the VSAM activity.
• The -D option activates the COBOL Animator.

Type the command:

$ cob -ia -C ibmcomp program.cbl

Type 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.

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.

Sun Mainframe Transaction Processing Software Developer's Guide

816-5329-11

Copyright © 2004, Sun Microsystems, Inc. All rights reserved.