C H A P T E R 3 - Development Utilities

C H A P T E R 3

Development Utilities

The utilities described in this chapter are located in the $UNIKIX/bin directory. They are useful during application development and include utilities for editing, browsing, and printing files, as well as tools for compiling programs.

`kixasm` - Sun MTP Assembler

kixasm is used for assembling basic mapping resource (BMS) maps. To invoke the kixasm shell script, press the PF4 (Assemble) key on the Set Assembler Options screen.

Format

kixasm [-c] [-l] [-o] [-y] [-9] filename

where:

`-c`	Generates a copy file.
`-l`	Generates a listing file.
`-o`	Specifies output as filename.
`-y`	Indicates a terminal device connected to the Sun MTP terminal processor.
`-9`	Indicates a temporary output file name.
filename	Indicates a concatenation of the directory and file name displayed on the Set Assembler Options screen.

`kixbms` - BMS Assembler

The kixbms assembler is invoked when the PF4 (Assemble) key is pressed on the Set Assembler Options screen or when the PF12 (Create SGU) key is pressed on the BMS Maintenance menu and a COBOL or PL/I map file is selected.

You can also run kixbms from the command prompt.

Format:

kixbms [-a] [-A] [-c] [-m {i|o}] [-s] [-q] [-t n] [-o output-filename] filename ...

where:

