C H A P T E R 4 |
Application Utilities |
The utilities described in this chapter are located in the $UNIKIX/bin directory. These utilities are useful in managing application files and tables.
The kixcisam utility executes C programs that are not defined as resources within Sun MTP but access VSAM files.
Before running kixcisam, you must perform the following tasks:
Refer to the Sun Mainframe Transaction Processing Software Developer's Guide for detailed procedures.
You can use the kixfile utility to dynamically change the status of a given dataset, including the associated alternate datasets. Depending on the options you specify, you can disable the specified dataset or give it limited access to certain types of processes. You can execute the utility only from a shell script running as a batch job while a region is executing.
kixfile {[{-b|-d|-f|-l|-o} Y|N [-r Y|N|C]] | [-c] | [-p]}
[-X VSTIME] dataset
When multiple datasets refer to the same physical file, the following additional rules apply:
The file can have more than one lock specified at a time, but the most restrictive of the specified locks is the one in effect. For example, if you specify both the -o and
-b locks on the same file, option -b overrides option -o.
You can issue the -o, -b, -d, and -l locks before the dataset is opened. When this is done, the dataset is opened based on that option. For example, if you specify kixfile -o Y dataset followed by kixfile -f N dataset, the dataset is opened for online read only.
If the file is opened for output by a batch program, you can use only the -p option online, which prints the status of the dataset.
If any process accesses a file locked by kixfile, it might receive a DISABLED (84) error status for online transactions, or (35) for batch programs, depending on the lock.
The following examples describe how the locking options work.
Online transactions encounter a NOTOPEN (19) status when trying to access the file using the name dataset1, and batch programs encounter a status (35).
dataset2 is read only for online access.
Online transactions encounter a DISABLED (84) status for any read for update or write/delete/rewrite requests using dataset2.
dataset3 is locked exclusively for the batch system.
Online transactions encounter a DISABLED (84) status for all requests using any dataset for that file.
dataset4 is locked exclusively for this batch job and recovery is disabled for dataset4.
Online transactions encounter a DISABLED (84) status for all requests using any dataset for that file. Batch programs other than programs in this batch job encounter a status (35).
Updates to this batch job are not recoverable.
dataset5 is read only for online and batch.
Online transactions encounter a DISABLED (84) status for any read for update or write/delete/rewrite requests using dataset5.
Batch programs encounter a status (35) if they try to open the file using that dataset for I/O. With all the dataset alias names to that file in this systemwide read-only mode, you can execute unikixbld to create a sequential file while the file is still available for reads.
If you associate multiple datasets to the same file, you must understand the behavior of kixfile when changing the status of any of those datasets. When either the -b or -1 locks are requested on any dataset associated with a file, kixfile quiesces activity by all datasets associated with the file in order to set this status. When other current dataset activity is affected by this quiescing activity, kixfile displays the following message:
After setting either of the locks, activity through any of the datasets for that file is affected equally. Resetting the lock removes the effect of that lock on all datasets for that file.
If you close a dataset with the -f option or set a dataset to read-only with the -o or -d option, kixfile also quiesces activity on all datasets associated with that file until the requested dataset is closed or set to read-only. kixfile displays the same message when other current dataset activity is affected. However, the closed/read-only status of that dataset affects only requests using that dataset.
To physically close a file that has multiple datasets (for example, to do backups), you must close all datasets using kixfile. Run kixfile -p using any dataset name to check that the status reports PHY_CLSD.
It is also necessary to run kixfile -o/-d on all datasets associated with the same physical file to ensure that read-only access to the file is permitted. To verify this, run kixfile -p on all datasets associated with the file to check for read-only status.
A message is displayed when kixfile is executed with the -p option.
Dataset dataset-name [PHY_OK|PHY_NOTOK], [PHY_CLSD|PHY_OPND], [RDONLY], [PEND], [RECOVOFF|RECOVON], [BTCH_OUTPUT], [JOB], [UBLD], [BTCH_ONLY], [OPEN_ONL|CLSD_ONL], [ENBLD_ONL|DSBLD_ONL], [ONL_RDONLY], [OPEN_BCH|CLSD_BCH], [ENBLD_BCH|DSBLD_BCH], [BCH_RDONLY]
Indicates that an error occurred on opening the file for this dataset. For example, file permissions disallow access, or the file does not exist. |
|
Indicates that the system knows about the file for this dataset and its attributes. The next option indicates whether it is currently accessible. |
|
Indicates that the file for this dataset is open and is accessible. |
|
Indicates that the file for this dataset is open for read only, due to file permissions. |
|
Indicates that the file has an exclusive lock pending. For example, some other process has requested the file for exclusive use or is changing the status of one of its datasets. When this lock is in effect, only the transactions or batch programs already accessed by any of the datasets are allowed. |
|
Indicates that the file for this dataset is opened for output by a batch program or by unikixbld. |
|
Indicates that the file for this dataset is locked for exclusive use by a process, such as unikixbld or a batch job stream. At the end of the batch job or shell script, the lock is automatically released. |
|
Indicates that unikixbld has locked the file for this dataset. See unikixbld - VSAM File Builder. |
|
Indicates that the only batch programs can access the file for this dataset. |
|
Indicates that the dataset is open and is accessible by online transactions. |
|
Indicates that the dataset is closed to online transactions. |
|
Indicates that the dataset is enabled for online transactions. |
|
Indicates that the dataset is disabled for online transactions. |
|
Indicates that the online transactions can only read, not write, the dataset. |
|
Indicates that the dataset is open and is accessible by batch jobs. |
|
Indicates that the dataset is closed and is not accessible by batch jobs. |
|
Indicates that the batch jobs can only read, not write, this dataset. |
If the option is not set, an empty field is displayed instead of the keyword. For example, if a dataset is opened for batch only, with recovery on, the following message is displayed:
If you have defined your VSAM files as recoverable and fail to adhere to the following restrictions when using kixfile batch shell scripts, your data might be corrupted and the files might be unrecoverable.
The kixjas shell script extracts the accounting data portion of the accounting records in the journal file. The conversion program, kixjas, reads a region's journal file and creates an ASCII file containing the same information but excluding accounting journal header information. The program can extract specific types of accounting records, either transaction ID records (record type 0001) or user records (record type 0002).
Note - This affects only accounting records generated by means of the SIT, SNT, and PCT options, not accounting records generated by application programs. |
kixjas -o outputfile [-c [nn]] [-t {tranid|userid}]
-i inputfile1, inputfile2, ...
The following command writes ASCII record formats to the out1 file, processes four accounting journal files, and places the report in the file named report.
You must type the command arguments in the order specified; otherwise the command will fail.
The Sun Mainframe Transaction Processing Software Administrator's Guide, which describes the format of the report file.
The kixjournal shell script processes the current journal file. kixjournal is called when a journal file has reached its maximum size.
By default, kixjournal writes messages to the unikixmain.log file indicating that the journal file was processed. If further processing, such as copying the file to a tape, is required, you must modify the shell script.
The kixlog utility provides an interface between Sun MTP's shell scripts and log files, unikixmain.log, unikixmain.err and unikixmain.dbg. The utility enables you to place a string in the log file of your choice. For example, the kixjournal shell script uses kixlog to write messages to unikixmain.log.
You can only execute this program in a shell script executed by Sun MTP. Sun MTP-invoked batch programs that execute in a shell script can also use the kixlog utility.
Specifies the message to place in the log file. Quotes are required if any spaces are included in the message. By default, string is written to the unikixmain.log file. |
For example, the following command places a message in the unikixmain.log file.
The entry in the unikixmain.log file is as follows:
where date and time are replaced with the date and time that kixlog was executed.
The kixtran command starts a transaction from a batch script or from the shell prompt. You can use this utility in a script that is submitted at the prompt or with the UNIX at and cron commands.
Identifies the requested transaction. If the transaction contains more than one word, enclose it in quotation marks. For example: |
You cannot use this command for conversational transactions or for transactions that require map input. The transaction can display output, but you cannot respond to what is displayed.
The unikixbld utility is used to manipulate VSAM files from a batch job. unikixbld performs these functions:
Refer to the Sun Mainframe Transaction Processing Software Developer's Guide for examples of the use of unikixbld.
unikixbld -d dataset -2 -l bytes -r format -s filename ... -t s -v n-rec
unikixbld -d dataset -2 -f percent -m -r format -s filename ... -t v
unikixbld -d dataset -f percent -t a [-M altkey-mem]
unikixbld -d dataset -p [reuse|noreuse] [-k{replace|noreplace}] -W nnn -V
unikixbld -d dataset -t x -X ALL
Indicates that the header record is 2 bytes instead of the default 4 bytes, if the record format is variable (-r recordv). This applies for both exporting and importing of files. The record header contains the length of the record. |
|
Appends records to a target ESDS file. This option is maintained for backward compatibility in this release. Use the -p reuse option for the same functionality. |
|
Identifies the dataset to process. dataset refers to a dataset defined in the FCT. This parameter is required. If dataset is blank and the -t s option is set, the specified sequential file is created and is empty. |
|
Specifies the fill percentage, which is the amount of free space to leave in each VSAM block. percent is any number from 0 to 99. If you do not use this parameter, the fill percentage defaults to 0. |
|
unikixbld does not expect the file to be closed before initializing. If the file is accessed by online and/or batch, unikixbld quiesces the file, locks it, initializes it, and releases it for further processing. If reuse is specified in the VSAM catalog, or noreuse is specified and the file contains no records, then the file is initialized. |
|
Specifies whether the source file record will replace the target VSAM file record.
The -k arguments have meaning only when the
Relative record datasets (RRDS) are not currently supported. |
|
Builds sequential files from a VSAM dataset. bytes specifies the maximum number of bytes to place in a sequential file. When this number of bytes is reached, the next sequential file is used. This number can be exceeded in the last file, if an insufficient number of sequential files are specified. This value can have a suffix of K, M, or G, which specifies kilobytes, megabytes, or gigabytes, respectively. Use this parameter when building a sequential file that is larger than available disk devices (spanned file). |
|
Merges multiple sequential files. Use this option when building a VSAM file from multiple sequential files when the keys are not in ascending order from file to file. This option is not applicable to customized record processing formats such as the mfrcd format. Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide. |
|
Specifies the amount of space (in MB) allocated by the internal sort utility when alternate keys are sorted. This argument is ignored if there are no alternate keys for the VSAM output file. |
|
Specifies whether the target VSAM file should be reinitialized.
RRDS files are not currently supported for any combination of -p and -k arguments. |
|
Specifies the record format to use when creating or accessing a sequential file. format is either one of the Sun MTP-supported record formats or a custom record format created using the procedure specified in the Sun Mainframe Transaction Processing Software Administrator's Guide. If you do not use this parameter, the format defaults to record. The supported record formats are:
Sun MTP-supplied customized record format:
Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for information about customizing record processing routines. |
|
Identifies a file name that specifies a full or relative path name to use for the sequential file. A relative path name is relative to the directory specified by the KIXSYS environment variable. When exporting to a non-VSAM file, filename is the file to which the VSAM records are written in the format specified in the -r option. When building a VSAM file, filename is the file from which the records are read in the format specified in the -r option. When building a VSAM file, also note that:
You can specify up to 50 sequential file names. If the input dataset is blank and the -t v option is set, filename is initialized just as if the -i parameter were set. |
|
Specifies the output file type: a: Rebuilds an alternate index file. s: Creates a sequential file from a VSAM file (see the -d option). v: Creates a VSAM file from a sequential file (see the -s option). |
|
Displays an informational message after n-rec records are processed. This enables you to view the progress of unikixbld. |
|
Indicates the verbose option. If specified, "duplicate record" keys are written to the log file. See the -k noreplace description. If not specified, no "duplicate record" keys are logged. The log information is a two-line entry that shows the key in both hexadecimal and alphanumeric formats, along with the record number of the input record that contains the duplicate key. For example: |
|
Specifies the number of input records that are passed for each syncpoint whether or not recovery is specified on the target VSAM file. The default (-W is not specified) means that no syncpoint is done until the end of the job. nnn must be greater than zero. This argument applies only if -p noreuse is specified. If you are working with recoverable files, specify the
|
|
Displays statistical information. Valid arguments are: ALL: Displays both sets of statistics. |
For sequential-to-VSAM file processing, unikixbld operates in two modes: load and update.
In load mode, unikixbld performs the following actions:
1. Locks the file for exclusive control.
2. Creates a temporary data and index file for the VSAM file.
3. Loads the records into the temporary data file.
4. Builds the temporary index file from the temporary data file.
5. Builds any existing alternate files for each alternate file, as in steps 3 and 4.
6. Copies the temporary files to VSAM files.
If unikixbld fails to complete, the temporary file is discarded and the VSAM file is the same as at the beginning of the load process.
In update mode, unikixbld acts like a transaction. When unikixbld is replacing or adding a record from the source sequential file, the VSAM file can be accessed by online and batch utilities. If recovery is enabled for the VSAM file, the record is not available for updating until unikixbld commits the record. This suggests that unikixbld can be a candidate for deadlock situations. If unikixbld fails to complete, the records added or updated since the last syncpoint are restored. If exclusive control of the file is required in update mode, kixfile must be used to lock the file.
Arguments that apply to unikixbld executing in the update mode are: -k, -p, -W, and -V.
This section describes issues to be aware of when using unikixbld.
Observe the following restrictions when using unikixbld batch shell scripts:
If your VSAM files are defined as recoverable and you fail to adhere to these restrictions, your data might be corrupted and the files might be unrecoverable if you perform an asynchronous manual termination.
The -k and -p arguments are for unikixbld sequential file-to-VSAM file processing. VSAM-to-VSAM processing is not supported.
The -k and -p arguments are valid only for KSDS and ESDS VSAM file types. If you use them with RRDS files, unikixbld terminates the process and issues an error message.
If you are using the mfrcd record format for input or output with unikixbld, and your files exceed 2 GBytes in size, read this section and perform the necessary configuration tasks.
Depending on your application, this file can contain other statements as well.
To execute a COBOL program inside a shell script, you must execute the program using the unikixvsam COBOL runtime system. You can pass parameters to the COBOL program by including them on the unikixvsam command line. The debugging options of unikixvsam are described in the Sun Mainframe Transaction Processing Software Developer's Guide.
unikixvsam [-d|-D] progname ["parameters"]
[-X {ALL|VSTIME|WTIME|LIO|PIO|}]
If you have defined your VSAM files as recoverable and fail to adhere to these restrictions when using unikixvsam batch shell scripts, your data might be corrupted and the files might be unrecoverable.
You must copy programs or shell scripts into a $KIXBTCH directory. Do not move files into $KIXBTCH because after the programs start, they are deleted. When the region looks for programs to execute, it attempts to execute each file in the directory that is executable or that has a .gnt or .int extension. Therefore, use $KIXBTCH directories exclusively for Sun MTP batch programs and shell scripts that are awaiting execution.
Copyright © 2004, Sun Microsystems, Inc. All rights reserved.