File Handling and Dataset Environment Variables

This topic lists environment variables that relate to configuring the file and dataset handling.

COBDATA

Specifies one or more locations, separated by ; (Windows) or : (UNIX), in which to search for data files at run time. As long as the file assignment does not contain a sub-path (that is, a string containing \ or /) then the file assignment is appended to each location specified by COBDATA in order to locate the file.

Note: Users modernizing RM/COBOL or ACUCOBOL-GT legacy code can use a sub-path in the file assignment, but only by compiling with the relevant DIALECT or IDXFORMAT values for the respective File Handling systems; setting these values in the File Handling configuration file is not sufficient to achieve this.

Specifies the directory or directories that the run-time system is to search for data files. Provides you with the facility to map data files globally, thus enabling you to put working data files in a directory whose name is not known until run time.

Syntax

UNIX:
COBDATA=pathname[:pathname]...
export COBDATA

Windows:
COBDATA=pathname[:pathname]...

Parameters

A list of search directories, each item separated by a semicolon (Windows) or colon (UNIX). The runtime system is to search these when looking for application data files. When more than one pathname is present, a null pathname represents the current working directory.

Comments

COBDATA affects the compiler and other utilities. During compilation, for example, program source is regarded as a data file by the compiler. If you intend to use any COBOL development system utilities, we recommend that the COBDATA value starts with a colon (:).

COBDATA is considered set if there is an environment variable of this name in your environment space, and its value is non-empty.

The full mapping order for files is:

Any dd_ environment mappings
Any ASSIGN TO EXTERNAL mappings
Any COBDATA environment variable mappings

For multiple directory paths specified either in the COBDATA environment variable or a dd_ environment variable, the system searches the first directory specified followed by a slash (/) as a prefix to the user name.

If the filename is not found, or is not readable, the search continues with the next directory until the final directory has been searched. If no file is found, the first directory is used if a file is to be created.

Any dd_ and COBDATA mappings are ignored for any filename that starts with a hyphen () or a slash (/). In addition, it is illegal to have a hyphen in an environment variable name.

When using this facility, you should not use a filename that starts with "COB... "(these are reserved for the COBOL system).

You can use the COBDATA environment variable for files open in any mode (including OUTPUT) and for fixed or variable length files. If you are using indexed files, both the data and index files must be in the same directory.

The COBDATA environment variable affects file deletes, using the rules given here, as well as file opens.

If you intend to use COBOL development system programs, we recommend that you first unset COBDATA, as many of these programs open data files and are thus affected by the value of COBDATA. If you have to set COBDATA, you should include the paths :$COBDIR/dynload/helptbox.lbr and :$COBDIR/dynload/check.lbr at the beginning of the COBDATA value. If you want to see the Animator Help pages, also include COBDIR/dynload/advanim.lbr.

Example

UNIX:
COBDATA=:demo:/home/data:progs
export COBDATA

Windows:
SET COBDATA=:demo:/home/data:progs

causes COBDATA to be set to instruct the runtime system to search for data files in the current directory, then in the directory ./demo, then in the directory /home/data and finally in ./progs.

DB2DBDFT

The default database for the DB2 SQL precompiler to process SQL statements against.

Values

The location and name of the default database.

ES_DB_FH

Enables or disables database file handler support. This is required if your data files are stored in a datastore, or your enterprise server region stores some of its resources in a database; see Micro Focus Native Database File Handling and Enterprise Server Region Database Management for more information.

Syntax

UNIX:
ES_DB_FH=value
export ES_DB_FH

Windows:
SET ES_DB_FH=value

Values

Y|y|true - file handling is directed through the Micro Focus Database File Handler (MFDBFH).
N|n|false - database file handler support is disabled.

Default

Database file handler support is disabled.

ES_DB_SERVER

Specify the name of the database server to be used for region database operations.

There also needs to be a corresponding <server> entry for the database server within the configuration file specified by the MFDBFH_CONFIG environment variable. <dsn> entries for the region, cross-region and master databases must also be specified in the configuration file to enable use of region database operations.

Syntax

UNIX:
ES_DB_SERVER=server-instance
export ES_DB_SERVER

Windows:
SET ES_DB_SERVER=server-instance

Values

server-instance is the name of a valid database server instance. For example, set ES_DB_SERVER=(local)\SQLEXPRESS.

Default

Not set.

Example

Using the example above, you would be required to have something similar to that below in your database configuration file:

