2 Oracle Software Interaction with z/OS and Language Environment

2.2.2.1 Application Program, Tool, or Utility

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.

2.2.2.2 LE Runtime

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.

2.2.2.3 Oracle Program Interface Code

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.

For OCCI applications, the OCCI program interface code is a program object named LIBOCCI. It is required at runtime by all OCCI applications. LIBOCCI and OCCI applications that call the OCI API also depend on LIBCLNTS Therefore, LIBCLNTS and LIBOCCI reside in CMDLOAD and in the lib subdirectory of Oracle home.

2.2.2.4 Oracle Supporting Data Objects

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:

1. If an ORA$LIB DD is present in the address space, it is searched for a matching program object.

2. 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.

3. 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.

2.2.2.5 Invocation Examples

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.

Example 1

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

Example 2

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…

Example 3

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…

2.2.3.1 Parameters in Batch (JCL)

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.

Example 1

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.

Example 2

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.

2.2.3.2 Parameters in TSO

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.

Example 1

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 tsoprefix.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.

Example 2

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'.

2.2.3.3 Parameters in a z/OS UNIX Shell

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)

2.2.3.4 Parameters Containing Spaces

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 "++".

2.2.4.1 Environment Variables in a z/OS UNIX Shell

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 a Program".

2.2.4.2 Environment Variables in Batch and TSO Environments

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:

1. The LE runtime option ENVARn (not available in Oracle tools and utilities)

2. 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)

3. A global default set of Oracle environment variable assignments in a specific z/OS data set or HFS file

4. A local set of environment variable assignments specified by the ORA$ENV DD statement in the application

5. Program calls to functions such as C/C++ putenv() during application execution (discussed in "Setting Environment Variables in a 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.

2.2.4.3 Oracle Environment Variable Files

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

where 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 stuff:$That, not stuff:something.

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.

2.2.4.4 Setting Environment Variables in a Program

If you create an Oracle-accessing applications using IBM C/C++ (Pro*C/C++, OCI, or OCCI applications) you have access to functions like putenv() and 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.

2.3.2.1 Data Set Names

The full form for specifying a z/OS data set by its name is

//'dsname'

or

//'dsname(member)'

where 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".

The dsname and 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.

2.3.2.2 DD Names

You can identify a file as a DD statement or TSO allocation using the following filespec forms:

//DD:name

or

//DD:name(member)

where 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 name and 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.

2.3.2.3 SYSOUT

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

//SYSOUT:class,form,dest

where 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.

The 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:.

The 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.

The 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.

The 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.

2.3.2.4 TSO Terminal

In a TSO session you can specify both input and output files as the terminal device using the filespec

//*

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)'

2.3.2.5 HFS Files

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:

./test.sql

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).

2.3.3.1 Standard File Defaults (non-POSIX)

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.

2.3.3.2 Redirection Operators in TSO and Batch

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.

2.3.4.1 What's in a Name?

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.

2.3.4.2 Data Set Name Parts

For z/OS data set name filespecs, the logical parts are determined as follows:

• 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'

2.3.4.3 HFS File Name Parts

When a filespec refers to an HFS file, Oracle components on z/OS follow the same rules as Oracle on other UNIX platforms for decomposing and composing filespecs. When decomposing an HFS filespec:

• 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.

2.3.4.4 Extension Processing

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

2.3.4.5 FNA

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.

2.3.4.6 FNA Name Transformation

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(+)') )

or

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.

2.3.4.7 FNA Attribute Assignment

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:

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.

2.3.4.8 Example FNA Control File

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:

get report2

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:

spool weekly

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.

2.3.5.1 Default DCB Attributes

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:

2.3.5.2 DCB Attributes from FNA

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.

2.3.5.3 DCB Attributes without FNA

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.