| Oracle® Database User's Guide 10g Release 2 (10.2) for IBM z/OS (OS/390) Part Number B25396-01 |
|
|
View PDF |
| Oracle® Database User's Guide 10g Release 2 (10.2) for IBM z/OS (OS/390) Part Number B25396-01 |
|
|
View PDF |
This chapter provides z/OS-specific information on design and runtime considerations for applications that will run in batch, TSO, or a shell. It also covers how to build an application: running Oracle Precompilers and OTT (Oracle Type Translator), compiling, and linking or binding a program. This includes both traditional (TSO/batch) mechanisms as well as a shell, including make. Most of the precompiler application build information in this chapter also pertains to applications that will run in CICS TS or IMS TM. Application design and runtime considerations and a few specific build considerations for CICS TS and IMS TM are covered at the end of this chapter.
Before reading this chapter, you should be familiar with Chapter 2, "Oracle Software Interaction with z/OS and Language Environment". Regardless of the language of your application, it will be using the Oracle program interface code, and is subject to features and mechanisms described there. In addition, you should review Chapter 3, "Oracle Net and Server Connections on z/OS", which describes the mechanisms involved in connecting to an Oracle database server both locally and over a real network.
This chapter contains the following sections:
Three facilities are provided for developing compiled high level language programs that run on z/OS and access an Oracle database: Oracle Precompilers, OCI, and OCCI.
Oracle Precompilers-Pro*C/C++, Pro*FORTRAN, Pro*COBOL, and Pro*PL/I-translate special EXEC SQL statements imbedded in a source program into language-specific declarations and executable statements that carry out the requested operation in a target Oracle database server. The output of the precompiler is compiled with a supported z/OS language compiler and then linked or bound as a z/OS program object, conventional load module, or executable file in an HFS. Precompiler applications can run in batch, TSO, or a shell, or under control of CICS TS or IMS TM.
With OCI and OCCI, direct calls to defined Oracle API functions are coded in a C (OCI only) or C++ language program. The program is compiled with a supported z/OS C/C++ compiler and then linked or bound as a z/OS program object, conventional load module (OCI only) or executable file in an HFS. While more complex to use, OCI and OCCI provide access to virtually all Oracle features with fine-grained control over server operations. OCI and OCCI applications on z/OS can run in batch, TSO, or a shell. They are not supported in CICS TS or IMS TM environments.
All precompiler runtime, OCI and OCCI functions reside in the LIBCLNTS and LIBOCCI program objects that are part of the Oracle distribution. In a POSIX environment, LIBCLNTS and LIBOCCI are loaded from an HFS directory in LIBPATH. In a non-POSIX environment, LIBCLNTS and LIBOCCI are loaded from the JOBLIB/STEPLIB concatenation. Both LIBCLNTS and LIBOCCI are accessed through or in coordination with the Oracle stubs discussed below. For more information on LIBCLNTS and LIBOCCI and how they are accessed, refer to the section "Application Runtime Considerations" and to Chapter 2, "Oracle Software Interaction with z/OS and Language Environment".
Precompiler, mixed precompiler/OCI applications and non-POSIX OCI applications must use an API stub. However, OCI POSIX applications can use an API stub. The API stub is used to resolve the application's references to precompiler and OCI functions. Traditional (non-XPLINK) linkage must be used. No other form of linkage to Oracle code is supported. All the API stubs except ORASTBX must be included at link or bind time; COBOL DYNAM applications include ORADMYC at link or bind time which loads ORASTBX at run time. Oracle applications that use COBOL DYNAM are subject to limitations. Refer to the "Pro*COBOL Considerations" section for details on how to compile and link programs using the DYNAM option. For more information on binding and linking with API stubs, refer Table 6-1.
Table 6-1 Binding and Link-Editing with API Stubs
| Platform | Language | Bound with | Creates | Must Specify |
|---|---|---|---|---|
|
Pro*C/C++ or OCI or mixed |
ISO C |
Binder |
PM3/PM4 |
INCLUDE SQLLIB(ORASTBL) |
|
|
ISO C++ |
Binder |
PM3/PM4 |
INCLUDE SQLLIB(ORASTBL) |
|
|
ISO C |
Prelinker/Linkage Editor |
PM2/Load Module |
INCLUDE OBJLIB(ORASTBS) |
|
|
Pre-ISO C++ |
Prelinker/Linkage Editor |
PM2/Load Module |
INCLUDE OBJLIB(ORASTBS) |
|
|
ISO C (OCI V7 names, NOLONGNAME option) |
Linkage Editor |
PM2/Load Module |
INCLUDE OBJLIB(ORASTBS) |
|
|
ISO C |
c89 |
PM3/PM4 |
$ORACLE_HOME/lib/orastbl.o |
|
|
ISO C++ |
c++ |
PM3/PM4 |
$ORACLE_HOME/lib/orastbl.o |
|
Pro*COBOL |
COBOL |
Binder |
PM3/PM4 |
INCLUDE SQLLIB(ORASTBL) |
|
|
COBOL |
Linkage Editor |
PM2/Load Module |
INCLUDE OBJLIB(ORASTBS) |
|
|
COBOL |
Linkage Editor (DYNAM) |
PM2/Load Module |
INCLUDE OBJLIB(ORADMYC) |
|
|
COBOL |
cob2 |
PM3/PM4 |
$ORACLE_HOME/lib/orastbl.o |
|
Pro*FORTRAN |
FORTRAN |
Linkage Editor |
PM2/Load Module |
INCLUDE OBJLIB(ORASTBF) |
|
Pro*PL/I |
PL/I |
Binder |
PM3/PM4 |
INCLUDE SQLLIB(ORASTBL) |
|
|
PL/I |
Linkage Editor |
PM2/Load Module |
INCLUDE OBJLIB(ORASTBS) |
OCCI and mixed OCI/OCCI applications must use XPLINK linkage and a DLL stub. However, OCI POSIX applications can use a DLL stub with traditional or XPLINK linkage. References to OCI and OCCI functions are implicitly resolved at bind time using the LIBCLNTS.x (client) and LIBOCCI.x (OCCI) side decks. No other form of linkage to Oracle code is supported. For more information on binding with DLL stubs, refer Table 6-4.
Without exception, all precompiler, OCI, and OCCI applications on z/OS use LE services at runtime. You must use an LE-enabled compiler to build your applications and LE runtime services must be available when the application executes. In complex application designs-those involving multiple separate executables, multiple compiled languages, multiple tasks or threads, and similar techniques-you must adhere to requirements imposed by LE as well as ones imposed by Oracle.
If you are exploiting Oracle object-relational features in a Pro*C/C++, OCI, or OCCI application, you may also want to use OTT, a utility program that generates C language structure declarations corresponding to database object types.
Most of the Precompiler application build information in this chapter also applies to applications that will run in CICS TS or IMS TM. Additional details and requirements for CICS TS and IMS TM applications are provided later in this chapter.
The foremost determiner of application design considerations is the intended execution environment. CICS TS and IMS TM have very specific requirements and limitations covered separately at the end of this chapter. The other traditional MVS environments (batch job and TSO) have one set of considerations while z/OS UNIX shells have another. In batch and TSO environments the LE POSIX attribute of your application can be either OFF or ON, as you choose, and this affects various LE behaviors such as interpretation of ambiguous filespecs. If your application runs in a shell, the LE POSIX attribute will always be ON.
Regardless of execution environment, your application's ultimate physical form will be one of several z/OS executable formats: a traditional load module (stored in a PDS), or a program object produced by the z/OS binder and stored in a PDSE or as an executable file in an HFS. In general you use the HFS for programs that will run in a shell and a PDS or PDSE for programs that run in other environments.
In terms of requirements, we can distinguish between simple and complex applications. A simple application meets all of the following criteria:
Single load module or program object that does not dynamically invoke any other Oracle-accessing program, including Oracle tools and utilities
Written in a single high level language
Executes as a single batch job step, TSO command, or shell command
Does not require z/OS APF authorization, run in supervisor state or a PSW key other than 8, or use an ASC mode other than primary
If your application fits the prior description, you can skip the section "Requirements for Complex Applications".
In sections that follow, the term application context is used to refer to the collection of visible and internal state data representing the Oracle interactions of a single coherent application. An application context typically represents a connection to an Oracle database server and multiple SQL operations (cursors). It may include multiple connections to the same or different Oracle database servers, using specific facilities provided by OCI or an Oracle Precompiler for that purpose.
In addition, it is important to understand what LE calls an enclave in order to understand the requirements for z/OS Oracle application designs. An enclave is the set of resources and processing associated with a single logical LE application used within a single z/OS task (TCB), with an execution lifetime delineated by well-defined initialization and termination events. For more information on enclaves, refer to the IBM Language Environment Concepts Guide and related publications.
The following requirements apply to all Oracle-accessing applications that run on z/OS, from the simplest to the most complex:
An application must use IBM Language Environment. In other words, you must use a compiler that generates LE-enabled code and that initializes an LE enclave when execution begins.
An application can use any residency mode (RMODE) and either 31-bit or 24-bit addressing mode (AMODE), as permitted by the compiler you use. An application must use the same AMODE on all calls to Oracle API functions. If your application uses 24-bit addressing (AMODE=24), all parameters passed to Oracle interface functions must be addressable with a 24-bit address. For example, they must reside in virtual memory below the 16 MB line. All applications that are compiled with the XPLINK compiler option are AMODE=31.
An application can be reentrant or not, as you choose and as supported by the compiler and linkage you use. The API and DLL stubs and all dynamically loaded Oracle interface code are reentrant, but the application itself is not required to be reentrant. Certain OCI and OCCI facilities require that you compile your C or C++ program with the DLL compiler option, which dictates the RENT option. All applications that are compiled with the XPLINK compiler option are reentrant.
An application must not use the LE exit CEEBXITA. An Oracle-specific version of this exit is provided in the API and DLL stubs and cannot be overridden or replaced. This exit is used to provide cleanup of Oracle-related resources when your application ends; its actions are transparent to your application.
If an application uses any functions implemented in an XPLINK DLL, for example, OCCI, an XPLINK application DLL, the ISO C++ STL, and C++ standard I/O library functions, it must use the XPLINK(ON) LE runtime option. For more information on the XPLINK(ON) LE runtime option, refer to the "Using the XPLINK(ON) LE Runtime Option" section.
Read this section if your application does not meet one or more of the criteria for simple applications listed in the section "Application Design Considerations", or if you are interested in more of the z/OS technical details involved in Oracle application execution. This discussion assumes familiarity with LE and other z/OS features and interfaces.
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.
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.
If permitted by the language and compiler, the application can exploit the DLL mechanism of LE. Your Oracle-accessing programs can call subroutines that are packaged in a DLL and the called subroutines themselves (in the DLL) can also be Oracle-accessing. When using DLLs, your main program must include the API or DLL stub, even if it does not contain any Oracle API calls. In an application that uses a DLL stub, only the main program in an LE enclave should contain the DLL stub.
In an application that uses an API stub, the Oracle API function calls in a DLL always go through the API stub included in the DLL. In an application that uses a DLL stub, the Oracle API function calls in a DLL are implicitly resolved by binding the DLL against the client and OCCI side decks.
When you use DLLs, both the subroutines in the DLL and any Oracle API functions execute in the caller's LE enclave.
If any application code is compiled with XPLINK or uses a DLL that is compiled with XPLINK, such as OCCI, the ISO C++ STL, the ISO C++ standard I/O library, the main program must use the XPLINK(ON) LE runtime option. This can be done by using one of the following methods:
Compiling the main program with XPLINK, where permissible.
Compiling the main program with #pragma runopts(XPLINK(ON)).
Placing XPLINK(ON) into the _CEE_RUNOPTS environment variable. This is the only supported method for COBOL and PL/I main programs.
For more information, refer to z/OS C/C++ Programming Guide or z/OS Language Environment Programming Guide.
Your Pro*COBOL application can use COBOL dynamic linkage to invoke your own subroutines. As with DLLs, your main program must include the API stub regardless of whether it contains Oracle API calls. Subroutines invoked with COBOL dynamic call linkage and containing Oracle API calls must also include the API stub.
Oracle also allows you to use the COBOL DYNAM compiler option, subject to certain limitations. When you compile with DYNAM, the Pro*COBOL API calls themselves are treated as dynamic COBOL calls, loading a special runtime version of the API stub.
When you use COBOL dynamic linkage, the called subroutines execute in the caller's LE enclave.
system()The system() function of C/C++ library can be used to invoke a batch program, a TSO command, CLIST, or EXEC, or a shell command or script. From an LE standpoint, a program or script invoked in this fashion is not a subroutine; it is a main program and runs in its own LE enclave. This means your application is using multiple LE enclaves, discussed in the section "Multiple LE Enclaves in an Application". You cannot pass Oracle connection state data (such as cursor or connection handles) to a program invoked using system(). Programs invoked with system() must establish their own independent interactions with an Oracle server. You can use system() to invoke Oracle tool or utility programs, such as SQL*Plus.
fetch()The fetch() function of C/C++ library loads an executable, returning a function pointer that can be used to invoke the executable one or more times. A program invoked this way runs as a subroutine in the caller's LE enclave and cannot be a main routine. If you use fetch() to run one or more Oracle-accessing subroutines, you must include the API stub in the main program and in all Oracle-accessing subroutines or include the DLL stub in the main program and bind all Oracle-accessing routines against the client and OCCI side decks.
These services are accessed directly using z/OS Assembler Language macros. The LINK service is also used internally by other facilities, including ISPLINK under TSO ISPF. These mechanisms operate outside of LE, so care must be taken to ensure that LE facilities are not impacted.
If you use LOAD and CALL to invoke an Oracle-accessing program, one of two conditions must be met when CALL is issued:
No LE enclave exists at the time of the CALL, and the called program operates as a main program, initializing its own LE enclave and terminating it before returning.
An LE enclave exists, the Assembler program that issues the CALL is LE-conforming, and the called program operates as a subroutine and runs in the same enclave-it cannot be a main routine. In this case, the main program must include the API or DLL stub, even if it is written entirely in Assembler and contains no Oracle API calls.
When you use a LINK macro to invoke an Oracle-accessing program, the called program must be a main routine that initializes its own LE enclave. If an enclave already exists at the time of the LINK, the called program runs as a nested enclave, discussed in the section "Multiple LE Enclaves in an Application". Regardless of which condition exists, you cannot pass Oracle connection state data, such as cursor or connection handles, to the called program.
The ATTACH macro creates a subtask, which means you are using multitasking, discussed in the section "Multiple LE Enclaves in an Application". The program you run with ATTACH must be a main routine that creates its own LE enclave. You cannot pass Oracle connection state data, such as cursor or connection handles, from one z/OS task to another.
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.
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.
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.
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.
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.
The following steps outline how to build an application to access an Oracle database using API stubs:
Precompile your program with one of the Oracle Precompilers and other precompilers that are required by your target environment (not required for OCI applications).
Compile your program with the host language compiler.
Link your program with an API stub designed especially for the target environment.
Run your program in the target environment.
The following steps outline how to build an application to access an Oracle database using DLL stubs:
Compile your program with the host language compiler.
Bind your program with a DLL stub designed especially for the target environment.
Run your program in the target environment.
Oracle Precompilers are used to process C/C++, COBOL, FORTRAN, and PL/I programs before passing them to their native compilers. They translate embedded SQL statements into the appropriate language statements and calls necessary to access an Oracle database. Oracle Precompilers are supported in all three operating environments (batch, TSO, and shell) except Pro*FORTRAN and Pro*PL/I, which are not supported in the shell environment.
You should review the information in the following product-specific documentation on Oracle Precompilers before proceeding with the z/OS-specific information in this section:
Programmer's Guide to the Oracle Precompilers
Pro*C/C++ Precompiler Programmer's Guide
Pro*COBOL Precompiler Programmer's Guide
Pro*FORTRAN Supplement to the Oracle Precompilers Guide
Pro*PL/I Supplement to the Oracle Precompilers Guide
Oracle Precompilers can be run in various environments. The following table shows the names of the executables for each environment:
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:
Table 6-3 Oracle Precompiler INCLUDE Files
| Language | Member Name | Data Structure |
|---|---|---|
|
C/C++ |
SQLCAC |
SQLCA |
|
C/C++ |
ORACAC |
ORACA |
|
C/C++ |
ORADAC |
ORADA |
|
COBOL |
SQLCACOB |
SQLCA |
|
COBOL |
ORACACOB |
ORACA |
|
FORTRAN |
SQLCAFOR |
SQLCA |
|
FORTRAN |
SQLCAFOR |
ORACA |
|
PL/I |
SQLCAPLI |
SQLCA |
|
PL/I |
ORACAPLI |
ORACA |
For more information about data structures, refer to your Oracle Precompiler documentation.
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.
specifies the input file containing the source code, in any supported language, for the precompiler. The INAME file can be a sequential data set, a PDS member, an instream (DD *) data set, or an HFS file. In batch and TSO environments there is no default. Typically, this operand is coded as shown in the following example with a SYSIN DD statement pointing to the input source code:
INAME=//DD:SYSIN
specifies the file to contain the output from the Oracle Precompiler. The ONAME file can be a sequential data set, a PDS member, or an HFS file. In batch and TSO environments there is no default. Typically, this operand is coded as shown in the following example with a SYSPUNCH DD statement pointing to a data set that is passed as input to the native language compiler:
ONAME=//DD:SYSPUNCH
specifies the file to contain the listing from the Oracle Precompiler. The LNAME file can be a sequential data set, a PDS member, a SYSOUT data set, or an HFS file. In batch and TSO environments there is no default. The LNAME parameter cannot specify the SYSPRINT DD. Typically, this operand is coded as shown in the following example with a LIST DD statement pointing to a SYSOUT data set:
LNAME=//DD:LIST
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.
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.
The following sections discuss certain considerations that impact Oracle Precompiler programs written in a particular language, regardless of the target environment running the program:
Oracle Corporation supports any currently supported IBM compiler that uses the LE runtime environment.
When using Pro*COBOL, each of the following has special considerations:
RETURN-CODE Special Register. On z/OS, COBOL programs use the RETURN-CODE special register to pass a return code from a main program back to z/OS. It is then used to form the job step completion code. The z/OS standard subroutine linkage places unpredictable values into the RETURN-CODE special register as a subroutine is called. Subprograms on z/OS can set the value of the RETURN-CODE special register as they exit. However, the RETURN-CODE special register is an IBM extension to the COBOL language and is not part of the SQL standard.
In compliance with the SQL standard, Oracle Pro*COBOL does not make use of the RETURN-CODE special register and does not explicitly set the value. This causes the value of the RETURN-CODE special register to be unpredictable after each SQL statement completes. If a SQL statement is issued immediately before the main program returns to z/OS, then the unpredictable value remains in the RETURN-CODE special register and is used to form the job step completion code. The application developer is responsible for ensuring the correctness of the RETURN-CODE special register.
INTEGER Values. In the Oracle product documentation, SQL library function parameters are often documented with a data type of INTEGER. In z/OS, integers are a fullword and must be defined in COBOL as fullword COMP fields with sizes from S9(5) to S9(8). An S9(4) or smaller definition generates a halfword that is the default integer size on some operating systems. This can cause problems when migrating applications from other operating systems to z/OS. For example, a call to SQLIEM expects an integer MESSAGE_LENGTH as the second parameter. Define a MESSAGE_LENGTH field as PIC S9(8) COMP in your program. A call to SQLGLM expects the second and third parameters, BUFFER_SIZE and MESSAGE_LENGTH respectively, to be integers. As with SQLIEM, they must be defined as PIC S9(8) COMP fields.
DYNAM Compiler Option. Pro*COBOL support for the DYNAM option is provided with a loadable version of the API stub. This support is meant for installations whose standards or existing application designs require the use of DYNAM; it is not recommended for general use. When you use COBOL DYNAM, the Oracle LE exit CEEBXITA is not included with your application and does not run at enclave termination. This means Pro*COBOL programs that use DYNAM support cannot be executed as part of a multiple LE enclave design. Refer to the sections "Compiling Programs", "Linking Programs", and "Oracle Interface Initialization, Processing, and Error Handling" for details on using COBOL DYNAM support.
When using Pro*C/C++, OCI, or OCCI, object support has special considerations. The OTT utility is used to convert database object type definitions into C programming language declarations that are included in your Pro*C/C++, OCI, or OCCI applications. OTT is a Java application which must run in a POSIX environment. For more information on OTT, refer to your Oracle Precompiler documentation.
All Oracle interface code is compiled with the ENUMSIZE(INT) option. In order to be compatible, your Pro*C/C++, OCI, and OCCI programs must also use ENUMSIZE(INT).
Currently only FLOAT(HEX) is supported in Pro*C/C++, OCI, and OCCI programs on z/OS. You cannot use FLOAT(IEEE) in an Oracle-accessing application.
Pro*FORTRAN is supported in the non-POSIX batch and TSO environments only. It is not supported in the POSIX environment.
When using Pro*PL/I, the record format of the output file and the execution environment have special considerations, as follows:
The native language output from the Pro*PL/I Precompiler that is directed to the data set specified in the ONAME parameter cannot have a RECFM of V. This is because a z/OS compiler restriction requires all PL/I programs contained in a variable length data set to have a blank or a sequence number in columns 1 to 8. This restriction does not apply to the data set input to Pro*PL/I, only to the intermediate data set passed to the PL/I compiler.
Pro*PL/I is supported in the non-POSIX batch and TSO environments only. It is not supported in the POSIX environment.
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)
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
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
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,
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
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
This section contains information regarding compiler options for Oracle applications. The settings are grouped by language with an environment indicator to reflect whether the setting applies.
Environment indicators are listed as follows:
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
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
Precompiled, OCI, and OCCI applications must be compiled using their host language compiler. In the case of precompiled applications, the output generated by the precompiler is used as input to the host language compiler.
Use of the DLL compiler option when compiling Pro*COBOL, Pro*C/C++, OCI, or OCCI programs is an option and is generally determined by the design of the application. This is supported for Oracle applications, but with two exceptions:
Pro*COBOL applications compiled with the COBOL DYNAM option cannot specify the DLL option.
OCI C API stub applications that make use of callbacks, C++ applications and DLL stub applications.
Considerations for building applications to run in the CICS TS and IMS TM environments are covered in the sections "Developing Oracle Applications for the CICS TS Environment" and "Developing Oracle Applications for the IMS TM Environment".
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
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:
Point to the program to be compiled. This can be in a dataset (DD DSN) or an HFS file (DD PATH).
Replace $ORACLE_HOME with the Oracle home directory.
After a program has been compiled, the resulting object code is passed to the binder, where it is linked with the API stub.
Considerations for linking applications to run in the CICS TS and IMS TM environments are covered in the sections "Developing Oracle Applications for the CICS TS Environment" and"Developing Oracle Applications for the IMS TM Environment".
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:
Include additional libraries required by your program and any runtime libraries required by the native language.
This DD statement describes the library in which your linkedited Oracle load module is placed.
This DD statement points to the object output from your Oracle Precompiler program's native language compiler.
The specific contents of the SYSLIN DD statement depend on the target environment. Refer to "Linking Programs" for more information.
Include any additional linkage editor statements you might require.
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.
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:
Include additional libraries required by your program and any runtime libraries required by the native language.
This DD statement describes the library in which your linkedited Oracle load module is placed.
This DD statement points to the object output from your Oracle Precompiler program's native language compiler.
The specific contents of the SYSLIN DD statement depend on the target environment. Refer to "Linking Programs" for more information.
Include any additional linkage editor statements you might require.
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.
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
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.
Table 6-4 Binding with DLL Stubs
| Platform | Language | Bound With | XPLINK | Must Specify |
|---|---|---|---|---|
|
OCI Apps (no Pro*C/C++ or OCCI) |
ISO C |
c89 |
Not Recommended |
$ORACLE_HOME/lib/orastbp.o $ORACLE_HOME/lib/LIBCLNTS.x |
|
|
Pre-ISO C++ |
c++ |
Not Recommended |
$ORACLE_HOME/lib/orastbp.o $ORACLE_HOME/lib/LIBCLNTS.x |
|
|
ISO C++ |
c++ |
Recommended |
$ORACLE_HOME/lib/orastbp.o $ORACLE_HOME/lib/LIBCLNTS.x |
|
OCCI Apps (no Pro*C/C++, or mixed with OCI) |
Pre-ISO C++ |
c++ |
Required |
$ORACLE_HOME/lib/orastbp.o $ORACLE_HOME/lib/LIBCLNTS.x $ORACLE_HOME/lib/LIBOCCI.x |
|
|
ISO C++ |
c++ |
Required |
$ORACLE_HOME/lib/orastbp.o $ORACLE_HOME/lib/LIBCLNTS.x $ORACLE_HOME/lib/LIBOCCI.x |
|
|
ISO C++ |
Binder |
Required |
$ORACLE_HOME/lib/orastbz.o $ORACLE_HOME/lib/LIBCLNTS.x $ORACLE_HOME/lib/LIBOCCI.x |
Note:
If an application uses DLL stubs, the DLL stub should be included in the main program. Application DLLs and other subroutines loaded by the main program should not include the DLL stub.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
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:
Use your installation's run-time library dataset prefix.
Use your installation's standard I/O library prefix.
Point to the PDSE member where the program will be stored.
Replace $ORACLE_HOME with the Oracle home directory.
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:
Use your installation's run-time library dataset prefix.
Use your installation's standard I/O library prefix.
Point to the PDSE member where the program will be stored.
Replace $ORACLE_HOME with the Oracle home directory.
Oracle has provided sample batch JCL and POSIX make files to simplify building Oracle Precompiler, OCI, and OCCI applications. Chances are you will need to modify them for your system. Consult your system administrator to determine if these are installed on your system and whether they already have been modified for your system.
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:
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:
Table 6-6 Sample Make Files to Build an Oracle Precompiler Program
| Precompiler | Make File |
|---|---|
|
Pro*C/C++ |
|
|
Pro*COBOL |
|
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
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
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.
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
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.
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.
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 …"
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
The nominal Pro*C/C++, Pro*COBOL, and Pro*PL/I application executable is a PM3 or PM4 program object that must reside in a PDSE or HFS file. This section presents methods for producing traditional load modules. The common component of these methods is an alternate, short name API stub called ORASTBS. ORASTBS is shipped as an object deck, suitable for prelinker or binder input.
Note:
These methods can also create a PM2 program object that resides in a PDSE or HFS file.For more information, refer to MVS Program Management:User's Guide and Reference
This method is suitable for the following types of Oracle API programs: Pro*COBOL, Pro*PL/I, and OCI V7 programs. Existing Pro*C/C++ and OCI V8 programs calling API functions using their truncated names, as documented in prior releases, can use this method as well. The object produced by the compile step, along with the alternate API stub ORASTBS, is passed to the prelinker and the resultant object is then passed to the binder, as shown in the following example:
//PRELINK EXEC PGM=EDCPRLK,COND=(4,LT)
//STEPLIB DD DISP=SHR,
// DSNAME=SYS1.SCEERUN
//SYSMSGS DD DISP=SHR,
// DSNAME=SYS1.SCEEMSGP(EDCPMSGE)
//SYSLIB DD DISP=SHR,
// DSNAME=ORACLE.V10.OBJLIB
//SYSIN DD DISP=(OLD,DELETE),
// DSN=&&LOADSET
// DD DDNAME=SYSIN2
//SYSMOD DD DISP=(NEW,PASS),
// DSNAME=&&PLKSET,
// UNIT=VIO,
// SPACE=(32000,(30,30)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSIN2 DD *
INCLUDE SYSLIB(ORASTBS)
/*
//LINKEDIT EXEC PGM=HEWL,COND=(4,LT),
// PARM='LET,LIST,MAP,XREF'
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DISP=SHR,
// DSN=SYS1.SCEELKED
//SYSUT1 DD UNIT=VIO
//SYSLMOD DD DISP=SHR,
// DSN=USER.LOADLIB(SAMPLE1)
//SYSLIN DD DISP=(OLD,DELETE),
// DSN=&&PLKSET
// DD DDNAME=SYSIN
//SYSIN DD DUMMY
The steps to precompile and/or compile the program would precede the PRELINK step. Note that in the case of C programs, NOLONGNAME must be specified on the compile step.
This method is suitable for the following types of Oracle API programs: Pro*C/C++ and OCI V8. At precompile and/or compile time, a header file is included which maps the longnames to shortnames.
Inclusion of the header file is triggered by the definition of ORA_SNAME. The object produced by the compile step, along with the alternate API stub ORASTBS, is passed to the prelinker and the resultant object is then passed to the linkage editor, as shown in the following example:
//PRECOMP EXEC PGM=PROC,
// PARM='++//DD:SYSPARM'
//STEPLIB DD DISP=SHR,
// DSN=ORACLE.V10.CMDLOAD
//ORA$LIB DD DISP=SHR,
// DSN=ORACLE.V10.MESG
//SYSPRINT DD SYSOUT=*,
// DCB=(LRECL=132,BLKSIZE=1320,RECFM=VB)
//SYSOUT DD SYSOUT=*,
// DCB=(LRECL=132,BLKSIZE=1320,RECFM=VB)
//SYSERR DD SYSOUT=*,
// DCB=(LRECL=132,BLKSIZE=1320,RECFM=VB)
//SYSCOD DD UNIT=SYSDA,
// SPACE=(TRK,(10,10))
//SYSCUD DD UNIT=SYSDA,
// SPACE=(TRK,(10,10))
//SYSPUNCH DD DISP=(,PASS),
// DSN=&&PCCOUT,
// UNIT=SYSDA,
// SPACE=(CYL,(2,1)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=800)
//SYSUT1 DD UNIT=SYSDA,
// SPACE=(CYL,(5,5))
//SYSUT2 DD UNIT=VIO
//SYSUT3 DD UNIT=VIO
//SYSLIB DD DISP=SHR,
// DSN=USER.MACLIB
// DD DISP=SHR,
// DSN=ORACLE.V10.H
// DD DISP=SHR,
// DSN=SYS1.SCEEH.H
// DD DISP=SHR,
// DSN=SYS1.SCEEH.SYS.H
// DD DISP=SHR,
// DSN=SYS1.SCLBH.H
//CONFIG DD DUMMY
//SYSIN DD DISP=SHR,
// DSN=USER.PROGRAM.SRC
//ORA@XXXX DD DUMMY
//SYSPARM DD *
INAME=//DD:SYSIN
LNAME=//DD:SYSPRINT
ONAME=//DD:SYSPUNCH
CONFIG=//DD:CONFIG
CODE=ANSI_C
USER=SCOTT/TIGER
SQLCHECK=FULL
DEFINE=ORA_SNAME
/*
//COMPILE EXEC PGM=CBCDRVR,COND=(0,LT),
// PARM=('/SOURCE,NOMAR,NOSEQ,LIST,RENT,DEF(ORA_SNAME=)')
//STEPLIB DD DISP=SHR,
// DSNAME=SYS1.SCEERUN
// DD DISP=SHR,
// DSNAME=SYS1.SCBCCMP
//SYSMSGS DD SYSOUT=*
//SYSLIB DD DISP=SHR,
// DSN=ORACLE.V10.H
// DD DISP=SHR,
// DSN=SYS1.SCEEH.H
// DD DISP=SHR,
// DSN=SYS1.SCEEH.SYS.H
// DD DISP=SHR,
// DSN=SYS1.SCLBH.H
//SYSLIN DD DISP=(,PASS),
// DSN=&&LOADSET,
// UNIT=VIO,
// SPACE=(CYL,(3,3)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSCPRT DD SYSOUT=*
//SYSUT1 DD UNIT=VIO,
// SPACE=(32000,(30,30)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
//SYSUT4 DD UNIT=VIO,
// SPACE=(32000,(30,30)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
//SYSUT5 DD UNIT=VIO,
// SPACE=(32000,(30,30)),
// DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT6 DD UNIT=VIO,
// SPACE=(32000,(30,30)),
// DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT7 DD UNIT=VIO,
// SPACE=(32000,(30,30)),
// DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT8 DD UNIT=VIO,
// SPACE=(32000,(30,30)),
// DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT9 DD UNIT=VIO,
// SPACE=(32000,(30,30)),
// DCB=(RECFM=VB,LRECL=137,BLKSIZE=882)
//SYSUT10 DD SYSOUT=*
//SYSUT14 DD UNIT=VIO,
// SPACE=(32000,(30,30)),
// DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSIN DD DISP=(OLD,DELETE),
// DSN=&&PCCOUT
The precompile step is only needed when the program is a Pro*C/C++ application. For OCI V8 programs, only the compile step is needed. In either case, the object produced by the compile step, with the alternate API stub ORASTBS, are passed to the prelinker and the resultant object is then passed to the binder, discussed.
This method is suitable for Pro*COBOL and Pro*PL/I applications and Pro*C/C++ applications that are written in C and do not use OCI. The object deck produced by the compile step must not contain any long names. C must be compiled with NOLONGNAME. It and the alternate API stub ORASTBS are passed to the binder, as shown in the following example:
//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(ORASTBS) - Refer to Note 4 -
- Refer to Note 5 -
/*
Usage Notes:
Include additional libraries required by your program and any runtime libraries required by the native language.
This DD statement describes the library in which your linkedited Oracle load module is placed.
This DD statement points to the object output from your Oracle Precompiler program's native language compiler.
The specific contents of the SYSLIN DD statement depend on the target environment. Refer to "Linking Programs" for more information.
Include any additional linkage editor statements you might require.
Runtime considerations for an Oracle Database for z/OS application depend on the execution environment (batch, TSO, or POSIX) and are essentially the same considerations as those for the Oracle tools and utilities on z/OS, with the addition of whatever resources the application itself requires. Refer to Chapter 2 for a description of basic runtime requirements for the Oracle Database for z/OS client. In this chapter, we provide additional processing details that may be helpful in application design and debugging. Refer to Table 6-7 and Table 6-8 for timelines of Oracle applications that use API and DLL stubs.
In most cases, the first call of an API stub application to an Oracle interface function causes the API stub to load and initialize LIBCLNTS, a large program object containing all of the Oracle interface code for both Oracle Precompiler and OCI applications. (A few precompiler runtime calls, such as the SQLADR function, are serviced entirely within the API stub and do not trigger LIBCLNTS initialization.)
In an API stub application, the API stub loads LIBCLNTS using the LE DLL mechanism. In a DLL stub application, LE loads LIBCLNTS (and, for an OCCI application, LIBOCCI) itself before main(), if main() is compiled with XPLINK, or at the application's first call to an OCI or OCCI API function. In addition to locating or loading the LIBCLNTS executable code, LE allocates virtual memory for LIBCLNTS Writeable Static Area (WSA) and for various internal LE data structures.
After successful LE initialization of LIBCLNTS, the API stub calls an Oracle-specific initialization function within LIBCLNTS and certain Oracle initializations are done, such as the processing of global and local environment variable files in non-POSIX applications, as described in Chapter 2.
For an OCI or OCCI POSIX DLL stub application, no Oracle-specific initialization of LIBCLNTS is required. For a native OCCI (non-POSIX) batch or TSO application, intialization code in the orastbz stub calls the Oracle-specific initialization function within LIBCLNTS.
For an API stub application, after successful Oracle initialization, the original application call to an interface function is routed to the appropriate function within LIBCLNTS. Subsequent interface calls from the application skip the loading and initialization activities and are routed directly to the target LIBCLNTS function. OCI and OCCI interface calls in DLL stub applications go directly from the application to LIBCLNTS or LIBOCCI.
For an API stub application, errors that arise during LIBCLNTS loading and initialization may be detected by LE or by Oracle code. In most error situations control ends up back in the API stub, which issues messages describing the error and then issues a User 2010 (U2010) ABEND with an accompanying reason code. With one exception, these descriptive messages are issued to the LE message file using the LE CEEMOUT function. The exception is when the API stub detects that the caller is not LE-enabled. In this case, CEEMOUT is not available and the descriptive message is written to the job log with WTO. For more information on error messages, refer to the Oracle Database Messages Guide for IBM z/OS.
On all Oracle interface calls from an API stub application, both initial and subsequent, the API stub establishes an LE condition handler for the duration of the call. This means that severe errors detected or raised by LE during either initialization or Oracle call processing cause control to pass to the Oracle handler, which issues message MIC012E to indicate what phase of Oracle API processing was occurring and to display the LE condition token associated with the error. The Oracle handler returns control (percolates) to LE, which passes control to any condition handlers established before Oracle's, including those that may have been established in the application. If there are no other handlers, or the ones there also percolate the error, control ultimately reaches LE's default handler which terminates the enclave.
Normal Oracle processing errors (such as failure to connect to a target server) do not raise LE conditions and so do not participate in the processing just described. Such errors return various error codes to an application as described in the Oracle Precompiler and OCI documentation. An ABEND during an Oracle interface call normally gets trapped by LE and invokes the condition handling mechanisms. This is true for both User (Uxxxx) and System (Sxxx) ABENDs unless the application has disabled LE's ABEND interception with the runtime option TRAP(OFF). Be aware that the U2010 ABEND issued for failed LIBCLNTS initialization is subject to this trapping and condition handling process.
For COBOL applications built with the DYNAM option, the following exceptions apply:
Since the COBOL main module does not include the API stub, the initialization normally performed by the API stub is deferred until the first SQL function is loaded into memory and then called.
To load the first SQL function the system must load the module ORASTBX. ORASTBX resides in the CMDLOAD data set, which also contain LIBCLNTS. If there is a problem loading LIBCLNTS, the API stub initialization will indicate so with a messages similar to the following, followed by a U2010 abend:
MIC0022E Failed to load Oracle API module LIBCLNTS - errno 205, EDC5205S DLL module not found. MIC011E Oracle API processing error, reason code 002
If there is a problem finding or loading ORASTBX, an error will be reported by the COBOL runtime and an S806 abend may result.
Because the COBOL main module does not include the API stub, there is an issue with LE initialization. The COBOL main module must be marked, so that when LE initialization is performed for the COBOL components, some LE initialization is done to prepare for calling the C components within ORASTBX. This is done by including ORADMYC during the linking of the COBOL module. If the C part of the LE initialization is not perform, then the following error will result:
MIC011E Oracle API processing error, reason code 014
This is followed by a U2010 abend with reason code 14. Reason code 14 uniquely identifies this as the build-time mistake: ORADMYC was not included.
Because of the missing API stub, the CEEBXITA routine is absent from the enclave, which excludes a COBOL DYNAM module from participating in nested enclave situations.
Refer to Tables Table 6-7 and Table 6-8 for an overview of the timeline for API stub and DLL stub applications.
Table 6-7 Timeline for Oracle Applications Using API Stubs
| When | Action |
|---|---|
|
At bind or link-edit time |
|
|
During LE initialization, in the stub's CEEBXITA exit |
Establish support for multiple LE enclaves |
|
At first Oracle API call, its API stub routine |
|
|
At each Oracle API call, its API stub routine |
|
|
At normal Termination, the stub's CEEBXITA exit |
Clean up multiple LE enclave support |
Table 6-8 Timeline for Oracle Applications Using DLL Stubs
| When | Action |
|---|---|
|
At bind time |
|
|
During LE initialization, the stub's CEEBXITA exit |
Establish support for multiple LE enclaves |
|
Before main() (if app uses XPLINK) or before first API call (otherwise) |
|
|
At each Oracle API call |
Call API routine in LIBCLNTS (OCI) or LIBOCCI (OCCI) |
|
At normal Termination, the stub's CEEBXITA exit |
Clean up multiple LE enclave support |
See Also:
IBM language-specific documentation and to the IBM Language Environment Programming Guide for details on LE condition handling, condition tokens, the LE message file, and related topicsThe freeing of certain Oracle client interface resources (including allocated virtual memory, open files or data sets, and dynamically-loaded program code) may not occur until the application's LE enclave terminates. In some application designs this can be long after the application's last Oracle interaction, giving the appearance of a memory leak or similar resource issue. This is expected behavior and not a defect. If you want to ensure that all Oracle-related resources allocated by a client are freed, either the associated LE enclave or the associated z/OS task (TCB) must terminate.
The foregoing point refers only to resources in the client environment, not to resources allocated on the client's behalf in a target Oracle database server. Freeing of resources in the server occurs when the server recognizes that the client is disconnected. Normally this happens when the client logs off of the server through the appropriate OCI or precompiler mechanism. If the application fails to log off, the session persists in the server and server resources remain allocated until the z/OS task (TCB) or address space associated with the client terminates, either normally or abnormally. If the client is connected to the server through TCP/IP protocol, there may be a discernable delay before the server recognizes that the client has terminated.
If a z/OS client application uses cross-memory (XM) protocol to connect to a local Oracle database server and the associated z/OS task terminates either normally or abnormally without logging off, a z/OS resource cleanup routine executes automatically to inform the server that the client is gone. Message MIS0215I is issued by the resource cleanup routine, reporting the status of the call to inform the server. This message is issued to the log, through WTO, as LE services are terminated at this point. Appearance of this message in an application suggests that proper logoff operations were not done.
Oracle Access Manager for CICS TS provides the interface between Oracle Precompiler programs (COBOL, C languages, or PL/I) and the Oracle database through a CICS TS transaction. CICS TS programs that access the Oracle database are built by precompiling the program containing Oracle SQL statements with the appropriate Oracle Precompiler, translating the output produced with the CICS TS translator or the integrated translator provided with IBM Enterprise COBOL, and compiling and linking the program with the Oracle ORACSTUB object built as part of the Access Manager for CICS TS configuration. ORACSTUB contains code to resolve calls to Oracle code from the application program and the name of the Oracle Access Manager for CICS TS instance, also known as the adapter name, which processes the requests.
CICS TS programs do not designate a target database. Instead, the program communicates with a target adapter named in ORACSTUB. The adapter communicates with a designated database which is defined in the configuration process. This allows the target database to be changed (between test and production, for example) and the Oracle Access Manager for CICS TS configuration to be changed, without changing the CICS TS program.
CICS TS application programs accessing the Oracle database are similar to other precompiler applications containing SQL statements that are passed to the Oracle database as the program executes. The following sections describe special considerations in the CICS TS environment:
The following CICS TS versions are supported by Oracle Database for z/OS:
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.
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.
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.
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.
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.
If Oracle Access Manager for CICS TS is configured with the EDF option, a SQL statement will be displayed when the call is made to the Oracle database. Additionally, CONNECT statements are displayed as CONNECT (no user id will be displayed), and SQL statements are displayed with variable names (values will not replace variable names).
Environment variables are a part of the configuration of Oracle Access Manager for CICS TS and apply to all CICS TS programs accessing a particular Oracle Access Manager for CICS TS instance. For more information, refer to the Oracle Database System Administration Guide for IBM z/OS (OS/390).
An Oracle CICS TS program is precompiled in the same manner as other Oracle Precompiler programs. Refer to the section "Precompiling Programs". The output of the precompiler (the "&&PCCOUT" data set) is passed to the CICS TS translator. The precompile step must precede the CICS TS translation step or the CICS TS translator will issue a warning for each EXEC SQL statement.
When linking a program to run under CICS TS, add the following linkage editor control statement:
INCLUDE SYSLIB(ORACSTUB)
The SYSLIB DD statement includes the data set with the appropriate ORACSTUB object. References to ORASTBS, ORASTBL, or AMILS should not be included. If there are any unresolved references for symbols whose names start with SQL, then ensure ORACSTUB is included in the linkedit. If ORACSTUB is correctly included, then contact Oracle Support Services for additional assistance.
AMODE must be set to 31. There are no special requirements for RMODE.
Refer to the machine readable samples in the SRCLIB library for sample JCL used to process COBOL or C language programs.
Normal CICS TS practices for defining your program to CICS TS are followed for Oracle Precompiler programs. CICS TS programs access a shared copy of the full SQL interface, called the CICS TS adapter, that must be configured and available before your program begins running. If the adapter is not available, then you receive error AEY9 from CICS TS and you must contact your CICS TS system administrator to have this condition corrected.
Oracle Access Manager for IMS TM allows COBOL, C or PL/I programming language programs running in an IMS MPP, IFP, or BMP region to access an Oracle Database 10g server anywhere in your network. IMS TM programs accessing Oracle Database 10g databases use the normal IMS calls for input and output message processing, data access and synchronization as they would if Oracle Database 10g were not in use.
IMS TM application programs accessing the Oracle database are similar to other precompiler applications containing SQL statements that are passed to the Oracle database as the program executes. The following sections describe special considerations in the IMS environment:
Accessing Oracle Database 10g and DB2 Databases in a Single Transaction
Processing of Oracle Database 10g Errors by Your IMS TM Program
The following IMS TM versions are supported by Oracle Database for z/OS:
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.
See Also:
For more information, refer to the Oracle Database System Administration Guide for IBM z/OS (OS/390)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.
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.
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.
Use only Oracle DML SQL statements in programs used with Oracle Access Manager for IMS TM.
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.
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.
Environment variables are a part of the configuration of Oracle Access Manager for IMS TM and are defined for IMS transactions in the Resource Translation Table (RTT). For more information, refer to the Oracle Database System Administration Guide for IBM z/OS.
This section describes considerations for linking a program to run under IMS TM:
Add the following linkage editor control statements to the SYSLIN DD statement:
INCLUDE SYSLIB(AMILS) INCLUDE SYSLIB(lit-module)
The lit-module statement is the customer-generated language interface token(LIT) described in this chapter. For more information, refer to the Oracle Database System Administration Guide for IBM z/OS (OS/390).
Do not include references to ORASTBL, ORASTBS, or ORACSTUB.
If there are unresolved external references for symbols whose names begin with SQL, then ensure AMILS is included in the linkedit. This API stub resolves any calls in the generated code. If AMILS is correctly included, then the problem might be caused by a missing entry point to the stub routine. You can contact Oracle Support Services for additional assistance.
Normal IMS TM practices for defining your program to IMS are followed for Oracle Precompiler programs. IMS TM programs access a shared copy of the full SQL interface that must be configured and available before your program begins running. If the interface is not available, then you receive error 3042 from IMS TM and you must contact your IMS system administrator to have this condition corrected.