<?xml version="1.0" encoding="utf-8"?> 
<datastores usevault="false">
   <server name="(local)\SQLEXPRESS" type="sqlserver" access="odbc"> 
       <dsn name="SS.MYMASTER" type="database" dbname="master"/> 
       <dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO" feature="all"/> 
       <dsn name="SS.CAS.CROSSREGION" type="crossregion.cas"/>
   </server> 
</datastores>

ES_RLS_FILE_SUPPORT

If a record is locked because a program is doing a read for update, and the application needs to ensure that no other program can access that record, you can set this environment variable to avoid returning a dirty record until the program holding the lock has completed. The timeout in fileshare also needs to be set to 0 using /t 0 in the fileshare configuration file.

Syntax

UNIX:
ES_RLS_FILE_SUPPORT=value
export ES_RLS_FILE_SUPPORT

Windows:
SET ES_RLS_FILE_SUPPORT=value

Values

Y|y - Stops dirty records being returned when a record is locked by another process.

Default

RLS file support is off.

EXTFH

Specifies a configuration file for the Callable File Handler.

Syntax

Windows:
SET EXTFH=filename.cfg

UNIX:
EXTFH=filename.cfg
export EXTFH

Parameters

filename.cfg The name of the configuration file.

Example

Windows:
SET EXTFH=/home/mydir/myconfig.cfg

UNIX:
EXTFH=/home/mydir/myconfig.cfg
export EXTFH

FHREDIR

Specifies a configuration file to be used by the Fileshare Client.

Syntax

Windows:
SET FHREDIR=filename.cfg

UNIX:
FHREDIR=filename.cfg
export FHREDIR

Parameters

filename.cfg The name of the configuration file.

Example

Windows:
SET FHREDIR=/home/mydir/myconfig.cfg

UNIX:
FHREDIR=/home/mydir/myconfig.cfg
export FHREDIR

FS

Specifies a configuration file to be used by the Fileshare Server.

Syntax

Windows:
SET FS=filename.cfg

UNIX:
FS=filename.cfg
export FS

Parameters

filename.cfg The name of the configuration file.

Example

Windows:
SET FS=myconfig.cfg

UNIX:
FS=myconfig.cfg
export FS

FSCOMMS

Specifies that the Fileshare system is to run in single user mode.

Syntax

Windows:
SET FSCOMMS="\$local"

UNIX:
FSCOMMS="\$local"
export FSCOMMS

Parameters

"\$local" Run the Fileshare System in single user mode.

GDG.RECALL

Controls the recall of HSM archived datasets when accessing mainframe GDGs using MFA Data Access Services.

HCOBND (deprecated)

Specifies a directory to be used for bind files generated by the DB2 External Compiler Module (ECM).

Note: HCOBND is deprecated, and provided for backward compatibility only. We recommend that you use either the BIND or the BINDDIR compiler directive option instead.

Syntax

Windows:
SET HCOBND=pathname

Windows:
HCOBND=pathname
export HCOBND

Parameters

pathname The directory that the DB2 ECM is to use to store bind files.

Example

Windows:

SET HCOBND=d:\mydir\binds

UNIX:

SET HCOBND=/mydir/binds
export HCOBND

Comments

The DB2 ECM uses the specified directory until the variable is unset or reset to a different directory. The DB2 Compiler directive option BIND overrides this environment variable.

LIB

The location of the DB2 LIB directory.

MF_CBLQDA

Determines if QSAM files are dynamically allocated when processing an OPEN I-O or OPEN EXTEND statement for an optional file (that is, a file opened using the SELECT OPTIONAL syntax in the FILE-CONTROL paragraph) or a file opened for OUTPUT (regardless of whether it is optional or not). Permissible values are OFF and ON; the default is OFF, which specifies that dynamic allocation is not permitted.

This is an emulation of the CBLQDA Language Environment (LE) run-time option.

When set to ON, and your JCL contains a misspelled or no DD statement for the file being opened, a temporary file is created as a result of the OPEN statement, and then deleted after the program has run. For optional files opened for I-O or for EXTEND, you receive a return code of 05; for files opened for OUTPUT, you receive a return code of 00.

This variable has no effect on VSAM applications or the JCL utility programs.

Note: For programs that use ESDS files and have this variable set ON, ensure that FILETYPE is set to 15 or 16; otherwise these files will be affected by the variable, and treated as QSAM files.

MF_NEWSPACE

Indicates whether SPACE is required for NEW datasets.

MF_SYSLOGDSN

The Syslog Dataset name.

MFALLOC_LOC

The default allocated data set location.

