OSC Applications

This chapter describes tasks that must be performed before executing applications that implement business logic.

1. Overview

Application programs that run on the OSC system are written in COBOL or PL/I programming language. Unlike conventional COBOL and PL/I programs, OpenFrame COBOL and PL/I programs use EXEC CICS, EXEC DLI and EXEC SQL statements to access system resources.

Generally, application source code for the application servers are extracted from the customer’s mainframe legacy system. These source files can be used without modification to the original application logic. After the application sources are compiled to generate binaries, they are deployed and, if necessary, are preprocessed ("cleansed"). After the deployed programs are registered to the OSC SD table as program resource definitions, they can be used when the OSC system is started.

This chapter describes preparatory steps for development of OSC applications through a Unix shell.

  1. Applications can be developed with OpenFrame Studio as well. Refer to OpenFrame Studio User Guide for more information.

  2. When using maps in OSC application programs, the maps must be developed and prepared at the same time in order for the programs to run successfully. For more information about generating maps, refer to OpenFrame OSC Mapping Support Guide.

2. Source Code Preprocessing

Source code preprocessing is a process that allows COBOL application program source files that were written for the use with the mainframe CICS system to be compiled with the Unix COBOL compiler.

The following describes COBOL and PL/I application program source code preprocessing.

  • COBOL

    The COBOL source code preprocessing process consists of the following four steps.

    1. COBOL syntax preprocessing (cobolprep)

    2. OSC COBOL syntax preprocessing (osccobprep)

    3. EXEC DLI command statement preprocessing (dliprep)

    4. EXEC CICS command statement preprocessing (osccblpp)

      All COBOL programs that use the EXEC CICS command must be preprocessed by osccblpp. cobolprep, osccobprep and dliprep can be used optionally as needed.

  • PL/I

    PL/I program preprocessing is performed in the EXEC CICS syntax preprocessing (oscplipp) step. All PL/I programs using the EXEC CICS command must be preprocessed by the oscplipp tool.

  • C

    C program preprocessing is performed in the EXEC CICS syntax preprocessing (osccprep) step. All C programs using the EXEC CICS command must be preprocessed by the osccprep tool.

For more information about how to use each tool mentioned in this section, refer to OpenFrame Tool Reference Guide. You can also see more details on options by running the [-h] option from the system shell.

2.1. cobolprep

The cobolprep tool is a preprocessing tool that can convert COBOL syntax.

The underlying architectural differences between the mainframe and open system environments, as well as differences between the UNIX COBOL compiler and the mainframe COBOL compiler, mean that COBOL syntax used in mainframe must be converted into statements that can be understood by the UNIX compiler.

There are two main cases where COBOL program source files need to be preprocessed.

  • If the compiler in the open system environment cannot understand or support the COBOL syntax used by the mainframe

  • If the COBOL program source files used in the mainframe contain references to certain functions that can only be supported through preprocessing

The following example preprocesses the COBTEST.cob file to create a file named cobolprep_COBTEST.cob in the current directory.

$ cobolprep COBTEST.cob

2.2. osccobprep

Some statements in COBOL programs are not processed by the Unix compiler because of the differences between mainframe and Unix environment characteristics. The osccobprep tool preprocesses these statements so that COBOL programs can be used in OSC, and can also be used to add commands for the OSC system or to enable debugging. Currently, this tool preprocesses BLL (Base Locator for Linkage), BMSMAPBR, and EDF.

Unless an output filename is given or the prefix option is set, the output filename has the "osccobprep_" prefix attached to it.

BLL is a unique grammar structure which is supported by OS/VS COBOL or older versions of IBM mainframe COBOL compilers. For more information, refer to IBM CICS Application Programming Guide.
Usage

The osccobprep tool can be invoked as follows:

Usage: osccobprep [options] file

  • [options]

    Option Description

    [-V]

    Runs in verbose mode.

    [-a]

    Preprocesses BMSMAPBR.

    [-b]

    Preprocesses BLL.

    [-c]

    Specify this when using the dynamic CALL function or CBLPSHPOP function. This is a fundamental function of the OSC system, and therefore it is recommended that it is used by default.

    [-d]

    Specify this when using the EDF function.

    [-f postfix]

    Specifies the extension of the copybook file (If a period (.) is used, it must be included here).

    [-p dir]

    Specifies the directory path to the copybook file.

    [-o1 prefix]

    Specifies the prefix of the result file.

    [-o2 file]

    Specifies the name of the result file. If the [-o1] and [-o2] options are used together, the [-o2] option has a higher priority.

    [-h]

    Displays help information for osccobprep.

    [-v]

    Displays version information for osccobprep.

  • Input parameter

    Parameter Description

    file

    Specifies the file to be preprocessed.
