Oracle® Database User's Guide
10g Release 1 (10.1) for IBM z/OS (OS/390)
Part No. B13524-01
This chapter describes how Oracle software on z/OS is integrated with the operating system. It discusses the common implementation attributes of Oracle components used by end users and application developers. Details on specific Oracle components are provided in later chapters.
This chapter contains the following sections:
Except for components written in PL/SQL or Java, Oracle software that runs on z/OS is written in C. Oracle uses the IBM C/C++ compiler to build its z/OS components and Language Environment (LE) for z/OS to provide some of the operating system runtime services required during program execution. This means C and LE conventions figure heavily in the behavior of Oracle software on z/OS. For example, LE-specific syntax is normally used when specifying data set or HFS file names to an Oracle tool or utility.
Oracle on MVS predates both IBM's C/C++ compiler and LE by a number of years. In the early 1980's, Oracle developed and used its own C compiler and runtime library to support its products on MVS. Certain features of Oracle's runtime library continue to be supported on z/OS so that existing customer JCL and scripts continue to work unmodified. This legacy support causes slight deviations from normal LE behavior in several areas; it is optional and can be disabled if desired.
Besides the optional Oracle runtime compatibility feature, there are a number of areas where LE does not provide services that Oracle software requires, and those needs are met by using Oracle-developed program code. In some cases these services are implemented as extensions to existing LE support. For example, LE does not provide file syntax for directly requesting SYSOUT (JES spool) output. Oracle provides that capability, using file name syntax that is a logical extension of existing LE syntax. Other non-LE program support in Oracle, such as TSO attention interrupt support, is completely separate from LE.
Oracle supports several different z/OS environments for executing Oracle tools and utilities as well as user-written Oracle applications. Both LE and certain parts of Oracle program code behave differently across these environments. Applications that run under CICS TS or IMS TM are controlled by Oracle Access Manager software and are subject to the behaviors and requirements of the specific Access Manager. For more information, refer to Chapter 6, "Developing Oracle Applications to Run on z/OS". The remaining environments are discussed here, and are as follows:
Batch, meaning an environment started from JCL that is neither a TSO session nor a z/OS UNIX shell. This includes normal batch jobs that run in an initiator and started task (STC) address spaces that do not use an initiator.
z/OS provides a set of POSIX-compliant UNIX services. Originally called OpenEdition MVS, they are now called z/OS UNIX System Services. The most common way to use these services is from the z/OS UNIX shell variations described in the previous list, which provide a UNIX-style shell environment with a Hierarchical File System (HFS) and implementations of widely-used UNIX utilities like
Any task in a z/OS address space can interact with z/OS UNIX System Services provided it is authorized to do so. For example, an application program does not have to be launched from a z/OS UNIX shell in order to use z/OS UNIX System Services features such as HFS files or POSIX threading. Conversely, programs launched from a z/OS UNIX shell generally are free to utilize z/OS services and facilities that do not conflict with the mechanisms of z/OS UNIX Systems Services.
Many of the significant behavior differences in application programs are associated with LE, not with being in a z/OS UNIX shell. LE has its own internal POSIX indicator that is set to either ON or OFF when a program begins executing, and remains so for the life of the program (technically, for the life of the LE enclave). The initial setting of this POSIX indicator can come from the application program, from an external runtime specification, or can be defaulted based on the environment. In the case of Oracle tools and utilities, POSIX is set to ON if the program executable was obtained from HFS (for example, as a shell command). Otherwise, it is set to OFF (for example, with conventional batch and TSO execution).
Thus, the phrase "in a POSIX environment" means when a program is executing with POSIX set to ON, regardless of whether the program executes in a z/OS UNIX shell or in an ordinary batch job or TSO session. For behaviors that depend specifically on a z/OS UNIX System Services shell, the phrase "in a z/OS UNIX shell" or a reference to the specific shell will be used.
Running a program that accesses an Oracle database on z/OS, including Oracle tools and utilities and Pro*C, Pro*COBOL, Pro*PL/I, or OCI applications, requires the following components to be accessible:
Application program, tool, or utility
Oracle program interface code
Oracle supporting data objects
How these components are accessed depends on the execution environment and on how Oracle and LE software are installed and configured on your system. This, in turn, may dictate how you code the JCL, what things you ALLOCATE in a TSO session, or the environment variables you set in a z/OS UNIX shell. This section explains how these components are accessed in general. You may need to ask your z/OS system administrator or Oracle database administrator for the installation specifics of your system.
Oracle tools and utilities usually are installed in a specific load library data set, referred to in this document as the CMDLOAD data set. The exact name of the data set is chosen by the installation and can vary over different systems and over different versions or releases of Oracle software. For environments other than a z/OS UNIX shell, you may need to specify this data set in JCL (in a JOBLIB or STEPLIB DD statement) or in a TSO command such as CALL or TSOLIB. However, if your installation adds the CMDLOAD data set to the system linklist or copies the CMDLOAD modules into an existing linklist or LPA library, the modules are available in all environments without specifying a data set.
For z/OS UNIX shell environments, Oracle tools and utilities normally reside in HFS, in the
bin subdirectory of the installation Oracle home directory. Like the name of the CMDLOAD data set, the exact path for the Oracle home directory is chosen by the installation. This document refers to this directory as the Oracle home directory or as ORACLE_HOME, which is the name of an environment variable normally set to the Oracle home directory path. In the z/OS UNIX shell, as in other UNIX systems, the PATH environment variable is used to specify the directories in which to search for an executable. Thus, to access Oracle tools and utilities in a z/OS UNIX shell you would normally include the bin subdirectory of the Oracle home directory in your PATH environment variable.
Oracle application programs can reside in a normal load library data set, linklist or LPA (link pack area) data set, or z/OS UNIX System Services HFS directory. Follow the conventions or standards of your installation to make your application program available for execution.
It is typical for LE runtime to be available in all supported z/OS Oracle execution environments without special action on your part. In the rare situation where it is not, you will need to specify LE runtime library data sets in your JOBLIB or STEPLIB concatenation or in a TSOLIB command in TSO. Check with your z/OS system administrator if you are unsure of LE availability or to determine the data set names for LE runtime services, if needed.
LE is required in all z/OS UNIX shells, so no special action is required to make LE available to a shell-based Oracle application.
It is possible for a single z/OS system to have multiple releases or maintenance levels of LE installed, and LE provides a mechanism called Run-Time Library Services (RTLS) to manage this. If your installation is using RTLS, consult with your z/OS system administrator to determine how to access the correct release of LE for your Oracle database application programs.
The Oracle program interface code is a program object named LIBCLNTS. It is required at runtime by all Oracle programs on z/OS including Oracle tools and utilities and any applications that access the Oracle database. In conventional batch and TSO environments, LIBCLNTS normally resides in the same CMDLOAD data set as the Oracle tools and utilities. If your installation has made CMDLOAD a linklist library, or if LIBCLNTS has been placed in a linklist or LPA library, the interface code can be accessed from any batch job or TSO session without special action. Otherwise, the CMDLOAD data set must be included in a JOBLIB or STEPLIB DD statement or, in TSO, it must be specified on the CALL or TSOLIB command.
Besides LIBCLNTS, if you are exploiting Oracle's limited support for the COBOL DYNAM compile option in a Pro*COBOL application, module ORASTBX and all of its aliases must be available in JOBLIB, STEPLIB, TSOLIB, or the system linklist. This module is the loadable form of the Oracle API stub used only by COBOL DYNAM applications. Normally it is installed in the same location as LIBCLNTS.
In TSO environments only, an additional runtime module named ORASTAX is used by Oracle database applications to process TSO Attention or PA1 key interrupts. Like LIBCLNTS, ORASTAX normally resides in the Oracle CMDLOAD data set but can be placed in a linklist or LPA library.
For applications running in a POSIX environment, LIBCLNTS is provided as an HFS DLL (Dynamic Link Library) file, normally in the
lib subdirectory of Oracle home. Because of the way it is called (through the LE DLL mechanism), the LIBPATH environment variable determines the directories that are searched. LIBPATH is similar to PATH but pertains to DLL access rather than normal command access. When running an Oracle-accessing program in a POSIX environment, LIBPATH must include the directory that contains LIBCLNTS.
Besides executable code, the Oracle program interface uses a set of data objects containing character set translation tables, the text of displayable messages in various languages, and time zone configuration data. These are associated with Oracle's National Language Support (NLS) features and they are required, even if an application uses only the default language and character set.
For z/OS, these objects are distributed in two forms: as non-executable program objects residing in a partitioned data set (PDS) and as z/OS UNIX System Services HFS files. The program object form is used in all environments, including POSIX environments, if possible. If the program object form is not available in a POSIX application, Oracle accesses the HFS form of these files. (A non-POSIX application does not use the HFS form. If the program object form is not available, then the non-POSIX application fails during Oracle initialization.)
The program object forms of the data and message objects normally are installed in a data set referred to as the MESG data set. Like CMDLOAD, the exact name of this data set is chosen by the installation. Usually it has the same high-level qualifiers as the corresponding CMDLOAD. There are two ways to make the MESG data set available to an application, as follows:
Supply an ORA$LIB DD statement specifying the MESG data set, or ALLOCATE a comparable ORA$LIB DD to a TSO session. This is the recommended approach for applications that are not running in a z/OS UNIX shell.
Include the MESG data set in your JOBLIB or STEPLIB concatenation, or in your TSOLIB command in TSO.
It also is possible for an installation to make the MESG objects globally available by placing them in a linklist or LPA library, but this is not recommended.
Oracle tools and utilities and the Oracle program interface code use the following sequence to locate and access NLS data and messages:
If an ORA$LIB DD is present in the address space, it is searched for a matching program object.
If no ORA$LIB DD is present (or if the attempt to load from ORA$LIB fails), POSIX is ON, and the ORACLE_HOME environment variable is defined, Oracle attempts to read an HFS file in a subdirectory of ORACLE_HOME.
If neither of the previous steps occurred or succeeded, Oracle issues a z/OS LOAD request for the object. This LOAD follows the normal z/OS default search order for modules and program objects.
Because it can be awkward to include DD statements in POSIX applications, most such applications rely on the HFS form of these files (as describe previously, in step 2). Conversely, most batch and TSO applications rely on an ORA$LIB DD statement.
This section illustrates invoking a program that accesses the Oracle database and providing access to the required loadable components discussed previously. They are not complete examples of usage. All examples assume that LE is globally available through the linklist or LPA.
The following example shows part of the batch JCL used to invoke an Oracle Pro*COBOL application named ODBRA20. The application module resides in data set ODB1.PROD.LINKLIB (which is not a linklist library) and the Oracle program interface code also is not in the linklist or LPA, so the CMDLOAD data set also is included in STEPLIB. The CMDLOAD and MESG data sets have been installed with the prefix ORACLE.V10G:
//STEP07 EXEC PGM=ODBRA20 //STEPLIB DD DISP=SHR,DSN=ODB1.PROD.LINKLIB // DD DISP=SHR,DSN=ORACLE.V10G.CMDLOAD //ORA$LIB DD DISP=SHR,DSN=ORACLE.V10G.MESG
In the following example, a TSO session performs the necessary allocations to invoke Oracle SQL*Plus as a command processor. The installed data set conditions are the same as those in Example 1.
READY tsolib activate da('oracle.v10g.cmdload') READY alloc shr fi(ora$lib) da('oracle.v10g.mesg') READY sqlplus SQL*Plus: Release 10.0.1 - Production…
The following example is also SQL*Plus, but in the POSIX environment in a Telnet TTY session. The HFS part of the Oracle install created
/fs1/oracle/prod as the Oracle home directory. NLS data and message files from HFS are used.
$ export ORACLE_HOME=/fs1/oracle/prod $ export PATH=$ORACLE_HOME/bin:$PATH $ export LIBPATH=$ORACLE_HOME/lib:$LIBPATH $ sqlplus SQL*Plus: Release 10.0.1 - Production…
Oracle tools and utilities generally take command-style parameters (or arguments) that specify processing options, inputs, outputs, and so on. Depending on the tool or utility, parameters may be positional, identified by keyword, identified by UNIX-style option letters, or some combination of these. How parameters are specified depends on where and how the tool or utility is invoked: different conventions apply to batch (JCL), TSO, and a z/OS UNIX shell. This section describes those conventions generally, without going into the particulars of individual tools or utilities. For details on specific tools and utilities, refer to Chapter 4, "Oracle Tools and Utilities on z/OS".
As described in the following sections, parameters are specified in the JCL PARM field, the TSO command line, the "parm" string of a TSO CALL command, or the command line of a shell. Data that are not parameters may also appear in these places, including C standard file redirection operators, discussed in the section "Standard Files and Redirection", and a special notation indicating that parameter values be obtained from a file, discussed in the section "Parameters in Batch (JCL)". When these things appear in the PARM, command line, and so on, they are processed and removed before the Oracle tool or utility program code receives control and are not "seen" by the tool or utility.
When you run a tool or utility using JCL, parameters are supplied using the PARM keyword of the JCL EXEC statement. All Oracle tools and utilities are built with the NOEXECOPTS option, which means LE runtime options cannot be supplied in the PARM data, so everything in the PARM string except for LE redirection operators is seen by Oracle software. There are several different ways to code PARM data in JCL; the most common, used in our examples, is to enclose the data in single quotes (apostrophes). When a parameter value must include single quotes, code two single quotes together to signify one single quote in the value. Refer to the z/OS JCL Reference for details and variations of PARM syntax.
Some programs (such as SQL*Loader) have a large vocabulary of parameters including ones that specify data set or HFS file names. z/OS limits the PARM field to 100 total characters which can easily be exceeded by parameters you want to supply. To accommodate this, Oracle provides the ability to place parameters into a data set or HFS file. This is indicated by coding "++" (two plus signs) followed immediately by a filespec, with no intervening blanks, inside the PARM string. Filespecs and related details are covered in the section "File Types and Filespec Syntax".
The ++ operator can appear alone in the PARM string or it can appear before, after, or among normal parameters. Wherever it appears in relation to normal parameters is where Oracle logically inserts the parameter data from the specified file; this is significant when ++ is used to supply positional parameters. More than one ++ operator can appear in a single PARM.
The filespec following ++ can designate an existing Physical Sequential (PS) data set, a member of a partitioned data set, an instream (DD *) data set, or an HFS file. If an HFS file is used the filespec must use unambiguous HFS syntax, discussed in "File Types and Filespec Syntax", and the address space must be authorized for z/OS UNIX System Services. Tools and utilities in batch run with POSIX OFF, so ambiguous notation for the filespec is interpreted as a DD or data set name.
When ++ specifies a sequential data set or PDS member, the data set can have either fixed- or variable-length records and the logical record length (LRECL) can be anything up to 1028 (1024 data bytes) that will hold the longest single parameter. Parameters in the file must be separated by one or more blanks or by a record boundary (or a newline character in an HFS file). Parameter values are not quoted (any quotes are treated as part of the value) and they cannot contain blanks or span multiple records or lines. Sequence numbers or other non-blank non-parameter data must not appear in a parameter file. Also, LE redirection operators and the ++ operator itself cannot be specified in a parameter file.
The following example is part of a jobstep showing a typical parameter file setup with SQL*Plus, using an instream data set. In this case, all parameter values are being supplied in the file, so only the ++ operator appears in the PARM.
//PLUS EXEC PGM=SQLPLUS,PARM='++//DD:PARMS' //PARMS DD * -L scott/tiger@db1 @//DD:SQL /*
When SQL*Plus executes, it sees three parameters: L
, scott/tiger@db1, and @//DD:SQL.
The following example produces exactly the same behavior as Example 1, but the parameters are arranged differently:
//PLUS EXEC PGM=SQLPLUS,PARM='-L ++//DD:PARMS' //PARMS DD * scott/tiger@db1 @//DD:SQL /*
If an error occurs when opening or reading a parameter file, descriptive messages are displayed and tool or utility initialization fails.
Some Oracle utilities, such as Export and Import, have their own parameter file feature that is part of the generic Oracle Database product. This is distinct from the ++ operator, which works with all Oracle tools and utilities and is unique to z/OS.
In native TSO (not a TSO session that has entered a z/OS UNIX shell) there are two ways to invoke an Oracle tool or utility: as a true TSO Command Processor (CP) or through the TSO CALL command. Either can be used from plain TSO (the READY prompt), from an enhanced command interface such as ISPF or Session Manager, or from a CLIST or REXX procedure. For simplicity's sake, our examples here show the READY prompt.
When the CALL command is used, parameters are passed in a single-quoted string similar to the JCL PARM field and subject to the same 100-character limit. Coding considerations in this case (including use of the ++ operator) are the same as those discussed for batch jobs in the prior section.
The following example shows TSO CALL being used to run Oracle Export with a ++ operator for all parameters except the userid and password. The parameters are in member EXP1 of a PDS named
.MYORA.CNTL. The ++ operator specifies the data set name directly, instead of allocating a DD.
READY alloc file(ora$lib) da('oracle.v10g.mesg') shr READY call 'oracle.v10g.cmdload(exp)' 'scott/tiger ++//myora.cntl(exp1)' Export: Release 10.0.1 - Production…
To invoke a tool or utility as a TSO CP you must have the required program objects (generally, the CMDLOAD data set) specified in the logon procedure STEPLIB, in a linklist or LPA library, or in a TSOLIB command. In the CP case, parameters are specified after the command program name, separated by one or more blanks, for as long as necessary. If your parameters exceed the available terminal input area, end the line with a minus sign (-) or plus sign (+) character to indicate continuation, press ENTER, and resume typing parameters in the next provided input area. Refer to z/OS TSO/E documentation for full details on command line continuation.
Although it is less necessary (because there is no real parameter length limitation), the ++ operator can be used in TSO CP invocation as well.
The following example shows the use of TSOLIB to establish an Oracle CMDLOAD data set as a source for commands, followed by a call to Oracle Export (as a CP) with all parameters included on the command line. Although the normal name for Export is EXP, it has been installed with the name ORAEXP to avoid conflict with IBM's export command. TSO continuation is used, in this case in the middle of the FILE= parameter value.
READY alloc file(ora$lib) da('oracle.v10g.mesg') shr READY tsolib act da('oracle.v10g.cmdload') READY oraexp scott/tiger@db1 grants=n file=//'ORADB1.EXP1- .DATA' tables=(emp,dept) Export: Release 10.0.1 - Production…
In this case, the third parameter seen by Export is //'ORADB1.EXP1.DATA'.
In a z/OS UNIX shell, Oracle tools and utilities are invoked as commands at the shell prompt or from within a shell script. While some details of syntax and processing differ across the various UNIX shells, considerations are largely the same as those described for other Oracle UNIX platforms. Special attention is required when parameters contain characters that are subject to interpretation by the shell, such as $ (dollar), * (asterisk), and both single and double quotes. Refer to the documentation for the specific shell you are using to understand its particular conventions and requirements. For the IBM default shell,
/bin/sh, refer to z/OS UNIX System Services Command Reference, or type
man sh at the shell prompt to display the "man pages" for the shell.
The ++ operator described for batch and TSO is not available in z/OS UNIX shell environments.
In this example, Oracle Export is invoked at the shell prompt with the same parameters as the preceding TSO example. The shell escape character (backslash) is used on the single quotes in the file parameter to keep the shell from interpreting them.
$ exp scott/tiger@db1 grants=n file=//\'ORADB1.EXP1.DATA\' tables=(emp,dept)
Normally, tool and utility parameter values do not contain spaces but are separated by one or more spaces. There are, however, situations where a parameter containing spaces must be supplied, notably when using certain Oracle utilities and supplying the special logon identifier required for database control operations, which is / AS SYSDBA. To specify such a parameter using PARM or command line, enclose it in full (double) quotes. Depending on the environment, LE or the POSIX shell will remove the quotes and present the enclosed data as a single parameter to the tool or utility. In a batch SQL*Plus job, for example, this looks like the following:
//PLUS EXEC PGM=SQLPLUS,PARM='"/ AS SYSDBA"'
In a TSO command line setting it looks like the following:
READY sqlplus "/ as sysdba"
Parameters containing spaces cannot be supplied within a parameter file specified with "++".
Environment variables are simply named runtime entities with assigned character string values. Though they originated in the UNIX world they are also associated with C programming and were implemented in MVS C runtime services before MVS OpenEdition existed. Various Oracle components as well as z/OS components (particularly LE) use environment variables as parameters or to control internal processing options. You may need to specify certain environment variables when running Oracle tools or utilities or your own Oracle-accessing applications.
This section describes the mechanisms for specifying environment variables for Oracle software running in z/OS environments other than CICS TS and IMS TM. Refer to the Oracle Database System Administration Guide for IBM z/OS for information on environment variables in CICS TS and IMS TM transactions.
Information on specific environment variables, their names, usage, and allowed values is provided in other sections of this manual and in the generic Oracle product documentation. In addition, environment variables specific to Oracle Database for z/OS are listed in Appendix A.
The environment variable concept is indigenous to UNIX and to the shell environment. The default shell on z/OS provides various mechanisms for setting environment variables either explicitly or automatically on shell startup. When you run an Oracle tool, utility, or other application in z/OS UNIX shell you must ensure that required environment variables are set. Typically, the program or script runs in a new shell process that is a subshell of the one launching the application. In this case, environment variables that were set in the launching shell must be exported in order to be passed to the application shell. In the default IBM shell, the export command does this. Our example shows the setting and exporting of two environment variables prior to invoking SQL*Plus at the shell prompt:
$ ORACLE_SID=PDB1 $ export ORACLE_SID $ export LIBPATH=$ORACLE_HOME/lib:$LIBPATH $ export PATH=$ORACLE_HOME/bin:$PATH $ sqlplus scott/tiger SQL*Plus: Release 10.0.1 - Production…
For complete details on using environment variables in the default IBM shell, refer to the z/OS UNIX System Services Command Reference, or type man sh at the shell prompt to display the "man pages" for the shell.
It also is possible for your own C/C++ application programs running in a POSIX environment to set or change environment variables using calls to runtime functions such as
putenv(). This is discussed in the section "Setting Environment Variables in your Program".
When an Oracle tool, utility, or user-written application runs as a batch job or TSO command with LE POSIX OFF, several different mechanisms are available for specifying environment variables. More than one mechanism can be used in a single application and it is legal for the same environment variable to be specified in more than one place. The last setting of a given variable is the one that takes precedence. The following lists the available mechanisms in the order in which they are processed:
A file of settings specified by the LE environment variable _CEE_ENVFILE normally set using LE runtime option ENVAR (not available in Oracle tools and utilities)
A global default set of Oracle environment variable assignments in a specific z/OS data set or HFS file
Program calls to functions such as C/C++
putenv() during application execution (discussed in "Setting Environment Variables in your Program".
The first two mechanisms are provided by LE and are described in the IBM manual z/OS C/C++ Programming Guide.
The third and fourth mechanisms are provided by Oracle software and are available in Oracle tools and utilities as well as your own programs that access Oracle. The global environment file generally is set up by the system administrator, database administrator, or a person responsible for the Oracle product configuration on z/OS. It is meant to contain default environment variable assignments for all Oracle-accessing applications in a sysplex. The global environment file is optional and may not be present in your system; if it is, it is used automatically without action on your part. Check with your Oracle or z/OS system administrator to learn if the global environment file is configured on your system.
The local Oracle environment variable file, specified by the ORA$ENV DD statement, also is optional. Use it to supply environment variables specific to your job or application and to override (change) settings from the global file. The content and processing details for both the local and global files are described in the section "Oracle Environment Variable Files".
Processing for the Oracle-specific mechanisms (prior steps 3 and 4) occurs during program initialization in the case of Oracle tools and utilities. In user-written Oracle applications it occurs when the Oracle program interface code initializes, typically on the first call to an Oracle interface function. This in turn depends on application design and can be early or late in the life of the application program.
As mentioned earlier, both Oracle software and z/OS software (particularly LE) make use of environment variables. If your application requires setting of environment variables for LE or other IBM components, use one of the mechanisms provided by LE (prior steps 1 and 2). Do not use the Oracle-provided mechanisms to set IBM-specific environment variables because the setting may occur too late, after IBM software has queried the variable. This is particularly the case with variables that affect LE enclave initialization. For an obvious example, using the local ORA$ENV file to specify a value for _CEE_ENVFILE has no effect.
The converse-using LE mechanisms to supply Oracle-specific environment variables-is permitted. However, you might want to avoid LE's _CEE_ENVFILE mechanism for the reasons discussed at the end of the next section.
This discussion pertains to both the global and local environment variable file. These can be a Physical Sequential (DSORG=PS) data set, a member of a partitioned (DSORG=PO) data set, or an HFS file in the POSIX file system. The local file, specified by an ORA$ENV DD statement, can also be an instream (DD *) data set and can concatenate multiple data sets with compatible DCB attributes. When a sequential data set or PDS member is used, the data set can have either fixed- or variable-length records (RECFM of F, FB, FBS, V, or VB) and the logical record length (LRECL) can be anything up to 1028 (1024 data bytes). Choose an LRECL that will hold the longest required variable assignment statement you need.
In the environment file, each record (in a data set) or each line (in an HFS file) is either a comment or a variable assignment statement. Lines or records whose first nonblank character is # (pound), * (asterisk), or / (forward slash) are treated as a comment and are ignored. Records or lines that are entirely blank also are ignored. Otherwise, a record or line must contain a single assignment statement of the form
name = value
name is the environment variable name (case-sensitive), "=" is the equals sign as shown, and
value is as discussed in the following section. Blanks can precede and follow both the name and the value and are ignored. No other nonblank data can appear between the value and the end of the record or line. The entire statement must fit on one record or line: spanning or continuation is not permitted.
The value part is optional. If none is specified, the environment variable has an empty string as its value. Otherwise, the value is specified as an unquoted or quoted string. If it is not quoted, it starts at the first nonblank character after the "=" and ends at the next blank or at the end of the record or line, whichever comes first. Either apostrophes or full quotes can surround a value to allow it to include blanks. In this case, the value begins with the character following the opening apostrophe or quote and ends at the matching (closing) apostrophe or quote, which is required and must be the same kind as the opening character. If a quote of the same kind is to be included as part of the value, place two quotes together. An imbedded quote of the other kind is not doubled.
Unlike in a shell, assignment statements in an environment variable file cannot dereference another environment variable. For example, given file statements like
That = something This = stuff:$That
the value of environment variable
This is the string
The following illustrates a local (ORA$ENV) file specified as an instream data set in a batch job. The variables and values are not realistic but were chosen to illustrate syntax variations.
//ORA$ENV DD * *** * Sample Oracle environment variable file *** This_File='//''ORA.SOME.DATA.SET''' VAR1 = some_thing_1 VAR2 = "Don't go there." VAR3 = /*
As mentioned earlier, both the global and local environment variable files are optional. If the attempt to open either file fails with an error such as "File not found" or "DD statement not found", the error condition is ignored and processing proceeds normally. Other errors-including security rejects on file open, I/O errors reading the file, and syntax errors in the file contents-are reported through error messages. In this situation Oracle tool or utility initialization fails. In user-written applications, a user ABEND is issued by the Oracle interface stub.
There are significant differences between Oracle's environment variable file features and LE's _CEE_ENVFILE. The syntax requirements for the LE file are both simpler and more restrictive (and make fixed-length record formats all but unusable). By default, no error messages are displayed for errors that arise during LE environment file processing. This can make it difficult to detect problems related to environment variables. For non-POSIX applications, Oracle recommends using the Oracle-provided mechanisms to specify Oracle-specific environment variables.
If you are writing Oracle-accessing applications using IBM C/C++ (either Pro*C or OCI applications) you have access to functions like
setenv() and to the
environ pointer to set or change the values of environment variables.
In general, Oracle discourages programmatic manipulation of Oracle-specific environment variables. The exact "when" (and how often) Oracle software retrieves a given variable's value is an internal behavior and is not necessarily constant over even minor maintenance changes. An application that succeeds with this technique today might not work in a different version, release, or maintenance level of Oracle software.
cAll Oracle tools and utilities, the Oracle database server, and in some cases the Oracle program interface code require access to data on disk or, sometimes, tape. z/OS presents challenges in this area due to the variety of distinct file types and the associated software interfaces (Access Methods or APIs). To meet the needs of z/OS users across the various execution environments, Oracle tools, utilities, and program interface software must be able to process POSIX HFS files as well as sequential, partitioned, JES spool, and in some cases VSAM data sets. As a user of these components you must understand how files are specified (when you supply file information to a component) and how the software processes that information.
IBM C/C++ and LE provide most of the underlying file processing for end-user-accessible Oracle features. It is helpful to understand how LE processes the various types of files and data sets in z/OS. The z/OS C/C++ Programming Guide and z/OS C/C++ Run-Time Library Reference are the definitive sources of information on LE file processing. Some details on LE processing or behavior are provided here as a convenience, but the IBM manuals are the definitive source of information.
Central to an understanding of file processing is the notion of a filespec, which is our term for a character string that wholly or partially identifies a file. You will supply filespecs to Oracle components in parameters, commands, and possibly in SQL, PL/SQL, or server Java statements. On z/OS, a filespec can specify a data set or DD name, an HFS path and file name, a SYSOUT (spool) data set, or the terminal (in TSO or a z/OS UNIX shell). Which of these a given filespec means depends on the syntax of the filespec and on the POSIX indicator. The latter consideration is significant: as you will see shortly, a filespec like
myexport.dat can mean a data set in one execution environment and an HFS file in another.
Oracle generally uses the syntax defined by IBM C/C++ and LE for filespecs. In some areas, notably SYSOUT support, Oracle augments LE filespec syntax to provide useful capabilities not provided by LE. Optionally, Oracle also supports a subset of the filespec syntax used by the Oracle C runtime library so that existing customer JCL, scripts, and procedures that were developed for Oracle C runtime continue to work without changes. The Oracle C runtime syntax overlaps valid LE syntax and so is not recommended for new customers and new applications. Details on this compatibility feature are in the section"Oracle C Runtime Compatibility".
As suggested earlier, the filespecs you supply to Oracle functions are not always complete. This applies to filespecs that designate a data set name or an HFS file name. In some components, these names are subject to extension, which means adding a suffix string to the name. Usually the suffix indicates the type or usage of the data in the file, such as .
sql or .SQL for a file containing SQL statement text. The extension mechanics for HFS file names and data set names differ; in the case of data sets, the extension mechanism also can be used to associate attributes (space and DCB attributes) with a data set that is being created.
Other types of file name augmentation or manipulation also occur. LE adds the PROFILE PREFIX (in TSO) or the z/OS userid (in other environments) to the beginning of any filespec data set name that is not enclosed in apostrophes. Certain Oracle components construct filespecs by combining separate "directory" and "name" pieces. Oracle utilities, particularly SQL*Loader, may derive one filespec from another by removing one suffix extension and adding a different extension. A z/OS-specific Oracle feature called FNA can be used to map simple file names (as seen by Oracle) to member names in a z/OS partitioned data set. These topics are covered in the sections that follow.
Before we describe the syntax and interpretation of different types of filespecs we have to establish some more terminology. Most filespecs and types are usable in all of the client environments: batch, TSO, and z/OS UNIX shell. CICS TS and IMS TM are discussed separately in Chapter 4, "Oracle Tools and Utilities on z/OS". A few types are not usable in obvious circumstances: you can't specify a "TSO terminal" filespec for an input file in a non-TSO address space. More important, some filespecs are interpreted differently depending on the POSIX indicator; with POSIX ON they refer to data sets and with POSIX OFF they refer to HFS files. We call these ambiguous filespecs.
Ambiguous filespecs are perfectly legal and acceptable to use except where the POSIX-determined behavior is not what you want. If you want to refer to a data set in a POSIX ON application or to an HFS file in a POSIX OFF application, you must use an unambiguous filespec, one which is self-identifying as to type. C/C++ and LE use specific syntax elements to make a filespec unambiguous. If a filespec begins with exactly two forward slashes (the third character is not a forward slash), it is taken as a non-HFS filespec regardless of POSIX. If it does not begin with exactly two slashes but it contains one or more slashes (anywhere in the filespec), it is taken as an HFS filespec regardless of POSIX. If neither case applies, the filespec is ambiguous. There are some subtle details in this scheme when DD name filespecs are used. Refer to the section "DD Names".
The treatment of ambiguous filespecs sometimes counters intuition. The criteria described previously mean
'JSMITH.TEST.SQL(CASE1)' is an ambiguous filespec. The fact that it looks very much like a z/OS partitioned data set and member name does not matter. If this filespec is used for output in a POSIX ON setting, an HFS file with a peculiar 24-character name-including the apostrophes-is created. One of the interesting attributes of the POSIX HFS is that virtually anything but a forward slash is legal within a file name, including blanks, punctuation, and even non-printing characters. When POSIX is ON, an ambiguous filespec is treated as HFS no matter how data-set-like it appears.
The converse treatment is equally impartial. You might use the filespec
=Silly_QA_Tests=.sql in a command in a batch (POSIX OFF) SQL*Plus job expecting the software to recognize that the filespec is valid only as an HFS file name, and treat it as such. Instead, you will get an error reporting an invalid (data set) file name.
dsname is the 1-character to 44-character fully-qualified data set name and
member is a 1-character to 8-character member name for a partitioned (DSORG=PO) data set or a numeric Generation Data Group (GDG) index (possibly beginning with + or -).
The pair of forward slashes signify that what follows is not an HFS file name. They are required in order to access a data set in a POSIX ON environment. When POSIX is OFF they can be omitted.
The apostrophes (single quotes) indicate that dsname is a complete data set name not subject to LE prefixing. If you omit the apostrophes, LE prefixes dsname with the PROFILE PREFIX (in TSO) or with the z/OS userid (in all other environments). (If you have enabled Oracle C runtime compatibility, prefixing occurs only in TSO.) If a TSO session has PROFILE NOPREFIX set, no prefix is added. Apostrophes also affect Oracle's tendency to add a suffix extension to a data set name; this is discussed later in the section "File Name Manipulation".
member portions of the filespec are case-insensitive: lower case letters are converted to upper case. To be usable, a data set name must ultimately have two or more name segments or qualifiers. The name in the filespec can be a single qualifier as long as prefixing and/or suffix extension applies to supply a second qualifier. If apostrophes are used to prevent prefixing (or if PROFILE NOPREFIX is set in TSO), the name in the filespec normally must have two or more qualifiers.
A data set referenced in this fashion can be physical sequential (DSORG=PS), partitioned (DSORG=PO), or VSAM (ESDS, KSDS, or RRDS). Use of VSAM is limited to certain Oracle components or features discussed in later chapters. If the filespec is being used for output purposes and the data set does not exist, it is created through z/OS dynamic allocation as a non-VSAM (PS or PO) data set. (Creation of VSAM data sets is not supported.) Dynamic creation relies on installation default mechanisms to determine SMS classes (or unit and volume) as well as disk space allocation. These may or may not be appropriate for your application and you may want to consider preallocating such data sets and/or using a DD filespec, discussed later. Space allocation for some types of files can also be influenced using FNA, described later.
For an input file it is legal to specify a partitioned data set name with no member name. Doing so, however, accesses the directory data of the PDS rather than any member. There currently are no Oracle components that exploit this capability.
The following are examples of valid data set name filespecs.
//'JSMITH.ORAEXP.TEST.DAT' prod.sql(case1) 'ODB1.init.ora' //discard1 //SAMPLE.LOG
In the prior set of examples, the first, fourth, and fifth are unambiguous.
name is the 1-character to 8-character DD name and member is a 1- to 8-character member name when the DD statement or allocation is a partitioned (DSORG=PO) data set.
The pair of forward slashes signify that what follows is not an HFS file name. When POSIX is OFF they can be omitted. If they are omitted when POSIX is ON, LE does something surprising: it checks to see if the specified DD name is allocated in the job or address space. If it is, the DD is opened. If it is not, an HFS file named DD:
name or DD:
name(member) is opened. This is one case where the interpretation of an ambiguous filespec depends on more than just POSIX.
The DD: portion of the filespec is required to indicate that what follows is a DD name. It is case-insensitive and can use any of the 4 possible combinations of upper case and lower case "D." The
member parts are also case-insensitive and are converted to upper case.
The DD statement or TSO allocation specified by this filespec can be any of the following:
Physical sequential (DSORG=PS) or partitioned (DSORG=PO) data set
VSAM KSDS, ESDS, or RRDS cluster
Instream data for input usage (DD *) or SYSOUT for output usage
Dummy (DD DUMMY)
TSO terminal (DD TERM=TS or TSO ALLOCATE DA(*))
HFS file (DD PATH=)
If the file is being used as input, the DD can be a concatenation of multiple data sets of compatible type and DCB attributes.
When a partitioned data set is used, either the filespec or the DD statement (but not both) can include the parenthesized member name. If neither specifies a member name, the PDS directory data is accessed rather than any member; this is allowed only with input usage.
Files specified as DD name filespecs have some specific behaviors in Oracle software. Name manipulation operations such as extension have no effect on a DD filespec nor can such a filespec be parsed or divided into logical pieces. This affects the way some Oracle components work when using DD filespecs. This is covered in more detail in "File Name Manipulation" and in the later chapters dealing with specific Oracle components.
The following are examples of DD name filespecs:
//dd:mysql DD:LIB1(sample) dD:x //DD:REPORT
In the prior set of examples, the second and third are ambiguous; when POSIX is ON, they are subject to the processing discussed earlier.
Oracle provides a logical extension of LE file syntax for direct specification of SYSOUT data sets for output. This is usable in most places where Oracle requires an output file specification but it is associated primarily with text (message or report) files. The filespec syntax is
class is the 1-character SYSOUT class, form is a 1-character to 4-character form name, and
dest is a 1-character to 8-character JES destination identifier.
The pair of forward slashes signify that what follows is not an HFS file name. They are required in order to use a SYSOUT filespec in a POSIX ON environment. When POSIX is OFF they can be omitted.
SYSOUT: portion of the filespec is required to indicate that what follows is a SYSOUT specification. It is case-insensitive and can use any combination of upper- and lower-case letters. It also can be abbreviated to S: or s:.
class is a valid JES SYSOUT class (letter or digit), or an * (asterisk) signifying that the job's MSGCLASS be used. If the class is omitted it defaults to *. If you omit the class but want to supply a form or destination, code a single comma.
form is a valid JES form name. The default, when form is omitted, is installation-dependent. If you omit the form name but want to supply a destination, code a single comma.
dest is a valid JES destination identifier. Legal destination values and the default depend on whether your z/OS system uses JES2 or JES3.
Check with your z/OS system administrator for specific information on output classes, form names, and destinations used in your installation.
Like DDs, SYSOUT filespecs are immune to file name manipulation operations such as extension and parsing. Here are some examples of SYSOUT filespecs:
//SYSOUT:G,,JSMITH s: sysout:*,STD //S:,,HQPRT1
The second and third examples are ambiguous and would result in oddly-named HFS files in a POSIX ON application.
The forward slashes signify that what follows is not an HFS file name and the single asterisk is required to indicate the TSO terminal. The forward slashes can be omitted when POSIX is OFF.
Optionally, you can follow the asterisk in this filespec with either a data set name (with or without surrounding apostrophes) or a DD name specification beginning with DD:. When such a filespec is opened in a non-TSO address space, it is processed as though the asterisk was not there-the indicated data set or DD name is opened. This allows you to code a single filespec that uses the TSO terminal under TSO and a data set in other environments. You cannot specify an HFS file name after the asterisk, but a DD name specification can refer to an HFS file (DD PATH=).
If the TSO terminal is specified for an output file in a non-TSO address space and no data set or DD name follows the asterisk, LE allocates a SYSOUT data set with default class, form name, and destination. For an input file, this situation results in an error.
Unless it includes a data set name as just described, TSO terminal filespecs are immune to name extension and other name manipulation operations. Manipulating the data set name included on a TSO terminal filespec may or may not be meaningful depending on the usage and environment.
When an input file is specified as the TSO terminal, the keyboard is unlocked to accept user input. Whatever is typed up to the point of pressing the ENTER key is presented to the software as a single logical record. To signal the end of input (EOF), type /* (forward slash and asterisk) alone as input and press ENTER.
TSO terminal support in LE uses the TGET and TPUT services to read and write at the terminal. Using TGET for input means that the terminal is always accessed; so-called stacked input (the TSO input stack) is not processed by TGET. Applications cannot place data on the input stack (for example, using REXX "queue") and have it read by an Oracle component through a TSO terminal filespec. Using TPUT for output means that the terminal is always the destination. This means features like REXX OUTTRAP cannot be used.
The following are examples of TSO terminal filespecs:
//* *dd:print * //*'JSMITH.ORA1.CNTL(SQL1)'
The syntax for HFS filespecs is that which is typical of UNIX systems. A complete file specification, or path, begins with a forward slash (signifying the root directory). This is followed by zero or more directory names, each ended with a forward slash, and finally the file name. The sequence of directory names represents navigation through the logical hierarchy represented by the directories. A single period is interpreted as the current directory in the navigation and a pair of periods refers to the parent (previous) directory. Besides directories and files, the HFS supports links, which are essentially aliases or alternative names for directories and files.
When an HFS filespec begins with a forward slash it is said to be absolute, meaning the entire navigation through the HFS is specified. If it does not begin with a slash it is taken as being relative to the current working directory, which is an attribute of the running process. Typically, when you are in a z/OS UNIX shell, the current working directory starts out set to your userid's home directory. You can change the current working directory with the cd shell command and other mechanisms.
File names in the HFS are essentially unconstrained in content; while there are conventions for naming files there are few system-imposed rules. Names are case-sensitive, can contain almost any characters (including non-printing characters), and can be quite long: the total length of all slashes, directory names, and finally the file name in a z/OS HFS filespec can be up to 1023 characters. Here are some examples of valid HFS filespecs:
/u/jsmith/test.sql ../oradev/c/rover/rover1.c @-@-@ Read_Me_And_Weep @-@-@ SYS1.PROCLIB(ASMHCL)
From a UNIX perspective, the first two are fairly conventional while the latter two are somewhat unusual but still legal. As the last example shows, valid HFS name syntax is a superset of valid z/OS data set name syntax.
For complete information on z/OS HFS files, refer to the z/OS UNIX System Services User's Guide and related IBM publications.
In a POSIX ON application, any filespec that does not begin with exactly two forward slashes is interpreted as an HFS filespec. There is one exception in the case of DD filespecs, described in the section "DD Names" .
When POSIX is OFF, a filespec must contain at least one forward slash (and not begin with exactly two slashes) in order to be recognized as HFS. In this situation, if you want to refer to a file relative to the current working directory (where no directory names and slashes are needed), you must include some unnecessary but benign syntax:
This is a reference to the file
test.sql in the current directory, signified by "./". The "./" part isn't really needed to get to the file but it gets a slash into the filespec.
Besides regular files, HFS structure and syntax is used for various special files in z/OS UNIX System Services. Many of these appear under HFS directory
/dev, which provides an HFS structure for special devices used as files. Two of these that are often used by shell-based applications are
/dev/tty, which indicates the terminal associated with the current process, and
/dev/null, which indicates a null or empty file (similar to z/OS DD DUMMY).
C language applications, including Oracle tools and utilities, are provided with three pre-opened files by the runtime environment. (These are called standard streams in IBM terminology.) One is an input file (standard input) and the other two are outputs (standard output, usually used for normal output, and standard error, usually reserved for error messages and supporting data). Most Oracle tools and utilities get their primary input (such as control statements) by reading from standard input and display their normal output (such as status messages and listings) by writing to standard output.
What is actually opened as standard files depends on the environment. In a z/OS UNIX shell, the standard files are controlled by the shell; they normally are assigned to the terminal associated with the process but they might be changed using shell mechanisms such as redirection (which specifies a different filespec for a standard file) or piping (where the standard output of one command is treated as the standard input to another). For details on standard files in shell sessions refer to the z/OS UNIX System Services User's Guide and to the documentation (such as "man pages") for the particular shell you are using.
When not in a shell, the standard files normally default to the terminal (in TSO) or to certain DD names (if present) or to SYSOUT (if not, in the case of standard output and standard error). Oracle tools and utilities deviate from normal LE processing in this area. This is done mainly to be compatible with past (Oracle C runtime) behavior, but it cannot be disabled with an environment variable like other Oracle C runtime compatibility features because the processing occurs before environment variables can be queried.
Redirection, meaning respecification of standard files to something besides the default, is also available in TSO and batch using command line or PARM syntax similar to that in shells. When redirection operators are included in the command line or PARM field they are processed during LE initialization and are not "seen" by the Oracle tool or utility. Redirection conventions and syntax are described in "Redirection Operators in TSO and Batch".
When you do not redirect standard files for an Oracle tool or utility running in TSO or batch (which is usually the case), the default behavior differs slightly between the two environments. In TSO, the default behavior is as follows:
Standard input defaults to the TSO terminal unless a SYSIN allocation (DD) is present, in which case SYSIN is read.
If both SYSOUT and SYSERR allocations (DDs) are present, standard output and standard error are written to SYSOUT and SYSERR respectively; otherwise, both are written to the TSO terminal.
In a batch job, when the standard files are not redirected, the following defaults are used only if all 3 of the DD names SYSIN, SYSOUT, and SYSERR, are present:
Standard input defaults to the SYSIN DD.
Standard output defaults to the SYSOUT DD.
Standard error defaults to the SYSERR DD.
This behavior mimics Oracle C runtime, which required all three of the standard file DDs to be provided in order to initialize successfully. If any of these three DD names is not included in the JCL, the job uses the normal IBM C/C++ defaults instead, as follows:
Standard input reads the SYSIN DD if provided, otherwise standard input is treated as empty (like DD DUMMY).
Standard output goes to DD SYSPRINT if provided, or to SYSTERM if provided and SYSPRINT is not, or to SYSERR if provided and neither SYSPRINT nor SYSTERM is provided. If none of these DDs is provided, standard output is dynamically allocated to the default spool output class and form.
Standard error goes to the LE message file (normally the SYSOUT DD) if it is provided, otherwise it is dynamically allocated to the default spool output class and form.
Be aware that there is a logical conflict between Oracle C runtime compatibility and IBM C/C++ normal processing in certain situations. For example, if a batch job supplies SYSIN, SYSERR, and SYSOUT DDs intending them to be used as standard input, output, and error respectively (per the C/C++ defaults just described), the job will assume Oracle C runtime compatibility is intended and will reverse the roles of SYSERR and SYSOUT to be standard error and standard output.
Typically, when setting up JCL to run an Oracle tool or utility in batch, you will supply a SYSIN DD statement for whatever data the particular tool or utility expects as its primary input. The exact form or syntax of that data depends on the particular tool or utility. Some components, such as SQL*Loader, do not necessarily use standard input, in which case the SYSIN DD can be omitted. For the output files, if the fallback SYSOUT dynamic allocation is acceptable, you need not supply the associated DDs. You will need to supply them if you want to have a different SYSOUT class or other characteristics, or if you want to direct the output to something other than SYSOUT, such as a disk data set.
You can modify the defaults for standard files using an LE redirection operator or one of the Oracle C runtime redirection operators for which backward compatibility is provided. Redirection is coded on the command line or in the PARM field but it is not processed by the Oracle tool or utility and does not affect tool or utility parameters. You cannot place a redirection operator in a parameter file specified with "++".
Redirection syntax consists of an operator (which can be one or several characters long) followed by a filespec with no intervening spaces. There also are special redirection operators to indicate that standard output and standard error are written to the same file. Complete details on redirection operators are in IBM's z/OS C/C++ Programming Guide. The operators most commonly used are as follows:
"<" for standard input redirection
" >" for standard output redirection
"2>" for standard error redirection;
"?" is also allowed for Oracle C runtime backward compatibility
The filespec that follows a redirection operator can be a data set name, DD name, TSO terminal, or HFS type. Depending on POSIX, you may need to use unambiguous filespec syntax to ensure that the correct type of file is accessed. Redirection cannot use the SYSOUT filespec type described earlier because SYSOUT filespecs are an Oracle extension that LE does not support directly.
When you use redirection, the filespec you supply must be capable of being opened in the correct mode (input or output) at tool or utility initialization time; there is no fallback to alternate DD names or to dynamic allocation like there is for default standard files. If the filespec for a redirection can't be opened, LE initialization issues error messages followed by a user ABEND.
The filespec following a redirection operator is permitted to use certain Oracle C runtime syntax for backward compatibility. Specifically, the prefixes /DD/, /ODD/, /DSN/, and /ODSN/ are accepted and converted internally to LE equivalents before the file is opened. This backward compatibility cannot be disabled. Be aware that this makes it impossible to use redirection with an HFS file whose directory path begins with /DD/, /ODD/, /DSN/, or /ODSN/ in any mix of letter case.
The following example shows a portion of a SQL*Plus jobstep that includes redirection of standard output. It also supplies the parameter
/nolog to SQL*Plus followed by other parameters that are in a parameter file which is a member of a PDS.
//PLUS EXEC PGM=SQLPLUS, // PARM='>''JSMITH.PLUSTEST.OUT'' /nolog ++dd:moreparm' //STEPLIB DD DISP=SHR,DSN=ORACLE.V10G.CMDLOAD //ORA$LIB DD DISP=SHR,DSN=ORACLE.V10G.MESG //MOREPARM DD DISP=SHR,DSN=JSMITH.ORA.PARMS(PLUS1) //SYSIN DD …
Because this is a batch job execution of SQL*Plus, POSIX will be OFF and the ambiguous filespec 'JSMITH.PLUSTEST.OUT' will be treated as a data set name. JCL PARM syntax conventions require that the surrounding apostrophes be doubled so that LE sees single apostrophes in the filespec.
Filespecs that you supply to Oracle may be subject to various kinds of manipulation or augmentation before they are actually opened for I/O operations. You need to understand this behavior in order to know what to code for a filespec in a given application. Some behaviors are common across all Oracle components and others are specific to particular components. This section describes in general the different ways filespecs are processed; refer to later chapters for details on specific components, tools, or utilities.
Most kinds of manipulation or augmentation pertain to filespecs that designate either a data set name or an HFS file name. DD, SYSOUT, and TSO terminal filespecs without an included data set name are mostly immune to the processing described here.
Oracle views both data set names and HFS file names as being composed of several distinct logical parts: a directory (sometimes called a path or location), a base name, and an extension. Some components accept separate directory and base name/extension strings and combine them prior to use. Others may parse or decompose a filespec you supply into these pieces and then use the pieces to construct new filespecs. In the simplest case, components often add or replace the extension part. How these operations work differs between data sets and HFS files.
The leftmost (high-level) qualifier of a data set name is taken as the directory. If a filespec data set name is not surrounded with apostrophes ( it is subject to prefixing with the TSO PROFILE PREFIX or the z/OS userid), the directory is an empty string signifying that a directory is supplied by LE. If the filespec includes "//" or surrounding apostrophes, the "//" and"/"or a single apostrophe are included with the directory.
If the data set name contains three or more qualifiers (two or more, when prefixing applies), the rightmost qualifier is taken as the extension. Otherwise, the extension is an empty string signifying "no extension."
Everything that remains after the directory and extension are subtracted is considered the base name. When a data set filespec includes a member name or GDG index in parentheses, the parenthesized part is retained in the base name. If the original filespec included a "//" prefix, the base name also has a "//" prefix.
The example shows how various data set name filespecs are decomposed into logical parts. From left to right, the four parts are: filespec, directory, base name, and extension. Assuming POSIX is OFF, ambiguous filespecs are treated as data sets.
//'JSMITH.TEST.SQL' //'JSMITH //TEST SQL loader.ctl(demo3) (empty) loader(demo3) ctl //*'ORADB1.PAY.LST ' //'ORADB1 //*PAY LST mydata (empty) mydata (empty) arproj.case.live.data (empty) arproj.case.live data
When Oracle composes a data set name filespec from separate parts, slightly different content rules apply. A directory part that you supply can contain more than one data set name qualifier, it can include an ending period, and it need not have the //' prefix. If what Oracle uses as the base name part includes apostrophes, neither the directory nor the extension part are added-such names are immune to alteration. The following list shows examples of various name pieces and how they are combined by Oracle. From left to right, the four parts are: directory, base name, extension, and result filespec.
//'JSMITH //TEST SQL //'JSMITH.TEST.SQL' 'ARD07N. lib.oracle(bb3) CTL 'ARD07N.lib.oracle.ctl(bb3)' (empty) 'PROD.ORA3.OUT' lst 'PROD.ORA3.OUT'
Everything up to the rightmost forward slash is taken as the directory. The directory can be absolute (begins with a forward slash) or relative (begins with a subdirectory name, a single period, or two periods). If the filespec contains no slashes, the directory is an empty string which means the current working directory.
Everything to the right of the rightmost period in the remaining text is taken as the extension. If there are no periods or the text ends with a period, the extension is an empty string.
Whatever remains after the directory and extension are subtracted is the base name. It is possible (though unusual) for the base name to be an empty string.
Composing a filespec from these parts essentially concatenates them in order: directory, base name, and extension. An intervening slash is added between the directory and the base name if needed, and a period is added between the base name and the extension if needed.
Most Oracle tools and utilities perform extension on filespecs before they are used. Extension associates a logical data type identifier with the filespec, such as "sql," for a file containing text SQL and PL/SQL statements. The extension identifiers come from Oracle software and usually (though not always) are three characters or less. In the case of filespecs that specify a data set or HFS file name, the extension operation may modify the name by inserting or appending the extension identifier text. The specific extensions used and processing done by each tool or utility is covered in later chapters of this manual and in the generic documentation. Here we cover the general behavior of the extension mechanism.
On z/OS, extension can also be used to completely transform the syntax of a filespec, simplifying the use of partitioned data sets with some components, and to associate disk space and DCB attributes with data sets being used for output. These z/OS-specific capabilities are described in the section "FNA".
Extension applied to filespecs other than data set or HFS file names, such as DD, SYSOUT, and TSO terminal filespecs without an included data set name, does nothing to change the filespec.
With data set name filespecs, an extension is incorporated into the data set name if the name is not enclosed in apostrophes. The rationale for this is the same as that of LE, which avoids adding a userid or PROFILE PREFIX to data set names enclosed in apostrophes. The extension mechanism adds the extension suffix to the right-hand end of the data set name (with an intervening period) regardless of the number of data set name segments already present. If a parenthesized member name or GDG index are present, they are preserved in the modified name. The following are examples of extension processing on various data set filespecs. From left to right, the three parts are: filespec, extension, and result.
//sample3 sql //sample3.sql 'JSMITH.LOADER.CTL log 'JSMITH.LOADER.CTL' payroll(rcn41c) lst payroll.lst(rcn41c) temp.acct.sql sql temp.acct.sql.sql
With HFS filespecs, the extension mechanism replaces a file name extension if one is already present; otherwise, the extension is added to the name with an intervening period. This differs from data set name processing and reflects the convention that most HFS file names do not have more than two segments separated by periods. the following are examples of the HFS filespec extension. From left to right, the three parts are: filespec, extension, and result:
sample3 sql sample3.sql ./proj9/admin/load1 ctl ./proj9/admin/load1.ctl /u/jsmith/test.c lst /u/jsmith/test.lst
On z/OS, the extension mechanism can be used to do more complex processing for data sets than just the addition of a name suffix. The facility that does this is called FNA (for File Name Augmentation. Using FNA allows you to do two things to a filespec associated with a given extension:
Transform the filespec into different syntax before it is used. This is used primarily to cause certain Oracle components to treat simple 1-segment file names as PDS member names.
Associate disk space and/or DCB attributes with a filespec that will be opened for output processing.
These two actions are independent of each other; when you use FNA, you can cause either or both of them to be applied to a given type of file; in other words, to a given extension.
To use FNA, you must supply an FNA control file using an ORA$FNA DD statement in your job or TSO session. The DD can specify a sequential data set, a member of a PDS, or an HFS file. When you use a sequential or partitioned data set (which is usual) either fixed-length or variable-length record formats of any legal LRECL are permitted. If no ORA$FNA DD is supplied, extension processing for data sets is simply that described in the previous section.
In the ORA$FNA data set, member, or HFS file you supply one or more keyword statements that configure FNA. Each statement supplies FNA information for a single extension. The general form of the statement follows, where
ext is an extension identifier,
newname is a name transformation specification, and
attrs is attribute specification data for output file usage:
FSA( FTYPE(ext) FNAME(newname) FATTR(attrs) )
The FSA, FTYPE, and at least one of FNAME or FATTR are required. Spaces are permitted before and after keywords, parentheses, and enclosed values. One FSA entry can span multiple records or lines as long as the break is not within a value. Comments are permitted, begin with "/*" and end with "*/" and can span multiple records or lines. Completely blank lines are ignored. Extraneous data (such as record sequence numbers) must not be included.
The FTYPE value
ext is a 1-character to 8-character alphanumeric file extension identifier without a leading period. This indicates the specific extension to which the entry applies and should match an extension used by some Oracle component. Since FNA applies only to data sets (not HFS files) the extension is case-insensitive and can be given in upper- or lower-case letters. Only one FSA statement for a given FTYPE extension should appear in the ORA$FNA file; duplicate entries for an extension produce a warning and are ignored.
The FNA keyword parameter FNAME value
newname specifies a syntax transformation of the input filespec. It usually is specified as a character string enclosed in apostrophes or quotes. If you use apostrophes and want an apostrophe to appear in the value, code two apostrophes in succession. The transformed filespec is produced by copying this character string and replacing certain characters with new values:
A "+" (plus sign) is replaced with all or part of the original input filespec text. If the + appears inside parentheses in the newname string and the input filespec contains a period, only the part up to the first period is used. Otherwise, the entire input filespec is substituted.
An "*" (asterisk) is replaced with the TSO PROFILE PREFIX (in TSO) or with the z/OS userid (in other than TSO). If PROFILE NOPREFIX is set in TSO, then * is replaced with an empty string.
After the string substitution is done, if the result is a data set name specification without surrounding apostrophes, the original extension suffix is added at the end of the data set name in the same fashion as normal extension processing described earlier. If the result is a DD or SYSOUT filespec, or a data set name surrounded with apostrophes, the original extension is discarded.
The primary use of the name transformation mechanism is to allow simple file names used by certain Oracle components to be treated as member names in a partitioned data set. This kind of transformation is done using FNA entries like
FSA( FTYPE(sql) FNAME('//DD:SQLLIB(+)') )
FSA( FTYPE(CTL) FNAME('''oradb1.prod.cntl(+)''') )
The transformation is truly mechanical as described previously, however, and can be used in other ways to impose name structure. The following examples show how the transformation applies to various combinations of input filespec and FNAME string. From left to right, the four parts are: input filespec, FNA FNAME, and result filespec.
catalog //DD:SQLLIB(+) //DD:SQLLIB(catalog) temp.ora '*.ORAPROD.LIB(+)' 'prefix.ORAPROD.LIB(temp)' ldr1 ORACLE(+) ORACLE.ctl(ldr1) drc10a.c 'JSMITH.ORA.+ 'JSMITH.ORA.drc10a.c'
The third example in the prior list assumes that extension
.ctl is involved.
The filespecs produced by FNAME transformation can use Oracle C runtime syntax if Oracle C runtime compatibility is enabled. Refer to the section "Oracle C Runtime Compatibility" for more information.
The FNA keyword parameter FATTR is used to associate an attribute string with files having a particular extension. It is pertinent only when the associated file is used for output and has no effect on input usage. The attributes that can be specified include disk space quantities and DCB characteristics (record format, logical record length, and block size). The disk space attribute pertains only to data set name filespecs for data sets that do not already exist (will be created when opened). DCB characteristics are meaningful for all output data set situations including data set name, DD:, SYSOUT:, and TSO terminal filespecs.
The FATTR attrs string normally is enclosed in apostrophes or quotes. It must begin with a semicolon (;) followed by one or more keyword assignments separated by commas. All text following the semicolon ultimately is passed to the C/C++ runtime function
fopen() in the "mode" argument. Although there are a number of options that can be included in the mode string, only the following keywords are supported by Oracle for use in FNA:
Table 2-1 FNA Keywords and Descriptions
|recfm=||Specifies the record format. Record format choices are the familiar z/OS JCL RECFM terms such as V, VB, F, FB, and so on. You can also specify
|lrecl=||Specifies the logical record length in bytes as a decimal integer. Choose a valid logical record length that meets any requirements specific to the tool or utility.|
|blksize=||Specifies the physical block size in bytes as a decimal integer. Choose a valid block size large enough to accommodate the logical record length. When using record format F or FS, block size must equal the logical record length. When using fixed blocked format (FB or FBS), block size must be an integer multiple of logical record length.|
|space=|| Specifies space allocation for a new data set on disk. The syntax for the value is similar to that of the SPACE keyword in z/OS JCL:
For details on these keyword parameters and their allowed values and syntax refer to the z/OS C/C++ Programming Guide.
Data set DCB attributes can come from sources other than FATTR or they can be completely unspecified, resulting in default behavior. Refer to the section "Data Set DCB Attributes" to understand how the various sources and default mechanisms determine what is ultimately established for a given data set.
The following shows an FNA control file supplied as an instream data set in a batch SQL*Plus job. It could just as easily be a sequential disk data set or a member of a PDS.
//REPORT EXEC PGM=SQLPLUS,PARM='/nolog' //STEPLIB DD DISP=SHR,DSN=ORACLE.V10G.CMDLOAD //ORA$LIB DD DISP=SHR,DSN=ORACLE.V10G.MESG //SQL DD DISP=SHR,DSN=YQB03.PROD.SQL <-- PDS containing SQL //ORA$FNA DD * /**************************** * Example FNA Control File * ****************************/ FSA( FTYPE(sql) FNAME('dd:sql(+)') } FSA( FTYPE(lst) FNAME('''YQB03.REPORTS.+''') FATTR(';space=(4096,(1000,200)),recfm=VBA,lrecl=137') } /* //SYSIN DD …
The example has FNA entries for the file extensions .
sql and .
lst. These extensions are associated with input SQL statement files and output SPOOL command files respectively. In the SQL*Plus input (not shown previously), a command which calls a file of SQL statements, such as the following:
This results in access to member REPORT2 in the partitioned data set YQB03.PROD.SQL. A SQL*Plus SPOOL command to direct output to a file, such a the following:
This results in writing the data set YQB03.REPORTS.WEEKLY. Assuming this data set does not already exist, it is created with a primary allocation of 1000 4K blocks and a secondary of 200 4K blocks. The data set is written with a record format of VBA and logical record length 137. The physical block size has been allowed to default.
Whenever Oracle opens an output filespec denoting a non-VSAM data set, DCB attributes must be determined. This is especially significant in the case of disk and tape data sets when the data set is to be processed or used by other software with specific DCB requirements, including non-Oracle software. These are situations where you may need to do something to ensure that specific DCB attributes are used. Multiple mechanisms are involved in establishing DCB attributes, including Oracle components such as FNA and z/OS components such as LE and DF/SMS. External factors such as the presence of DCB attributes on a DD statement or, for a preexisting data set, in the VTOC, also are involved.
Of chief importance in this area is LE, which performs the z/OS OPEN function for most data sets and thus controls much of what goes on. Even when you use FNA to request DCB attributes, Oracle simply passes the attribute keywords to the C function
fopen() and LE does the work.
In the following discussions various conditions lead to the setting of default DCB attributes. This refers to LE defaults, which are documented in z/OS C/C++ Programming Guide. The LE defaults depend on whether the file usage is "text" or "binary" (which comes from the software) and on the type of device or data set being used. In virtually all situations relevant to end users, Oracle opens files as "text" rather than "binary."
The LE default DCB attributes for text files depend on the type of device as shown in the following table:
When you use an FNA entry with FATTR as discussed in an earlier section, DCB attribute keywords from the FATTR string are passed to LE when the file is opened. In this case Oracle software takes no special action to influence what is finally established for DCB attributes; the outcome is simply normal LE behavior. The IBM manual C/C++ Programming Guide discusses some of the considerations in this situation, including the cases where not all three attributes (recfm, lrecl, and blksize) are specified. In general, the attributes you specify end up as the established attributes for the data set with any missing attributes defaulted as described in the IBM manual.
With sequential data sets, this process disregards any DCB attributes that might already exist (for a preexisting data set) or be coded in JCL (for a data set specified with DD:). In other words, DCB attributes from FNA will override both existing data set DCB attributes and DCB attributes you have specified on a DD statement or in a TSO ALLOCATE command. The issue arises only with sequential data sets. With an existing partitioned data set, if DCB attributes are specified in FNA they must match the established attributes of the data set.
To prevent changing existing sequential data set attributes, LE provides the special attribute notation recfm=*, which indicates that DCB attributes from the VTOC or on a DD statement are to be retained. When used, recfm=* should be coded without accompanying lrecl= or blksize= keywords. If these are included with recfm=* the values supplied must match the existing attributes.
A problem with recfm=* is that it eliminates LE default processing in determining DCB attributes. If you use this special attribute with a data set that does not have established DCB attributes, the data set ends up with the z/OS system default of RECFM=U. This is mostly likely to arise with a DD: filespec where the DD or allocation specifies DISP=NEW and no DCB attributes.
Most users do not intend to create data sets with a record format of U. Recently, IBM introduced another special attribute, recfm=+. This works exactly the same as recfm=* except for the case where there are no preexisting attributes: in that situation, the LE defaults discussed in the previous section are used. Support for recfm=+ was provided in IBM APAR PQ77259 which may or may not be installed on your system. Check with your z/OS system administrator to find out.
When Oracle opens a file for output and there is no FNA FATTR data associated with the type of file, the outcome depends on whether there are preexisting DCB attributes in the VTOC (for a disk data set) or on the DD statement or allocation (in the case of a DD: filespec). When there are preexisting attributes, they are retained as the real attributes for the data set provided they do not conflict with Oracle's intended usage. If there are no preexisting attributes, the LE defaults described earlier are used. This is essentially the behavior of LE's recfm=+ described previously, but it does not require that the fix for IBM APAR PQ77259 be installed. The additional checking and defaulting logic is provided by Oracle software.
When Oracle tools, utilities, or user-written applications run in an interactive environment (where there is a human user involved) it sometimes is desirable to interrupt a request that has been sent to the database server for processing. For example, when issuing ad hoc SQL from SQL*Plus, the user might realize that a SELECT is going to run too long in the server or produce too much output to view at the terminal. For these situations an interrupt mechanism is provided in the Oracle program interface code. The internals of the mechanism differ between TSO and a z/OS UNIX shell.
When an application running in TSO connects to an Oracle server, a subtask is automatically attached. The subtask uses the TSO STAX service to establish processing for TSO attention interrupts initiated with the 3270 ATTN or PA1 key. If you cause an attention interrupt while a request is running in the Oracle server, the message "Oracle ATTN." is displayed at the terminal and the server request is halted with an ORA-01013 error ("user requested cancel of current operation"). Halting of the server request is not necessarily instantaneous but usually occurs within a second or two.
In a shell, interrupt processing is implemented using POSIX signal processing that is part of z/OS UNIX System Services and LE. The internals are completely different from TSO and the interruption keying may differ (it normally is Ctl-C in a TTY session, for example) but the overall behavior is similar to that described for TSO. As in the TSO case, there may be a slight delay before the server recognizes the interrupt condition and terminates the current operation with ORA-01013.
Additional capabilities related to interrupt processing are provided in SQL*Plus. Refer to Chapter 4, "Oracle Tools and Utilities on z/OS"for details.
Prior to Oracle9
i Release 2, Oracle used its own C runtime library instead of LE. Developed in the early 1980's before POSIX services and HFS files existed on MVS, it differs from LE in certain areas, particularly filespec syntax and related processing. In its LE implementation Oracle provides compatibility for certain Oracle C runtime conventions. This compatibility is enabled by default so that existing customer jobs, scripts, and other types of programs continue to work without change. Oracle recommends that new customers (and new applications developed by existing customers) disable this compatibility or at least avoid using Oracle C runtime syntax, which conflicts slightly with LE conventions.
Most of the compatibility feature is controlled by the environment variable ORA_RTL_COMPAT. In non-POSIX environments, when this variable is not set or is set to ON, compatibility is enabled. When it is set to OFF, compatibility is disabled. The compatibility feature is always disabled when POSIX is ON, regardless of this environment variable.
You can specify ORA_RTL_COMPAT using any of the non-program environment variable mechanisms discussed earlier in this chapter. Setting it programmatically for example, using a call to C
putenv() is not supported. The variable must retain the same setting (or not be set at all) for the life of an application.
Your installation may choose to disable the compatibility feature by default using the global environment file feature described earlier in this chapter. In that case, to enable compatibility in an application, you must use a local (ORA$ENV) environment file with ORA_RTL_COMPAT=ON specified.
Because it runs prior to environment initialization, the compatibility feature for redirection operators is always enabled when POSIX is ON and is not affected by ORA_RTL_COMPAT.
When Oracle C runtime compatibility is enabled, filespecs that you supply in parameters, commands, and through FNA that use Oracle C runtime syntax are internally converted to equivalent LE syntax before they are used. Oracle C runtime used a filespec prefix notation based on HFS syntax in which a leading directory was interpreted as a keyword indicating the type of filespec to follow. The list shows the Oracle C runtime prefixes (on the left) and the LE syntax (on the right) to which they are converted when compatibility is enabled:
/DD/name //DD:name /DD/name(mem) //DD:name(mem) /ODD/name //*DD:name /ODD/name(mem) //*DD:name(mem) /DSN/name //'name' /DSN/name(mem) //'name(mem)' /ODSN/name //*'name' /ODSN/name(mem) //*'name(mem)'
The Oracle C runtime prefixes were case-insensitive, so filespecs with prefixes such as /dd/ or /ODsn/ are also converted, as shown in the prior list.
Note: Since the Oracle C prefix notation is valid HFS syntax in LE, enabling compatibility means you will be unable to access HFS files in directories with names like /DD and/dsn from a POSIX OFF application.
Oracle C runtime also supported inclusion of JCL-like attribute information in a filespec (following a comma or full colon). The same attributes could also be supplied through the FATTR keyword in an FNA entry. When compatibility is enabled, a subset of the available Oracle C runtime attribute keywords are converted to LE equivalents. (These are the same LE attributes that you can use directly in FNA, discussed earlier.) Oracle C attributes without an LE equivalent are discarded. The following list shows the Oracle C attribute on the left, and the LE equivalent to which they are converted, on the right:
BLKsize=x blksize=x BLOck=x space=(x,…) CYL space=(cyl,…) DIrectory=x space=(,(,,x)) F recfm=F FA recfm=FA FB recfm=FB FBA recfm=FBA FBAS recfm=FBAS FBS recfm=FBS LRecl=x lrecl=x PRIMary=x space=(,(x,…)) RECFM=x recfm=x SECondary=x space=(,(,x,…)) TRK space=(trk,…) V recfm=V VA recfm=VA VB recfm=VB VBA recfm=VBA
Besides the filespec and attribute conversions, enabling Oracle C runtime compatibility has another significant effect on file processing. With Oracle C runtime, prefixing of data set names that were not quoted or began with
/ODSN/ was done only in TSO, when a PROFILE PREFIX was set. LE prefixes unquoted data set names in non-TSO applications, using the z/OS userid associated with the address space. When Oracle C runtime compatibility is enabled, the prefixing normally done by LE in non-TSO environments is disabled in POSIX OFF applications.
An exception to Oracle C runtime compatibility occurs in file redirection operators when redirection specifies a z/OS data set name without a
/DSN/ prefix or surrounding apostrophes. In a batch job, Oracle C runtime would not prefix such a data set name but in Oracle's LE implementation prefixing does occur. This behavior is not affected by the ORA_RTL_COMPAT environment variable.
Oracle C runtime used different defaults for two of the three standard files discussed earlier in this chapter and also supported redirection syntax that is not supported by LE. Compatibility in this area, which pertains only to Oracle tools and utilities running in POSIX OFF environments, is provided using the LE exit routine CEEBXITA. This exit runs before the C environment is initialized and is permitted to examine and modify parameters specified on the command line or in the PARM string. Because it runs before environment initialization, this processing is not affected by the ORA_RTL_COMPAT environment variable.
Since it can't be controlled by the user, this compatibility processing is conditioned on detecting when Oracle C runtime conventions are being used. Detection is based on the use of Oracle C syntax for redirection (both the redirection operators and the following filespecs) and on the presence or absence of certain DD names.
The detection and compatibility processing proceeds as follows:
If the Oracle C standard error redirection operator "?"or "??" is found in the command line or PARM, it is converted to the LE equivalent "2>" or "2>>", respectively.
All redirection operators in the command line or PARM are examined for the use of Oracle C filespec syntax (/DD/, /ODD/, /DSN/, or /ODSN/). Any that use this syntax are changed to LE equivalents described in "Filespec Compatibility".
If no redirection of standard error was found and a SYSERR DD statement is present, standard error is redirected to it using 2>//DD:SYSERR.
If there was no redirection of standard output and a SYSOUT DD statement is present, standard output is redirected to it using 1>//DD:SYSOUT. In a batch job, this occurs only if a SYSERR DD statement also is present.
In a batch job only, if any one or more of these conversions was done and there are redirection operators with data set name filespecs that do not use apostrophes, those filespecs are modified to enclose the data set name in apostrophes.
The effect of this somewhat complex set of rules is to permit both Oracle C runtime syntax and conventions and LE syntax and conventions to coexist as much as possible. One limitation of this implementation is that the standard files cannot be redirected to HFS files under directory names like /DD or/dsn because they are interpreted as Oracle C syntax.