For a database-hosted data set location, you need to include the full SQL URL, for example, set MFALLOC_LOC=sql://localhost/JCLTEST?folder=/JCLDEMO/data

MFALLOC_PROP

Rules for generated PC dataset names on allocation (that is, the default catalog PC DSN format).

MFDBFH_CONFIG

Specifies the location and the name of the configuration file that defines the database server instances and associated databases.

Syntax

UNIX:
MFDBFH_CONFIG=value
export MFDBFH_CONFIG

Windows:
SET MFDBFH_CONFIG=value

Values

value represents the full path and filename of your database configuration file.

Default

Not set.

MFDBFH_CONNECTION_POOLING

Specify whether database connection pooling is to be enabled or not when the database file handler is in effect.

Syntax

UNIX:
MFDBFH_CONNECTION_POOLING=TRUE|FALSE
export MFDBFH_CONNECTION_POOLING

Windows:
SET MFDBFH_CONNECTION_POOLING=TRUE|FALSE

Paramaters

TRUE: Connection pooling is enabled, which keeps database connections open, and then reuses them where possible in preference of creating a new connection.
FALSE: Connection pooling disabled. This setting comes at a cost to performance, as a new physical connection is established each time. You may want to disable connection pooling during testing, when databases are more frequently added and dropped: if pooling is enabled, and existing connections remain open, it may stop you from dropping that particular database.

Default

MFDBFH_CONNECTION_POOLING=TRUE

MFDBFH_RECORD_LOCKING

Specifies the type of record locking that it is to be used when the database file handler is in effect.

Syntax

UNIX:
MFDBFH_CONFIG=table|database
export MFDBFH_CONFIG

Windows:
SET MFDBFH_CONFIG=table|database

Paramaters

table: A file's record locks are held in a seperate lock table. (When using this locking mode, the behavior of record locking COBOL file operations closely follows the same behavior when using Fileshare.)
database: The native record locking mechanism of the database engine is used to establish and test locks on the data file records. This method improves performance, but at the cost of the locking behavior not exactly matching that of traditional COBOL record locking; see Database Record Locking for a list of differences for each database engine.

Default

MFDBFH_RECORD_LOCKING=table

Note: If the value of this variable is set to anything other than 'database', this default is used.

MFDBFH_SCRIPT_DIR

Specifies the location of the scripts and stored procedures required when the database file handler is in effect.

Syntax

UNIX:
MFDBFH_SCRIPT_DIR=value
export MFDBFH_SCRIPT_DIR

Windows:
SET MFDBFH_SCRIPT_DIR=value

Values

value represents a path to the directory containing the required resources.

Default

value defaults to the \etc\mfdbfh\scripts sub directory of your product installation directory.

MFDBFH_VAULT

Specifies the name of a secrets vault (which must be defined in the product's secrets.cfg file). If this environment variable is not set, MFDBFH uses the default vault, as defined in secrets.cfg.

For more information on secrets vaults, see Vault Facility.

Syntax

UNIX:
MFDBFH_VAULT=value
export MFDBFH_VAULT

Windows:
SET MFDBFH_VAULT=value

Values

value represents the name of a vault.

Default

Not set.

MFLOCKING

Enables Locking Support.

PROCLIB

Specifies PROCLIB datasets. This can be a concatenation of PDS names.

strictvsam

Specifies strict mainframe emulation during file processing of VSAM files.

Syntax:

strictvsam=ON|OFF

Parameters:

ON

File status 37 is returned when an existing VSAM file is opened for OUTPUT if:

the file has data or previously had data written to it.
the file is of a different format to the file on disk.

OFF

File status 0 is returned and a new file is created when an existing VSAM file is opened for OUTPUT.

Properties:

Default:	OFF
IDE equivalent:	None

TXFILEP: The location of Micro Focus VSAM files. This can be a location on disk or a datastore location within a database. For database-hosted files, use the notation sql://host[/instance]/datastore[?folder=/path] - see The dbfhdeploy Command Line Utility for more information.

XFHLOG

Note: This variable is applicable to Windows platforms only.

Determines the location of the log file when the LOG option is active.

Syntax:

SET XFHLOG=DEFAULT

Parameters:

DEFAULT - generates the log file in the current directory.

Comments:

If the XFHLOG variable is not set, the log file is created in C:\ProgramData\Micro Focus\File Handler\[version-number].

where [version-number] represents the version of your Micro Focus product.

The effect of this variable can be overridden by the LOGFILENAME configuration option.