Examples

The following example preprocesses TESTCOB.cob with osccobprep to create the osccobprep_TESTCOB.cob file. The copybook extension used in the program is .cob and the copybook directory path is set to $OPENFRAME_HOME/osc/Copybook.

$ osccobprep -b -f .cob -p $OPENFRAME_HOME/osc/Copybook TESTCOB.cob

2.3. osccblpp

The osccblpp tool preprocesses the EXEC CICS command within the COBOL source code used by OSC. If no option is specified, a file is created with a name containing a prefix "osccblpp_".

Usage

The osccblpp tool can be invoked as follows:

Usage: osccblpp [-c] [-nl] [-ne] [-n] [-V] [-p <prefix>] <file> ...
     | osccblpp [-c] [-nl] [-ne] [-n] [-V] [-p <prefix>] [-o <output>] <file>
     | osccblpp [-h | -v]

  • [options]

    Option Description

    [-c]

    Does not add DFHCOMMAREA.

    [-n]

    Does not pre-process the EXEC CICS command.

    [-nl]

    Does not modify DFHCOMMAREA DFHEIBLK in the LINKAGE SECTION and PROCEDURE DIVISION.

    [-ne]

    Does not add DFHEIBLK to LINKAGE SECTION.

    [-o output]

    Specifies output file name.

    [-p prefix]

    Specifies output file name prefix.

    [-V]

    Runs in verbose mode.

    [-h]

    Displays help information for osccblpp.

    [-v]

    Displays version information for osccblpp.

  • Input parameter

    Parameter Description

    file

    Specifies the COBOL files to be preprocessed. Multiple files can be specified.
Examples

The following example creates the file osccblpp_SAMPLE00.cob by preprocessing SAMPLE00.cob.

$ osccblpp SAMPLE00.cob

2.4. oscplipp

The oscplipp tool preprocesses EXEC CICS commands within OpenFrame/OSC PLI application program source. The results of preprocessing are saved as a file with the prefix 'oscplipp_' added to the input filename.

Usage

The oscplipp tool can be invoked as follows:

Usage: oscplipp [options] file ...

  • [options]

    Option Description

    [-d]

    Displays debug messages related to preprocessing.

    [-f]

    Adds a FETCH sentence for an external procedure call.

    [-l]

    Displays debug messages generated by the scanner.

    [-m]

    Specifies that the program is run by connecting to MF-COBOL.

    [-o file]

    Specifies the name of the file where preprocessing results will be saved.

    [-y]

    Displays debug messages generated by the parser.

    [-I dir]

    Specifies the name of a directory in which to search for an include file.

    [-V]

    Runs in verbose mode.

    [-h]

    Displays help information for oscplipp.

    [-v]

    Displays version information for oscplipp.

  • Parameter

    Parameter Description

    file

    Specifies the PL/I program source file to pre-process. It is possible to specify multiple modules of the PL/I program source file.
Examples

The following example preprocesses the sample00.pli fileto create a file named oscplipp_sample00.pli.

$ oscplipp sample00.pli

2.5. osccprep

Some statements in C programs are not processed by the Unix compiler because of the differences between mainframe and Unix environment characteristics. The osccprep tool preprocesses these statements so that C programs can be used in OSC, and can also be used to add commands for the OSC system.

Unless an output filename is given or the prefix option is set, the output filename will have the "osccprep_" prefix attached to it. If the -o option is not specified, the resulting file extension will be ".c".

The osccprep tool adds the dfheiptr.h header file provided by OSC and converts commands that start with EXEC CICS into functions provided by OSC during preprocessing.

Since the resulting file extension is ".c" unless the -o option is used, the input file extension cannot be ".c".
Usage

The osccprep tool can be invoked as follows:

Usage: osccprep [-p <prefix>] [-o <output>] [-V] <file> ...
     | osccprep [-h | -v]

  • [options]

    Option Description

    [-p <prefix>]

    Specifies the prefix of the result file.

    [-o <output>]

    Specifies the name of the result file. If [-p] and [-o] options are used together, the [-o] option has a higher priority.

    [-V]

    Runs in verbose mode.

    [-h]

    Displays help information for osccobprep.

    [-v]

    Displays version information for osccprep.

  • Input parameters

    Parameter Description

    file

    Specifies a file to be preprocessed. The extension cannot be ".c".
Examples

The following example preprocesses TEST.ccs with osccprep to create the osccprep_TEST.c file.

$ osccobprep TEST.ccs

The following example preprocesses TEST.ccs with osccprep to create the TEST.c file.

$ osccobprep -V -o TEST.c TEST.ccs

3. Compilation

The following describes COBOL and PL/I application program source code compilation.

  • COBOL

    OSC applications are compiled in the same way that shared objects are created via the COBOL compiler. At this time, the name of a shared object and the PROGRAM-ID value of a COBOL program source must be identical.

  • PL/I

    OSC applications are compiled in the same way that shared objects are created via the PL/I compiler. At this time, the names of a shared object and the PROCEDURE of a PL/I program source must be identical.

  • C

    OSC applications are compiled by creating shared objects using the C complier. There must be a function with the same name as a shared object in a C program source (for a source with a main function, the main function name will be changed to the source file name during preprocessing).

For more information about using the compiler and creating shared objects, refer to the respective guide for the COBOL, PL/I and C compilers.

4. Deployment

After a source file has been preprocessed and compiled to generate an executable binary, the binary must be deployed to each OSC region by using the osctdlinit and osctdlupdate tools (provided with OSC).

Deployment follows the following steps:

  1. Specify the directory to store the program to the VALUE of the TDLDIR key, in the GENERAL section of the osc.{servername} subject, which is intended for configuring the OSC application server. If the mod and run directories under the directory specified to the TDLDIR key do not exist, you must create them yourself. If the TDLDIR key value is not specified, the default directory is ${OPENFRAME_HOME}/osc/region/{Region name}/tdl.

  2. Create the tdl.cfg file in the config directory, under the TDLDIR directory. Use the sample tdl.cfg file provided by the installer.

    The following example creates a tdl.cfg file. Even if a PL/I program is used, LANG is set to COBOL.

    # shared memory version (1|1D|2|2D|3)
VERSION=3

# shared memory key
SHMKEY=0x3AB6

# shared memory and file creation permission
IPCPERM=0750

# number of dynamic loadable modules, rouded up to powers of 2
MAXMODULES=2000

# language environment
LANG=COBOL

# keeping extension
KEEPEXT=asmo

    When using the assembly module (.asmo), specify the file extension by using the KEEPEXT option, as demonstrated in the previous example, and run the osctdlupdate tool.

  3. Run the osctdlinit tool for each region. Then, initialization is performed according to the settings specified in the tdl.cfg configuration file.

  4. Copy the compiled application binaries in the mod directory under the TDLDIR directory.

  5. Use the osctdlupdate tool to distribute the compiled application binaries by specifying the OSC region name and the program name (do not include the file extension). For an assembly module, do not omit the file extension.

    1. The osctdlrm tool can be used to delete information stored in shared memory. To reinitialize the shared memory, use the osctdlinit tool.

    2. For more information about how to use subjects for configurations, refer to OpenFrame Configuration Guide.

5. Registering Programs and Transactions

Program and transaction definition macros must be prepared and registered to the OSC SD table before registering application programs.

The following examples are resource definition macros for the OIVPMAIN program and the OIVP transaction, respectively. The following macro files can be registered to the OSC SD table by using the oscsdgen tool. Additionally, the macros can be registered, modified or deleted through the [OSC] > [Regions] > [System Definitions] menu in OpenFrame Manager.

DEFINE  PROGRAM(OIVPMAIN)
        GROUP(OIVP)
        LANGUAGE(COBOL)

DEFINE  TRANSACTION(OIVP)
        GROUP(OIVP)
        PROGRAM(OIVPMAIN)
        TWASIZE(255)

  1. For more information about program and transaction resource definitions, refer to OpenFrame OSC Resource Definition Guide.

  2. For more information about the [OSC] > [Regions] >[System Definitions] menu, refer to OpenFrame Manager User Guide.