6 Developing Oracle Applications to Run on z/OS

6.2.2.1 Using z/OS Assembler Language

Some complex application designs involve programming in z/OS Assembler Language and using low-level system services provided as Assembler macros or callable services. While you cannot use an Oracle Precompiler or make OCI or OCCI calls directly from Assembler, you can invoke Oracle-accessing C, C++, COBOL, FORTRAN, or PL/I programs from an Assembler program. Doing so requires, foremost, an understanding of LE and the notion of an LE enclave.

An Assembler program that invokes Oracle-accessing programs can be LE-conforming, using LE macros such as CEEENTRY and CEETERM for entry and exit linkage, or it can be a non-LE program. Which you use depends on what kind of Oracle-accessing programs are invoked and how, as discussed in the sections that follow.

6.2.2.2 Dynamic Linkage Techniques

There are a variety of ways in z/OS to cause program code to be read into memory and executed on demand of the initial or main application (the program invoked as a jobstep, TSO command, or shell executable). Some, such as DLLs, COBOL dynamic linkage, and the C functions system() and fetch(), are provided and supported by compilers and LE. Others, such as the Assembler services LOAD/CALL, LINK, and ATTACH (and related services such as ISPF's ISPLINK) operate outside LE. All of these techniques, and especially the latter category, require awareness of both LE requirements and Oracle requirements.

6.2.2.3 Multiple LE Enclaves in an Application

There are a couple of ways that an application that runs as a single z/OS task (TCB) can use multiple LE enclaves. One is for a program in an existing enclave to invoke another main program using a service such as C/C++ system() or Assembler LINK. In this case LE creates what is called a nested enclave for the invoked program. The nesting can go deeper if the invoked program invokes still other main programs the same way.

Another scenario is when a non-LE Assembler program invokes multiple LE main programs in succession using LOAD/CALL or LINK. Each invoked program creates and ultimately deletes its own LE enclave. Since there is no existing enclave at create time, these enclaves are not nested, and only one enclave exists at a time.

Regardless of which scenario applies (or both, since they can be combined), only one LE enclave is active (running program code) at a time. When the enclaves involve Oracle interaction, when the programs are precompiler, OCI, or OCCI applications, the following considerations apply:

• A single Oracle application context, as defined earlier, can be created and used within a single LE enclave only. This means your application cannot be designed to pass resources from one application context (such as cursors or OCI handles) to code that executes in a different LE enclave, including a nested enclave. In practical terms, this prohibits opening a cursor in one COBOL run unit, which equates to an LE enclave, and trying to fetch from that cursor in a different COBOL run unit. It also prohibits passing cursors or other Oracle connection state artifacts from one C/C++ main program to another C/C++ main program.

• If an application uses multiple LE enclaves with API stubs, all of the precompiler or OCI programs making up the application must have been built and bound with the API stub from either Oracle Database 10g or Oracle9i Release 2. Applications built with the Oracle9i API stub must use a version of the stub that contains the fix for Oracle bug 3431417.

• If an application uses multiple LE enclaves with DLL stubs, the main program in each enclave that makes Oracle API calls must be built and bound with a DLL stub shipped with Oracle Database 10g release 2. Any main programs or application DLLs that make Oracle API calls must be bound against the client and OCCI side decks.

• Pro*COBOL applications that use the COBOL DYNAM compile option and, therefore, do not include the API stub, cannot be used in a multiple enclave application.

6.2.2.4 Multitasking Applications

Using Assembler Language and the ATTACH macro and related services, you can develop an Oracle application that uses multiple concurrently dispatchable tasks. Both Oracle and LE impose requirements on such designs. For LE, enclaves normally have task scope: an enclave created in one task cannot be used to execute programs in another task. For Oracle, all connection state data (the application context) also has task scope. You cannot pass connection state data such as cursor or connection handles from one z/OS task to another.

These requirements essentially mean that each z/OS task in a multitasking design must be independent of the other tasks as far as LE and Oracle interactions are concerned. The tasks are otherwise free to communicate and synchronize among themselves. Such designs can be complex and difficult to debug.

6.2.2.5 z/OS Environment and z/Architecture Hardware States

In z/OS there are numerous combinations of software and hardware states in which a program can run. This includes variations of dispatchable unit (task or SRB), APF authorization, supervisor versus problem state, PSW key, and addressing variations including AR and cross-memory modes. Your Oracle-accessing application is constrained to using environments and execution states that are supported by LE. In addition, the following restrictions apply:

• You cannot access Oracle when running as an SRB; only task mode is supported.

• Your program must be in primary ASC mode and not in any cross-memory mode at the time an Oracle interface call is made.

• Your program must not be disabled, hold any z/OS lock, or have an Enabled Unlocked Task (EUT) FRR established at the time of an Oracle interface call.

• All input and output parameters for an Oracle interface call must be accessible in your application's address space using the application's AMODE and PSW key.

• All calls to Oracle from an application must be made in the same AMODE, the same privilege state (problem or supervisor), and the same PSW key.

• If your application uses PROTOCOL=XM to connect to a local Oracle server, z/OS Asynchronous Exits (IRBs) are not dispatched during Oracle server interaction (while running in the Oracle server in cross-memory mode). This means processes like z/OS STIMER/STIMERM timer pops and TSO attention interrupts are deferred until a server call returns control.

6.2.2.6 POSIX Threading

You can use the POSIX threading features of z/OS in an Oracle Pro*C/C++, OCI or OCCI application. However, because z/OS normally dispatches separate threads on separate z/OS tasks, you cannot pass Oracle connection state data (such as connection or cursor handles) from one thread to another. Each thread must establish, use, and close its own Oracle server connections and cursors.

6.2.2.7 OCI Interface to Publish/Subscribe

The OCI interface to Oracle's publish/subscribe features allows an application to register a callback function that is driven when there are queue data or trigger events to process. This feature is supported with Oracle Database for z/OS as long as the client executes in a multi-threaded environment and there is TCP connectivity between the server and the client. This includes local z/OS clients running under z/OS UNIX Systems Services shell environments as well as remote clients on any multi-threaded platform. It excludes native TSO/batch and IMS TM clients at this time

The TCP connectivity requirement does not mean that the client must be connected to the server using Oracle Net PROTOCOL=TCP. The client can be connected using any protocol (including Oracle Net PROTOCOL=XM for a local z/OS UNIX Systems Services client) and in fact the client can disconnect its session from the database after setting up the callback without affecting the callback. A special background process in the server (EMON) opens a TCP connection to the client thread that gets created when OCISubscriptionRegister is called. TCP communication from the server to the client thread ultimately drives the callback functions.

Refer to the OCI Programmer's Guide for further details on the OCI interface to Oracle's publish/subscribe facility.

6.3.1.1 Oracle Precompiler Executables

Oracle Precompilers can be run in various environments. The following table shows the names of the executables for each environment:

6.3.1.2 Oracle Precompiler INCLUDE Files

Several INCLUDE files are provided in the H data set for use by the Oracle Precompilers. You do not have to specify the member name that includes the language suffix in your source program. You may specify the data structure name, for example, SQLCA, in your source program. Oracle Precompilers include the appropriate member name based on the Oracle Precompiler language, as listed in the following table:

For more information about data structures, refer to your Oracle Precompiler documentation.

6.3.1.3 Oracle Precompiler Options

Because there are many possible options for the Oracle Precompilers, you might find it impossible to fit all the options you need in the 100 bytes z/OS allows for parameters initially passed to user programs (for example, from JCL). You can use the following methods to pass more than 100 bytes of precompiler options to an Oracle Precompiler interface:

• Use the Oracle Precompiler EXEC ORACLE OPTION statement in your source program to specify some of the parameters. This is a good way to specify options that do not change for each compile. Refer to your Oracle Precompiler documentation for information on the EXEC ORACLE OPTION statement.

• Use a parameter file to direct the Oracle Precompiler to retrieve parameters from a z/OS file in addition to the z/OS parameter field. Refer to Chapter 2 for more information about the parameter file feature. A combination of option overrides and parameter file also can be used. For example:

  PARM='++//DD:ddname option1 option2…'
  
  

• When using a question mark to determine the current value for one or more options, surround the question mark with full quotes or escape the question mark with a backslash, as shown in the following examples:

  // EXEC PGM=PROC,PARM='"?"'
  // EXEC PGM=PROC,PARM='\?'
  
  

When specifying Oracle Precompiler options on the command line, separate each option with one or more blanks. Do not use a comma as a separator. To specify a fully-qualified data set name in an Oracle Precompiler option, use the appropriate LE syntax.

When running in a batch or TSO environment, some Oracle Precompiler options require the following special considerations. Refer to Chapter 2 for rules on how to specify z/OS data set names to the Oracle database server.

INAME=//DD:SYSIN

ONAME=//DD:SYSPUNCH

LNAME=//DD:LIST

6.3.1.4 Configuration Files

Oracle Precompilers on z/OS support the concept of system and user configuration files. In batch and TSO environments, the system configuration file is read from the PROCFG DD statement, if it exists. To avoid a warning message, the PROCFG DD statement should be DUMMY if no changes to the default options are desired.

The user configuration file can be used to make overrides to the system configuration file for specific options. The file must be specified in the parameters passed to the precompiler using the CONFIG= option. The CONFIG= option is not allowed inside a configuration file; doing so will produce an error message, although the precompile continues. If a data set is used to pass precompiler options to an Oracle Precompiler, the data set must not have sequence numbers. If sequence numbers are found, then the Precompiler stops processing.

When using configuration files in the POSIX environment, follow the rules outlined in the product documentation.

In all environments, each option in a configuration file must be on a separate line and must begin in column 1.

6.3.1.5 Return Codes

Oracle Precompilers set a return code of 0 upon successful precompilation of source code. A return code of 4 is set if the precompiler issues a warning message.

A return code of 8 is set if the precompiler detects a potentially irrecoverable error condition. In this case, an error message is written to the file specified in the LNAME parameter passed to the precompiler.

6.3.1.6 Language-Specific Coding Considerations

The following sections discuss certain considerations that impact Oracle Precompiler programs written in a particular language, regardless of the target environment running the program:

6.3.1.7 Special Considerations for Running Precompilers in Batch and TSO Environments

The Oracle Precompilers use temporary files during their processing. In the batch and TSO environments, users must provide DD statements SYSUT1, SYSUT2, SYSUT3, SYSUT4 (Pro*FORTRAN only) and SYSUT5 (Pro*FORTRAN only) that point to temporary files. These are normally specified as UNIT=VIO DD statements.

If the ORECLEN precompiler parameter is larger than 132, then the DCB attributes must be specified in these DD statements to set the LRECL equal to the ORECLEN value. For example, the following statement sets the LRECL to 200:

//SYSUT1 DD UNIT=VIO,DCB=(LRECL=200)

6.3.1.8 Sample JCL for Running the Pro*C/C++ Precompiler in Batch Environments

The following sample JCL illustrates the precompile step necessary to build a Pro*C precompiler application program:

//PRECOMPL EXEC PGM=PROC,
// PARM='++//DD:SYSPARM'
//STEPLIB DD DSN=ORACLE.V10G.CMDLOAD,DISP=SHR
//ORA$LIB DD DSN=ORACLE.V10G.MESG,DISP=SHR
//SYSLIB DD DSN=ORACLE.V10G.H,DISP=SHR
//       DD DSN=SYS1.SCEEH.H,DISP=SHR
//       DD DSN=SYS1.SCEEH.SYS.H,DISP=SHR
//LIST   DD SYSOUT=*
//PROCFG DD DUMMY
//SYSIN DD DISP=SHR,DSN=JSMITH.CPGM.PC
//SYSPUNCH DD DSN=&&PCCOUT,DISP=(,PASS,DELETE),
//            UNIT=VIO
//SYSPARM DD *
INAME=//DD:SYSIN
ONAME=//DD:SYSPUNCH
LNAME=//DD:LIST
/*
//SYSUT1 DD UNIT=VIO
//SYSUT2 DD UNIT=VIO
//SYSUT3 DD UNIT=VIO

6.3.1.9 Sample JCL for Running the Pro*COBOL Precompiler in Batch Environments

The following sample JCL illustrates the precompile step necessary to build a Pro*COBOL precompiler application program:

//PRECOMPL EXEC PGM=PROCOB,
// PARM='++//DD:SYSPARM'
//STEPLIB DD DSN=ORACLE.V10G.CMDLOAD,DISP=SHR
//ORA$LIB DD DSN=ORACLE.V10G.MESG,DISP=SHR
//SYSLIB DD DSN=ORACLE.V10G.H,DISP=SHR
//       DD DSN=SYS1.SCEEH.H,DISP=SHR
//       DD DSN=SYS1.SCEEH.SYS.H,DISP=SHR
//LIST   DD SYSOUT=*
//PROCFG DD DUMMY
//SYSIN DD DISP=SHR,DSN=JSMITH.COBPGM.PCO 
//SYSPUNCH DD DSN=&&PCCOUT,DISP=(,PASS,DELETE),
//            UNIT=VIO
//SYSPARM DD *
INAME=//DD:SYSIN
ONAME=//DD:SYSPUNCH
LNAME=//DD:LIST
/*
//SYSUT1 DD UNIT=VIO
//SYSUT2 DD UNIT=VIO
//SYSUT3 DD UNIT=VIO

6.3.1.10 Sample JCL for Running the Pro*FORTRAN Precompiler in Batch Environments

The following sample JCL illustrates the precompile step necessary to build a Pro*FORTRAN precompiler application program:

//PRECOMPL EXEC PGM=PROFOR,
// PARM='++//DD:SYSPARM'
//STEPLIB DD DSN=ORACLE.V10G.CMDLOAD,DISP=SHR
//ORA$LIB DD DSN=ORACLE.V10G.MESG,DISP=SHR
//SYSLIB  DD DSN=ORACLE.V10G.H,DISP=SHR
//LIST    DD SYSOUT=*
//PROCFG  DD DUMMY
//SYSIN DD DISP=SHR,DSN=JSMITH.FORPGM.FOR
//SYSPUNCH DD DSN=&&PCCOUT,DISP=(,PASS,DELETE),
//            UNIT=VIO
//SYSPARM DD *
INAME=//DD:SYSIN
ONAME=//DD:SYSPUNCH
LNAME=//DD:LIST
/*
//SYSUT1 DD UNIT=VIO
//SYSUT2 DD UNIT=VIO
//SYSUT3 DD UNIT=VIO
//SYSUT4 DD UNIT=VIO
//SYSUT5 DD UNIT=VIO
//PRECOMPL EXEC PGM=PROCOB,

6.3.1.11 Sample JCL for Running the Pro*PL/I Precompiler in Batch Environments

The following sample JCL illustrates the precompile step necessary to build a Pro*PL/I precompiler application program:

//PRECOMPL EXEC PGM=PROPLI,
// PARM='++//DD:SYSPARM'
//STEPLIB DD DSN=ORACLE.V10G.CMDLOAD,DISP=SHR
//ORA$LIB DD DSN=ORACLE.V10G.MESG,DISP=SHR
//SYSLIB DD DSN=ORACLE.V10G.H,DISP=SHR
//       DD DSN=SYS1.SCEEH.H,DISP=SHR
//       DD DSN=SYS1.SCEEH.SYS.H,DISP=SHR
//LIST   DD SYSOUT=*
//PROCFG DD DUMMY
//SYSIN DD DISP=SHR,DSN=JSMITH.PLIPGM.PPL
//SYSPUNCH DD DSN=&&PCCOUT,DISP=(,PASS,DELETE),
//            UNIT=VIO
//SYSPARM DD *
INAME=//DD:SYSIN
ONAME=//DD:SYSPUNCH
LNAME=//DD:LIST
/*
//SYSUT1 DD UNIT=VIO
//SYSUT2 DD UNIT=VIO
//SYSUT3 DD UNIT=VIO

6.3.1.12 Sample Commands for Running Oracle Precompilers in a Shell

Oracle Precompilers running in a shell must know the include pathname to find all the include files. Therefore, the command line must have each nonstandard include pathname specified.

The following are sample commands for running Oracle Precompilers in a shell:

$ procob iname=mycobpgm.pco include=/home/jones/copybooks oname=xyz.cbl

$ proc iname=mycpgm.pc include=/home/jones/include

6.3.2.1 C/C++ Compiler Options

The C/C++ compiler options are listed as follows:

• DLL - N, PA, PD, PZ

  Required for C if using OCI callbacks or a DLL stub. Required for C++

• LANGLVL(EXTENDED) - N, PA, PD, Z

  Required if using OCI-Lob related functions or a DLL stub

• ENUMSIZE(INT) - C, I, N, PA, PD, Z

  Required for OCI/OCCI programs

• FLOAT(HEX) - C, I, N, PA, PD, Z

  Required (CHECK XPLINK!)

• LONGNAME - N, P

  Default for C. Required for DLL stub applications. For an OCI API stub application, LONGNAME allows prelinking and linking with ORASTBS or linking with ORASTBL. Refer to the section "Linking Programs" or more information.

• NOLONGNAME - N, P

  For an OCI API stub application that uses OCI V7 names or the DEFINE=ORA_SNAME precompiler option, NOLONGNAME allows linking with ORASTBS. Refer to the "Building a Traditional Load Module with the Alternate API Stub" section for more information.

• TARGET(LE,zOSV1R4) - N, PA, PD, Z

  zOSV1R4 or later is required. Default on z/OS V1.4 or later

• NOXPLINK - C, I, N, PA, PD

  Required C, I, N, PA. Optional for PD.

• XPLINK - PD, Z

  Optional for PD. Required for Z. Implies DLL, LONGNAME.

• SEARCH($ORACLE_HOME/rdbms/public) - PD, Z

  Required for OCCI

6.3.2.2 COBOL Compiler Options

The COBOL compiler options are listed as follows:

• APOST/QUOTE - C, I, N, P

  The PCC option LITDELIM must match the value specified. For CICS TS, this value must also be specified as a CICS translator option.

• NODYNAM/DYNAM - N, P

  NODYNAM is recommended. To use the DYNAM option, refer to the sections "Compiling Programs", "Linking Programs", and "Oracle Interface Initialization, Processing, and Error Handling" for details on using COBOL DYNAM support.

• PGMNAME - N, P

  LONGMIXED - requires linkage with ORASTBL.

  LONGUPPER - requires linkage with ORASTBL.

  Refer to the section "Linking Programs" or more information.

• SQL - C, I, N, P

  Not applicable for Oracle applications

6.3.2.3 PL/I Compiler Options

The PL/I compiler options are listed as follows:

• NOINTERRUPT - N,P

  Required

• NOT,OR -

  Refer to the PRO*PL/I Supplement to the Oracle Precompilers Guide for restrictions on using PL/I logical operators in SQL statements

6.3.3.1 Sample Commands for Compiling Programs in a Shell

The following are sample commands for compiling programs in a shell:

export STEPLIB=SYS1.SIGYCOMP
export COBOPT='QUOTE,OPTIMIZE,SOURCE,LIST'
cob2 -c pgm_name.cbl -o pgm_name.o -v \
-I. \
-I$ORACLE_HOME/precomp/public \
2>pgm_name.err

c89 -c \
-I. \
-I$ORACLE_HOME/rdbms/public \
-I$ORACLE_HOME/precomp/public \
-o pgm_name.o pgm_name.c \
2>pgm_name.err 

6.3.3.2 Compiling OCCI programs to Run in Batch and TSO Environments

The following sample JCL, based on standard procedure CBCXCB, illustrates the compilation step necessary for an OCCI C++ program in batch and TSO environments.

//COMPILE EXEC PGM=CCNDRVR,REGION=96M,
//        PARM=('/CXX XPLINK GOFF OPTFILE')
//SYSLIN  DD DISP=(,PASS),UNIT=VIO,
//        DCB=(RECFM=FB,LRECL=80,BLKSIZE=3120)
//SYSIN   DD                    - Refer to Note 1 -
//SYSPRINT DD SYSOUT=*
//SYSOUT  DD SYSOUT=*
//SYSCPRT DD SYSOUT=*
//SYSOPTF DD *
  LANGLVL(EXTENDED) ENUMSIZE(INT)
  SEARCH($ORACLE_HOME/rdbms/public) - Note 2 -
*/

Usage Notes:

1. Point to the program to be compiled. This can be in a dataset (DD DSN) or an HFS file (DD PATH).

2. Replace $ORACLE_HOME with the Oracle home directory.

6.3.4.1 Linking Pro*C/C++, OCI, COBOL, and PL/I Programs to Run in Batch and TSO Environments

When linking a C, C++, COBOL, or PL/I program to run in batch or TSO, add the following linkage editor control statement to the SYSLIN DD statement:

INCLUDE SYSLIB(ORASTBL)

If there are unresolved external references for symbols whose names begin with SQL, then ensure ORASTBL is included in the linkedit. This API stub resolves any calls in the generated code. If ORASTBL is correctly included, then the problem is probably caused by a missing entry point to the API stub routine. You can contact Oracle Support Services for additional assistance.

The following sample JCL illustrates the linking step necessary to run C, C++, COBOL, and PL/I programs in batch and TSO environments:

//LKED EXEC PGM=IEWL,
// PARM='XREF,LET,LIST,DYNAM=DLL'
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DSN=ORACLE.V10G.SQLLIB,DISP=SHR
//       DD DSN=SYS1.SCEELKED,DISP=SHR
//       DD                                 *- Refer to Note 1 -*
//SYSLMOD DD                                *- Refer to Note 2 -*
//TEXT    DD                                *- Refer to Note 3 -*
//SYSUT1  DD UNIT=VIO
//SYSLIN  DD *
INCLUDE TEXT                                *- Refer to Note 3 -*
INCLUDE SYSLIB(ORASTBL)                        *- Refer to Note 4 -*                                            *- Refer to Note 5 -*
/*

Usage Notes:

1. Include additional libraries required by your program and any runtime libraries required by the native language.

2. This DD statement describes the library in which your linkedited Oracle load module is placed.

3. This DD statement points to the object output from your Oracle Precompiler program's native language compiler.

4. The specific contents of the SYSLIN DD statement depend on the target environment. Refer to "Linking Programs" for more information.

5. Include any additional linkage editor statements you might require.

6.3.4.2 Linking COBOL Programs Using DYNAM

Each target environment has a unique stub, and different linking considerations apply to each of the target environments. In all cases, unless you are using the COBOL DYNAM compiler option, the API stub must be linked statically linked with your program.

If you are using the DYNAM option when building a Pro*Cobol application, you need to make the following changes for linking your program:

• Remove any DYNAM(DLL) parameter

• Add an OBJLIB DD statement allocating oracle_hlq.OBJLIB

• For link/binder control, replace the following control statement:

  INCLUDE SQLLIB(ORASTBL)
  

Instead, use the following statement:

INCLUDE OBJLIB(ORADMYC)

If the application developer does not change or incorrectly changes the INCLUDE statement, it will probably go undetected when the application is built. The mistake will result in an all-too-common 0C4 abend. Tracing it back to the build error, the reason will not be apparent without a significant amount of debugging. To help with this problem, extra checking was added to the runtime interface to detect the condition before the 0C4 abend is likely to occur.

Detection that the LE initialization is insufficient for C, results in a standard API failure message, such as:

MIC011E Oracle API processing error, reason code 014

This is followed by a U2010 user abend with reason code 14. Reason code 14 uniquely identifies this as the build-time mistake: ORADMYC was not included.

6.3.4.3 Linking FORTRAN programs to Run in Batch and TSO Environments

When linking a FORTRAN program to run in batch or TSO, add the following linkage editor control statement to the SYSLIN DD statement:

INCLUDE SYSLIB(ORASTBF)

IIf there are unresolved external references for symbols whose names begin with SQL, then ensure ORASTBF is included in the linkedit. These API stubs resolve any calls in the generated code. If ORASTBF is correctly included, then the problem is probably caused by a missing entry point to the API stub routine. You can contact Oracle Support Services for additional assistance.

The following sample JCL illustrates the linking step necessary to run FORTRAN programs in batch and TSO environments. Note that SYSLMOD may be either a PDS (for a traditional load module) or PDSE (for a PM2 program object).

//LKED EXEC PGM=HEWL,
// PARM='LET,LIST,MAP,XREF'
//SYSPRINT DD SYSOUT=*
//SYSLIB   DD DSN=SYS1.SCEELKED,DISP=SHR
//         DD                   - Refer to Note 1 -
//OBJLIB   DD DSN=ORACLE.V10G.OBJLIB,DISP=SHR
//SYSLMOD  DD                   - Refer to Note 2 -
//TEXT     DD                   - Refer to Note 3 -
//SYSUT1   DD UNIT=VIO
//SYSLIN   DD *
 INCLUDE TEXT                   - Refer to Note 3 -
 INCLUDE OBJLIB(ORASTBF)        - Refer to Note 4 -
                                - Refer to Note 5 -
/*

Usage Notes:

1. Include additional libraries required by your program and any runtime libraries required by the native language.

2. This DD statement describes the library in which your linkedited Oracle load module is placed.

3. This DD statement points to the object output from your Oracle Precompiler program's native language compiler.

4. The specific contents of the SYSLIN DD statement depend on the target environment. Refer to "Linking Programs" for more information.

5. Include any additional linkage editor statements you might require.

6.3.4.4 Linking API Stub Programs to Run in a Shell

When linking an API Stub program to run in a POSIX environment, specify the following object file to be linked with your program:

$ORACLE_HOME/lib/orastbl.o

If there are unresolved external references for symbols whose names begin with SQL, then ensure orastbl.o is included in the linkedit. This API stub resolves any calls in the generated code. If orastbl.o is correctly included, then the problem is probably caused by a missing entry point to the API stub routine. You can contact Oracle Support Services for additional assistance.

6.3.4.5 Sample Commands for Compiling and Linking API Stub Programs in a Shell

The following are sample commands for compiling and linking API stub programs in a shell:

export STEPLIB=SYS1.SIGYCOMP
export COBOPT='QUOTE,DLL,OPTIMIZE,SOURCE,LIST'
cob2 pgm_name.cbl -v \
$ORACLE_HOME/lib/orastbl.o \
-I. \
-I$ORACLE_HOME/rdbms/public \
-I$ORACLE_HOME/precomp/public \
-o pgm_name 2>pgm_name.err

c89 -I. \
-I$ORACLE_HOME/rdbms/public \
-I$ORACLE_HOME/precomp/public \
-o pgm_name $ORACLE_HOME/lib/orastbl.o \
pgm_name.c \
2>pgm_name.err 

6.3.4.6 Linking DLL Stub Programs in a Shell

When linking a DLL stub program to run in a POSIX environment, specify the object files and side decks listed in Table 6-4 for the compiler and environment.

6.3.4.7 Sample Commands for Compiling and Linking DLL Stub Programs in a Shell

The following are sample commands for compiling and linking DLL stub programs in a shell.

c89 -I. \
-I$ORACLE_HOME/rdbms/public \
-o pgm_name $ORACLE_HOME/lib/orastbp.o \
$ORACLE_HOME/lib/LIBCLNTS.x \
-W "0,dll,langlvl(EXTENDED),ENUMSIZE(INT)" \
pgm_name.c \
2>pgm_name.err

c++ -I. \
-I$ORACLE_HOME/rdbms/public \
-o pgm_name $ORACLE_HOME/lib/orastbp.o \
$ORACLE_HOME/lib/LIBCLNTS.x \
$ORACLE_HOME/lib/LIBOCCI.x \
-+ -W "0,xplink,langlvl(EXTENDED),ENUMSIZE(INT)" \
-W "l,xplink" \
pgm_name.cpp \
2>pgm_name.err

6.3.4.8 Binding OCCI programs to Run in Batch and TSO Environments

The following sample JCL, based on standard procedure CBCXCB, illustrates the bind step necessary for an OCCI C++ program in batch and TSO environments.

//BIND    EXEC PGM=IEWL,REGION=20M,COND=(8,LE,COMPILE),
// PARM='NOMAP,LIST=NOIMP,COMPAT=CURR,OPTIONS=SYSOPTB'
//SYSPRINT DD SYSOUT=*
//SYSLIB  DD DSN=CEE.SCEEBND2,DISP=SHR          - Note 1 -
//SYSLIN  DD DSN=*.COMPILE.SYSLIN,DISP=(OLD,DELETE)
//        DD DSN=CEE.SCEELIB(CELHSCPP),DISP=SHR - Note 1 -
//        DD DSN=CEE.SCEELIB(CELHS003),DISP=SHR - Note 1 -
//        DD DSN=CEE.SCEELIB(CELHS001),DISP=SHR - Note 1 -
//        DD DSN=CEE.SCEELIB(C128),DISP=SHR     - Note 1 -
//        DD DSN=CBC.SCLBSID(IOC),DISP=SHR      - Note 2 -
//        DD DSN=CBC.SCLBSID(IOSTREAM),DISP=SHR - Note 2 -
//        DD DSN=CBC.SCLBSID(COMPLEX),DISP=SHR  - Note 2 -
//        DD DSN=CBC.SCLBSID(COLL),DISP=SHR     - Note 2 -
//        DD DDNAME=SYSIN
//SYSLMOD DD                       - Refer to Note 3 -
//SYSOPTB DD *
  AMODE=31,RENT,DYNAM=DLL,CASE=MIXED
//SYSIN   DD *
 INCLUDE '$ORACLE_HOME/lib/orastbz.o'  - Refer to Note 4 -
 INCLUDE '$ORACLE_HOME/lib/LIBOCCI.x'  - Refer to Note 4 -
 INCLUDE '$ORACLE_HOME/lib/LIBCLNTS.x' - Refer to Note 4 -
*/

Usage Notes:

1. Use your installation's run-time library dataset prefix.

2. Use your installation's standard I/O library prefix.

3. Point to the PDSE member where the program will be stored.

4. Replace $ORACLE_HOME with the Oracle home directory.

6.3.4.9 Building an Oracle XDK API Using Program in a Shell

The Oracle XDK API is available for use by z/OS C and C++ applications that run under a POSIX shell. Any main program or application DLL that uses the Oracle XDK API must be compiled with DLL and NOXPLINK, which is the default, statically linked against the Oracle XDK API and dynamically linked against LIBCLNTS. If any piece of the application uses XPLINK, the XPLINK(ON) LE runtime option must be used. For more information, refer to Section 6.2.2.2.2, "Using the XPLINK(ON) LE Runtime Option". If the application accesses an Oracle database, it must follow the rules for main program and application DLL links specified in Table 6-4. It must also use the OCI API, which is compatible with NOXPLINK, or isolate OCCI API use from Oracle XDK API. For more information, refer to Section 6.2.2.2.1, "Using DLLs".

The following are sample commands for compiling and linking Oracle XDK API-using programs in a POSIX shell.

C:
c89 -I. \-I$ORACLE_HOME/rdbms/public \
-I$ORACLE_HOME/xdk/include \
-L$ORACLE_HOME/lib \
-o pgm_name -lxml10 \
$ORACLE_HOME/lib/LIBCLNTS.x \
-W "0,dll,langlvl(EXTENDED),ENUMSIZE(INT)" \
pgm_name.c \
2>pgm_name.err
C++:
c++ -I. \
-I$ORACLE_HOME/rdbms/public \
-I$ORACLE_HOME/xdk/include \
-L$ORACLE_HOME/lib \
-o pgm_name -lxml10 \
$ORACLE_HOME/lib/LIBCLNTS.x \
-+ -W "0,dll,langlvl(EXTENDED),ENUMSIZE(INT)" \
pgm_name.cpp \
2>pgm_name.err

Usage Notes:

1. Use your installation's run-time library dataset prefix.

2. Use your installation's standard I/O library prefix.

3. Point to the PDSE member where the program will be stored.

4. Replace $ORACLE_HOME with the Oracle home directory.

6.3.5.1 Sample Batch JCL to Build an Oracle Precompiler Program

The SRCLIB data set created at Oracle Database install time contains sample JCL to demonstrate the precompile, compile, link, and execute phases of a precompiler program in a single batch job. The SRCLIB members that contain the sample JCL are listed in the following table:

6.3.5.2 Using Make to Build a Precompiler Program

Oracle provides sample make files for each supported language to precompile, compile, and link precompiler programs. They can be found in the following location, where precompiler is either proc or procob:

$ORACLE_HOME/precomp/demo/precompiler 

If your program depends on non-Oracle libraries, you may have to alter the make files to include them:

In order to use the make files, enter a command similar to the following in a shell:

$ make -f xxxxx.mk your_program_src_file

6.3.5.3 Pro*COBOL Sample Programs

Sample Pro*COBOL programs are located in the $ORACLE_HOME/precomp/demo/procob directory. Some of these programs require that you run the SQL scripts in the $ORACLE_HOME/precomp/demo/sql directory.

To build one of the sample Pro*COBOL programs, use the cd command to set the working directory to $ORACLE_HOME/precomp/demo/procob and issue the following make command:

$ make -f demo_procob.mk sample1

To build all of the sample Pro*COBOL programs, use the cd command to set the working directory to $ORACLE_HOME/precomp/demo/procob and issue the following make command:

$ make -f demo_procob.mk samples

6.3.5.4 Pro*FORTRAN Sample Programs

FORTRAN does not run in a z/OS shell environment. Therefore, the Pro*FORTRAN sample programs that work on z/OS have been moved to SRCLIB. The sample programs include FORSMP1-FORSMP4 and FORSMP6-FORSMP11. These programs can be compiled using the PFORCLGO sample procedure, which contains notes and input for those sample programs that require it.

6.3.5.5 Pro*C/C++ Sample Programs

Many of these programs require that you run the SQL scripts in the $ORACLE_HOME/precomp/demo/sql directory.

To build one of the sample PRO*C programs, use the cd command to set the working directory to $ORACLE_HOME/precomp/demo/proc and issue the following make command:

$ make -f demo_proc.mk sample1

To build all of the sample PRO*C programs, use the cd command to set the working directory to $ORACLE_HOME/precomp/demo/proc and issue the following make command:

$ make -f demo_proc.mk samples

6.3.5.6 Batch JCL to Build OCI Programs

There is sample JCL in the SRCLIB data set created at Oracle Database install time that contains sample JCL to demonstrate the precompile, compile, link, and execute phases of OCI programs in a single batch job. The SRCLIB member that contains the sample JCL is CDEMCLGO.

6.3.5.7 Batch JCL to Build OCCI Programs

There is sample JCL in the SRCLIB dataset created at Oracle Database install time that contains sample JCL to demonstrate the compile, link and execute phases of an OCCI program in a single batch job. The SRCLIB member that contains the sample JCL is CPDMCXBG.

6.3.5.8 Using Make to Build OCI and OCCI Programs

Oracle provides a sample make file to compile and link OCI and OCCI programs. It is located in the $ORACLE_HOME/rdbms/demo/demo_rdbms.mk directory.

If your program depends on non-Oracle libraries, you may have to alter this make file to include them.

In order to use this make file, enter a command similar to the following in a POSIX shell environment:

$ make -f demo_rdbms.mk build EXE=your_program_src_file SRCS="your_program_name.o …"

6.3.5.9 Sample OCI and OCCI Programs

Sample OCI and OCCI programs are located in the $ORACLE_HOME/rdbms/demo directory. Some of these programs require that you run SQL scripts in the $ORACLE_HOME/rdbms/demo directory.

To build one of the sample OCI programs, cd to the $ORACLE_HOME/rdbms/demo directory and run the following make command:

$ make -f demo_rdbms.mk build EXE=oci02 SRCS=oci02.o

To build all of the sample OCI programs, change to the $ORACLE_HOME/rdbms/demo directory and issue the following make command:

$ make -f demo_rdbms.mk samples

To build one of the sample OCCI programs, change to the $ORACLE_HOME/rdbms/demo directory and run the following make command:

$ make -f demo_rdbms.mk buildocci EXE=occiblob SRCS=occiblob.cpp

To build all of the sample OCCI programs, change to the $ORACLE_HOME/rdbms/demo directory and run the following make command:

$ make -f demo_rdbms.mk occidemos

6.6.1.1 CICS TS Versions Supported

The following CICS TS versions are supported by Oracle Database for z/OS:

6.6.1.2 CONNECT Statements

Explicit CONNECT statements are supported but result in increased overhead and are not recommended. Authentication can be determined with several methods as described in the Oracle Database System Administration Guide for IBM z/OS. If used, note the following:

• The CONNECT…AT clause is not supported

• When using CICS SYNCPOINT, if there is more than one CONNECT statement within the same CICS TS transaction, a CICS syncpoint is required prior to a second, or subsequent CONNECT statement. This applies whether multiple connect statements are within one program or the program containing the CONNECT statement is given control by a CICS LINK, CICS XCTL, 'CALL', or other method within the same CICS TS transaction.

• Using an explicit CONNECT statement with "/" as the userid is redundant and not supported. If an explicit CONNECT statement is not used, then the thread table authorization definitions are used for the transaction. This is equivalent to using CONNECT with "/" as the userid, but it does not incur the overhead of an extra call to Access Manager for CICS TS.

6.6.1.3 Synchronization of Oracle and CICS TS Updates

CICS TS programs can synchronize Oracle database updates with updates to other data stores in the same CICS TS unit of work. Oracle Access Manager participates in CICS SYNCPOINT processing when COMMIT(CICS) is specified as the commit/recovery mechanism during the configuration process. If this option is used, CICS SYNCPOINT/ROLLBACK triggers commit/rollback and any Oracle SQL COMMIT/ROLLBACK statements will result in an 'ORAP' CICS TS transaction abend.

If COMMIT(ORACLE) is specified as the commit/recovery mechanism, then Oracle SQL COMMIT/ROLLBACK statements trigger commit/rollback, and these updates are not coordinated with updates to other CICS TS data stores.

The RELEASE option of the COMMIT WORK and ROLLBACK statements is not supported and should not be used in a CICS TS program.

6.6.1.4 Cursor Considerations

The following considerations are related to cursors:

• The precompiler options RELEASE_CURSOR=YES and HOLD_CURSOR=NO are required for CICS TS programs.

• Each cursor that is opened explicitly must have an associated CLOSE statement before a CICS LINK, CICS XCTL, 'CALL' or other method of transferring control to another program, or CICS RETURN.

6.6.1.5 Accessing Multiple Oracle Databases

Each CICS TS program that accesses an Oracle database can communicate with one Oracle Access Manager for CICS TS instance which is determined by the ORACSTUB linked with the program. Each Oracle Access Manager for CICS TS communicates with one Oracle database server. Access to more than one Oracle database server from a single CICS TS region can be accomplished using the following:

• Oracle database links, which allow all updates to an accessed database to be part of a single program.

• Multiple Oracle Access Managers, where access logic for each database is contained in a separate CICS TS program. An Oracle Access Manager for CICS TS is configured for each distinct server and an associated ORACSTUB is built for each instance of Oracle Access Manager for CICS TS. The appropriate ORACSTUB is then linked with the program.

6.6.1.6 Accessing Oracle Database 10g and DB2 Databases in a Single Transaction

When accessing Oracle and DB2 data in a single transaction, the DB2 and Oracle access logic must be separated into distinct source programs that are precompiled and compiled separately. They are then linked to act as a single transaction program.

6.6.1.7 Additional SQL Statement Restrictions

Programs used with Access Manager for CICS TS can only use Oracle data manipulation (DML) SQL statements.

6.7.1.1 IMS TM Versions Supported

The following IMS TM versions are supported by Oracle Database for z/OS:

6.7.1.2 CONNECT Not Supported

A typical Oracle Database 10g application uses the CONNECT statement to specify which server is to be accessed and to send the server an Oracle user id and password for authentication. With Oracle Access Manager for IMS TM, this information is configured outside of the program:

• The application program does not specify an Oracle server but accesses a specified instance of Access Manager for IMS TM which is configured to communicate with a specific Oracle server. A language interface token(LIT), built as part of the configuration process, is linked with the application program to designate which instance of Oracle Access Manager for IMS TM will be accessed by the application program.

• The Oracle userid and authentication to be used for IMS TM transactions are related to the IMS PSB name and are defined in the Resource Translation Table (RTT) as part of the configuration process.

6.7.1.3 Synchronization of Oracle and IMS TM Updates

A typical Oracle Database 10g application might use COMMIT or ROLLBACK statements to control whether database updates are committed or removed. With Oracle Access Manager for IMS TM, these SQL statements are not available. Instead, programs must use native IMS functions (such as GU, SYNC, ROLL, or ROLB) to synchronize both Oracle and non-Oracle updates.

6.7.1.4 Cursor Considerations

The Oracle Precompiler MODE option lets you specify one of several alternatives to normal Oracle SQL processing behavior. This allows applications to adhere more closely to ANSI/ISO rules. These options work under Oracle Access Manager for IMS TM. For example, if MODE is set to ANSI, then the cursors are closed with each transaction.

6.7.1.5 Accessing Multiple Oracle Databases

Each program targeted to IMS TM can normally only communicate with one Oracle Access Manager for IMS TM and only one server because it can only be linked with one LIT. Access to more than one Oracle Database 10g database server from a single IMS TM region can be accomplished as follows:

• You can use Oracle database links. With this method, all updates to any of the accessed databases can be part of a single program.

• You can use multiple Oracle Access Managers. To accomplish this, you first design your application so that the access logic for each database is contained in a separate IMS TM program. Then you configure an Oracle Access Manager and a corresponding LIT for each distinct server to be accessed. Finally, you link each of the IMS TM programs with the appropriate LIT.

6.7.1.6 Additional SQL Statement Restrictions

Use only Oracle DML SQL statements in programs used with Oracle Access Manager for IMS TM.

6.7.1.7 Accessing Oracle Database 10g and DB2 Databases in a Single Transaction

When accessing Oracle and DB2 data in a single transaction, the DB2 and Oracle access logic must be separated into distinct source programs that are precompiled and compiled separately. They are then linked to act as a single transaction program.

6.7.1.8 Processing of Oracle Database 10g Errors by Your IMS TM Program

Oracle errors that are considered application-oriented are always returned to the transaction program to be handled by the application logic. These include message ORA-0001, all errors in the range of messages ORA-1400 to ORA-1489, and user-defined error messages in the range of ORA-20xxx. It is the responsibility of the application developer to include suitable error handling logic for these types of errors.

All other errors are considered system-oriented. These include errors associated with loss of the connection to the target Oracle9i database server and simpler errors such as ORA-0942. How Oracle Access Manager for IMS TM handles these errors is determined by an IMS option called the region error option (REO).

The REO can specify that system errors are to be passed to the transaction for handling that is identical to application-oriented errors. Alternatively, the REO can specify that system errors abend and requeue, or abend and discard the transaction.

Which REO to use is decided by the application developer and the IMS administrator. The REO is not specified by or in the application program. It is an Oracle Access Manager for IMS TM configuration parameter.