`-a`	Aligns the output data for the user programs. All fields, regardless of length, are aligned on even-byte boundaries. By default, all fields are allowed to start on any byte boundary. Use this option only if the SIT specifies `ALIGNED` maps. In general, do not specify this option unless it was in use on the mainframe.
`-A`	Retains the value of the `XINIT` option of the `DFHMDF` macro, if it is in ASCII code. Typically, the `XINIT` option contains hex values in EBCDIC, which the `kixbms` utility converts to ASCII.
`-c`	Depending on the value of `LANG` in the BMS file (filename), this option creates a COBOL copybook, C header file, or PL/I include file, which must be included in the user program. See TABLE 3-1.
`-m [i\|o]`	Overrides the `MODE` option of the mapset (`DFHMSD`) macro. You must follow the option with either an `i` or an `o`: `i`: `MODE` is `IN` `o`: `MODE` is `OUT`
`-o` output-filename	Overrides the default output name with the specified output name. The default output file name is the same as filename, but with the `.map` or `.sgu` extension. You can specify more than one input filename, but the `-o` option applies to the first input filename only.
`-q`	Overrides the default character for strings. The default is the apostrophe character ( ` ). When `-q` is specified, the quote character ( `"` ) is used.
`-s`	Produces an output file with a .`sgu` extension, which is used as input to the SGU for full-screen painting. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide for more information.
`-t` n	Overrides the default tab setting of eight characters. If the `-t` option is specified, you must follow it with a number from 1 to 7. When a tab character is found in the input file, it is replaced by the specified number of blanks.
filename ...	Specifies one or more file names, which are the BMS files to assemble. Required. The files must have an extension of .`bms`.

The following table shows the files that are created for each language when the -c option is used on the kixbms command.

TABLE 3-1 BMS Language Options
LANG=	Output Files	Usage
`COBOL`	`TSTMNU.map` `TSTMNU`	Map for `$KIXMAPS` COBOL copybook (`COPY TSTMNU.`)
`C`	`TESTMNU.map` `TSTMNU.h`	Map for `$KIXMAPS` C header file (`#include "TSTMNU.h"`)
`PLI`	`TSTMNU.map` `TSTMNU.inc`	Map for `$KIXMAPS` PL/I include file (`%include 'TSTMNU.inc';`)

Note - When executing kixbms, you must provide a file name, or an error message is issued.

`kixbrw` - Browse Files

This shell script is invoked when you select one or more files to browse on the File Utilities menu. The kixbrw utility uses the default editor to display the file for viewing only.

Format:

kixbrw terminaldevice files

where:

terminaldevice	Indicates the terminal device connected to the Sun MTP terminal processor.
files	Specifies the files to browse.

`kixcat` - Concatenate Files

The kixcat shell script is invoked when you select one or more files to concatenate on the File Utilities menu.

Format:

kixcat [-C filename] [-O terminaldevice] [-T filename]

where:

`-C` filename	Specifies which file to concatenate. You can provide as many `-C` options as required.
`-O` terminaldevice	Indicates the terminal device connected to the Sun MTP terminal processor.
`-T` filename	Specifies the target file name. All the `-C` files are concatenated into this file.

`kixclt` - Common Language Translator

The kixclt utility is the Sun MTP Common Language Translator. It locates and includes all copy, header, or include files before translating CICS COBOL, C, or Liant Open PL/I programs. Input file names must include one of these extensions:

`.clt`	Programs written using OS/VS COBOL
`.cl2`	Programs written using COBOL/2
`.ccs`	C programs with `EXEC CICS` commands
`.pli`, `.pl1`	Liant Open PL/I commands only
`.plt`	Liant Open PL/I with `EXEC CICS` commands
`.ppl`	Liant Open PL/I with `EXEC CICS` commands and database (Oracle) commands

The kixclt utility executes from the Sun MTP Development System for COBOL and PL/I programs or from the command line for COBOL, C, and PL/I.

From Sun MTP	On the Set Compiler Options menu, select a COBOL or PL/I file and press the Compile key (PF4).
From the command line	Use the syntax described in this section with the options you require. Then use the appropriate language compiler following the translation.

Format:

kixclt [-A] [-C] [-d oracle] [-E] [-e ex1,ex2,ex3,ex4] [-f upper|lower] [- o filename] [-q] [-r] [-t n] [-u] program . . .

where:

`-A`	Creates an audit report that displays what CICS APIs are and are not supported by Sun MTP, along with any errors that were encountered. The audit report file has a .`audlst` extension. This option does not generate translation code.
`-C`	Causes the translator to process only `COPY` statements that are located in the `LINKAGE SECTION` and `PROCEDURE DIVISION`. `COPY` statements in the `WORKING-STORAGE SECTION` are not processed. The `LINKAGE SECTION` and `PROCEDURE DIVISION` statements must be part of the `.clt` or .`cl2` source code; that is, these statements cannot be within a `COPY` file. This option is required primarily for programs that use the `oldcopy` option of the Micro Focus COBOL compiler. It is ignored for C and PL/I programs.
`-d oracle`	Indicates that programs contain Oracle SQL statements.
`-E`	Eliminates the .`audlst` file but retains a summary audit report with a `.err` extension. You must use this option with the `-A` option, or the `-E` option is ignored.
`-e` ex1,ex2,ex3,ex4	Allows up to four additional copybook extensions. You must use commas with no spaces to separate file extensions.
-f `upper\|lower`	Serves as the case indicator for copybook names.
`-o` filename	Overrides the default output name with the output filename that follows. You can specify more than one input program, but the `-o` option applies to only the first program on the command line.
program ...	Indicates file name(s) with the appropriate extension.
`-q`	Overrides the default character for strings. The default is the apostrophe character ( `'` ). When you specify `-q`, it uses the quote character ( `"` ).
`-r`	Retains the temporary output file from the copybook expansion phase. The warning and error messages in the `.err` file refer to line numbers in this temporary file.
`-t` n	Overrides the default tab setting of eight characters. When you specify the `-t` option, follow it with a number from 1 to 7. When a tab character is found in the input file, it is replaced by the specified number of blanks.
`-u`	Causes the translator to include only the `PROCEDURE DIVISION USING` information provided by the user on the `PROCEDURE DIVISION` statement, instead of allowing the translator to build the `PROCEDURE DIVISION USING` from the data in the `LINKAGE SECTION`. The translator inserts the `DFHEIBLK` and `DFHCOMMAREA` parameters as the first and second `USING` parameters followed by what the user provided. See the example that follows. This option is ignored for C and PL/I programs.

For example, when you translate the following line of code:

PROCEDURE DIVISION USING ABC_TABLE

kixclt -u displays the following line, regardless of what other 01 data is in the LINKAGE SECTION of your program:

PROCEDURE DIVISION USING DFHEIBLK DFHCOMMAREA ABC_TABLE

`kixcob` - COBOL Compiler

The kixcob shell script calls the COBOL compiler. It executes when you press the PF4 (Compile) key on the Set Compiler Options for COBOL menu screen in the Development System.

Format:

kixcob [-c] [-o] [-y] [-9] filename

where

`-c`	Sets the `COBCPY` environment variable. This passes the parameter plus any existing value of `$COBCPY`.
`-o`	Identifies the output file.
`-y`	indicates the terminal device connected to the Sun MTP terminal processor.
`-9`	Indicates the temporary output file name.
All other options are passed to the compiler without change.
filename	Indicates a concatenation of the directory and the file name displayed on the Set Compiler Options menu screen.

`kixcopy` - Copy Files

The kixcopy shell script is invoked after you select a file to copy on the File Utilities menu.

Format:

kixcopy file1 file2

where:

file1	Identifies the source file.
file2	Identifies the destination file.

`kixdlt` - Delete Files

The kixdlt shell script is invoked after you select a file to delete on the File Utilities menu.

Format:

kixdlt files

where:

files

Identifies the list of files to be deleted.

`kixecho` - Write Messages to a Terminal

The kixecho shell script is invoked to place a message on the terminal of the requestor. The message displays the name of the file being processed during compiles and assembles.

Format:

kixecho filename

where:

filename

Identifies the file being processed.

`kixed` - Edit a File

Sun MTP executes the kixed shell script whenever a file must be edited--for example, after you have selected a file and pressed PF2 (Edit) on the File Utilities menu, Compilation menu, or BMS Maintenance menu. kixed is also called to display temporary output files after shell scripts such as kixcob and kixasm terminate. kixed uses the default editor to display the file.

Format:

kixed filename terminaldevice

where:

filename	Identifies the file to edit, including the directory path.
terminaldevice	Identifies the terminal connected to the Sun MTP client.

`kixgrep` - Search Files

The kixgrep shell script is invoked after you select one or more files to be searched on the File Utilities menu. kixgrep uses the default editor to display the results for viewing only.

Format:

kixgrep (pattern) temporaryfile terminaldevice files

where:

(pattern)	Specifies a search string; must be enclosed in parentheses.
temporaryfile	Identifies the file that is to contain the output of the search operation.
terminaldevice	Identifies the ttyname of the output terminal.
files	Identifies one or more files to search.

`kixpl1` - PL/I Compiler

The kixpl1 shell script executes when you press the PF4 (Compile) key on the Set Compiler Options screen for PL/I programs. This executes the kixpl1 shell script, which calls the following:

Program/Utility	Description	File Types
`lpipp`	PL/I precompiler	All cases
`propli`	Oracle preprocessor	`.ppl`
`kixplt`	CICS translator	`.plt`
`lpipl1`	PL/I compiler	`.pl1, .pli`

If multiple files were selected, the files are compiled in reverse order (that is, the last file selected is compiled first).

At the end of the compilation, the default editor is called with the results of the compile and translation. You can change the editor by modifying kixpl1.

Format:

kixpl1 -9 vi-file [-c include-dirpath] -e suffix
-o output-file input-file.xxx -L -n -O -N -7 -A -E -X [-y terminal-dev]

where:

`-9` vi-file	Identifies the file for tracking the results of a script.
`-c` include-dirpath	Identifies the directory path where `include` files are located; multiple `-c` include-dirpath combinations are permitted. Optional.
`-e` suffix	Indicates a suffix. Choose one of the following: `.pli`, `.pl1`: Open PL/I commands only. `.plt`: Open PL/I with `EXEC CICS` commands. `.ppl`: Open PL/I with `EXEC CICS` commands and database (Oracle) commands.
`-o` output-file	Specifies an output object file. This file name does not take a suffix.
input-file.xxx	Specifies an input source where xxx is one of the suffixes described in `-e` suffix.
Single-letter arguments	These arguments are optional, depending on the `Y`/`N` response on the Set Compiler Options screen for PL/I. A description of these arguments is found in the Liant Open PL/I User's Guide.
`-A`	Position independent code.
`-E`	Allows CodeWatch to debug `EXEC CICS` precompiler-generated code.
`-L`	Used for debugging with CodeWatch.
`-N`	Produces storage allocation map in listing.
`-n`	Produces an expanded listing.
`-O`	Indicates the level of optimization.
`-X`	Indicates unaligned PL/I structures at level 1.
`-7`	Specifies the use of CodeWatch.
`-y` terminal-dev	Specifies a terminal device connected to the Sun MTP terminal processor. Omit this parameter on a command line.

`kixplt` - PL/I Command Language Translator

kixplt is the Sun MTP Command Language Translator for PL/I. The utility locates and includes all copy files before translating CICS statements to PL/I statements. Input file names must include one of the following extensions:

`.pli`, `.pl1`	Liant Open PL/I commands only.
`.plt`	Liant Open PL/I with `EXEC CICS` commands.
`.ppl`	Liant Open PL/I with `EXEC CICS` commands and database (Oracle) commands.

This utility executes from the Development System or from the command line.

From Sun MTP

Press the Compile key (PF4) on the Set PL/I Compiler Options screen. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide for additional information.

This executes the kixpl1 shell script, which calls the Liant Open PL/I compiler, the Oracle precompiler (.ppl extension), or preprocessing translator, depending on the file name extension of the source file.

If multiple files were selected, the files are compiled in reverse order (that is, the last file selected is compiled first and the first file selected is compiled last).

From the command line

To compile the translated source code, follow the kixplt call with a call to lpipl1. Refer to the Liant Open PL/I User's Guide for a description of the arguments to this command.

Format:

kixplt -i filenam.plt -o outfile.pli

where:

`-i` filenam.plt	Specifies an untranslated input source.
`-o` outfile.pli	Specifies a translated output PL/I source ready to be used as input to `lpipl1`.

You can use this utility from the command line instead of using kixclt.

Note - You must use the correct extension for the PL/I source programs because the translation is based on the extension of the input file.

`kixprt` - Print a File

The kixprt shell script is invoked when you select a file to print on the File Utilities menu.

Format:

kixprt filename(s)

where:

filename(s)

Identifies the name(s) of files to print.

`kixrnm` - Rename a File

The kixrnm shell script is invoked when you select a file to rename on the File Utilities menu.

Format:

kixrnm file1 file2

where:

file1	specifies a source file.
file2	Specifies a destination file.

`kixsgu` - Create an SGU

The kixsgu shell script is invoked when you press the Create SGU (PF12) key on the BMS Maintenance menu.

Open the BMS Maintenance menu by pressing PF9 (Screen Generation Utility) on the Development System main menu, and then pressing PF5 (List BMS) on the Maps Maintenance menu.

Format:

kixsgu [-o filename] [-y device] [-9 tempfile]

where:

`-o` filename	Identifies the output file.
`-y` device	Identifies the terminal device connected to the Sun MTP terminal processor.
`-9` tempfile	Identifies a temporary output file.

`kixsh` - Start a Shell

The kixsh shell script executes when you press the Execute in UNIX (PF10) key on the Development System main menu.

There are no parameters passed to this shell script. The shell defaults to the Bourne shell unless the SHELL environment variable is set to a different shell.

Format:

kixsh

kixasm - Sun MTP Assembler

kixbms - BMS Assembler

kixbrw - Browse Files

kixcat - Concatenate Files

kixclt - Common Language Translator

kixcob - COBOL Compiler

kixcopy - Copy Files

kixdlt - Delete Files

kixecho - Write Messages to a Terminal

kixed - Edit a File

kixgrep - Search Files

kixpl1 - PL/I Compiler

kixplt - PL/I Command Language Translator

kixprt - Print a File

kixrnm - Rename a File

kixsgu - Create an SGU

kixsh - Start a Shell

`kixasm` - Sun MTP Assembler

`kixbms` - BMS Assembler

`kixbrw` - Browse Files

`kixcat` - Concatenate Files

`kixclt` - Common Language Translator

`kixcob` - COBOL Compiler

`kixcopy` - Copy Files

`kixdlt` - Delete Files

`kixecho` - Write Messages to a Terminal

`kixed` - Edit a File

`kixgrep` - Search Files

`kixpl1` - PL/I Compiler

`kixplt` - PL/I Command Language Translator

`kixprt` - Print a File

`kixrnm` - Rename a File

`kixsgu` - Create an SGU

`kixsh` - Start a Shell