File Handling and Dataset Environment Variables

Lists environment variables related to configuring file and dataset handling.

COBDATA

Specifies the directory or directories that the run-time system is to search for data files.
Syntax
Windows:
COBDATA=path-name[[;path-name][...]]
UNIX:
COBDATA=path-name[[:path-name][...]]
Parameter
path-name
The full path to a directory for the run-time system to search for application data files. When more than one path-name is present, a null path-name represents the current working directory.
Default
Not set. The run-time searches the current working directory.
Comments
On Windows platforms, this environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.

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

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:

  1. Any dd_ environment mappings
  2. Any ASSIGN TO EXTERNAL mappings
  3. 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.

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

Windows platforms:

The following causes COBDATA to be set to instruct the run-time system to search for data files in the current directory, then in the current directory's demo subdirectory, and finally in the C:\data\progs directory.

COBDATA=.;.\demo;C:\data\progs

UNIX platforms:

The following causes COBDATA to be set to instruct the run-time 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.

COBDATA=:demo:/home/data:progs

DB2DBDFT

The default database against which the DB2 SQL preprocessor processes SQL statements.
Syntax
DB2DBDFT=path-name/database-name
Parameters
path-name
The location of the default database.
database-name
The name of the default database.
Default
Not set. Uses the database name specified in the project.

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 Database File Handler and Enterprise Server Region Database Management for more information.
Syntax
ES_DB_FH={[Y|true]|[N|false]}
Parameters
Y|true
Use the Micro Focus Database File Handler (MFDBFH) to direct file handling.
N|false
Disable database file handling.
Default
ES_DB_FH=N
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_DB_SERVER

Specify the name of the database server to be used for region database operations.
Important: The configuration file specified by the MFDBFH_CONFIG environment variable must contain a corresponding <server> entry for the database server. <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
ES_DB_SERVER=server-instance
Parameter
server-instance
The name of a valid database server instance.
Default
Not set.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Example
ES_DB_SERVER=MYSERVER

In this example, your database configuration file would need to contain something similar to the following:

<datastores usevault="false">
   <server name="MYSERVER" 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_LOCKDB

Specifies the region database that is to process resource locking (step- and system-scoped ENQs) for an enterprise server region within a cluster, where resources such as catalogs are deployed to a database.
Syntax
ES_LOCKDB=region-db
Parameter
region-db
The name of the region database responsible for processing step- and system-scoped ENQs.
Default
Not set.
Comments
This variable must be used in conjunction with ES_SERVER, in which ES_SERVER is set to the database server that houses the region database; see Resource Locking for more information.

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.
Syntax
ES_RLS_FILE_SUPPORT=Y
Parameter
Y
Stops dirty records being returned when a record is locked by another process.
Default
Not set. Dirty records are returned.
Comments
The timeout in fileshare also needs to be set to 0 using /t 0 in the fileshare configuration file. See Using a Fileshare Configuration File for details.

Parameter values are not case sensitive.

EXTFH

Specifies a configuration file for the Callable File Handler.
Syntax
EXTFH=file-name.cfg
Parameter
file-name
The prefix name of the configuration (.cfg) file.
Default
Not set. The default configuration file name prefix is extfh.
Example
Windows:
EXTFH=c:\mydir\myconfig.cfg
UNIX:
EXTFH=/home/mydir/myconfig.cfg

FHREDIR

Specifies a configuration file to be used by the Fileshare Client.
Syntax
Windows:
FHREDIR=[path-name\]prefix.cfg
UNIX:
FHREDIR=[path-name/]prefix.cfg}
Parameters
path-name
The full path to the location of the Fileshare Client configuration file.
prefix
The prefix name of the configuration (.cfg) file.
Default
Not set. Uses the fhredir.cfg file in the current working directory.
Example
Windows:
FHREDIR=C:\mydir\myconfig.cfg
UNIX:
FHREDIR=/home/mydir/myconfig.cfg

FS

Specifies a configuration file to be used by the Fileshare Server.
Syntax
FS=file-name.cfg
Parameter
file-name
The prefix name of the configuration (.cfg) file.
Default
FS=fs.cfg
Example
FS=myfsconf.cfg

FSCOMMS

Specifies that the Fileshare system is to run in single user mode.
Syntax
FSCOMMS="\$local"
Parameter
$local
Run the Fileshare System in single user mode.
Default
Not set. Fileshare system runs in multi-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).
Attention: 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
HCOBND=path-name
Parameter
path-name
The directory that the DB2 ECM is to use to store bind files.
Default
Not set. Looks only in the current working directory for bind files generated by the DB2 ECM.
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.
Example
Windows:
HCOBND=d:\mydir\binds
UNIX:
HCOBND=/mydir/binds

LIB

The location of the DB2 LIB directory.
Syntax
LIB=path-name
Parameter
path-name
The path to your Windows SDK LIB directory (x86) containing .lib files such as odbc32.lib.
Comments
On Windows platforms, this environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.

MF_CBLQDA

Determines if QSAM files are dynamically allocated
Syntax
MF_CBLQDA={ON|OFF}
Parameters
ON
Dynamically allocate QUSAM files when processing an OPEN I-O or OPEN EXTEND statement for an optional file (i.e., a file opened using the SELECT OPTIONAL syntax in the FILE-CONTROL paragraph) or a file opened for OUTPUT, whether it is optional or not.
OFF
Dynamic allocation is not permitted.
Default
MF_CBLQDA=OFF
Comments
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.

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_LEX_API

Specifies whether the JES configuration uses single or multiple LEX files, and enables JES configuration to specify subdirectories for LEX files as necessary.
Syntax
MF_LEX_API={1|2|D}|1D|2D|D
Parameters
1
Use multiple LEX files.
2
Use a single LEX file. Disk-based access only.
D
Use directories to store LEX files.
Default
MF_LEX_API=1
Comments
Do mix these settings in a Region/PAC. They must be consistent for all.
Example
This example sets the JES configuration to use a single LEX file stored in directories.
MF_LEX_API=2D

MF_NEWSPACE

Indicates whether SPACE is required for NEW datasets.

MF_SYSLOGDSN

The Syslog Dataset name.

MFALLOC_LOC

The default allocated dataset location.
Syntax
MFALLOC_LOC={path-name|SQL-URL}
Parameters
path-name
The full path to the dataset location.
SQL-URL
For a database-hosted dataset, the SQL URL to that location.
Default
Not set.
Example
Set the default allocated dataset to the sql://localhost/JCLTEST?folder=/JCLDEMO/data location:
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
Windows:
MFDBFH_CONFIG=path-name\file-name
UNIX:
MFDBFH_CONFIG=path-name/file-name
Parameters
path-name
The full path to the location of the configuration file.
file-name
The file name of the configuration file.
Default
Not set. Uses the mfdbfh.cfg file found in the current working directory.
Comments
You can also set MFDBFH_CONFIG as a system environment variable.

MFDBFH_RECORD_LOCKING

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

Syntax
MFDBFH_RECORD_LOCKING={table|database}
Parameters
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 Record Locking Strategies for more information.
Default
MFDBFH_RECORD_LOCKING=table

MFDBFH_SCRIPT_DIR

Specifies the location of the scripts and stored procedures required when the database file handler is in effect.
Syntax
MFDBFH_SCRIPT_DIR=path-name
Parameter
path-name
The full path to the directory containing the required resources.
Defaults
Windows:
MFDBFH_SCRIPT_DIR=%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\mfdbfh\scripts
UNIX:
MFDBFH_SCRIPT_DIR=$COBDIR/etc/mfdbfh/scripts

MFDBFH_VAULT

Specifies the name of a secrets vault.
Syntax
MFDBFH_VAULT=vault-name
Parameter
vault-name
The name of a vault that is defined in the product's secrets.cfg file.
Default
Not set. Uses the default vault as defined in secrets.cfg.
Comments
For more information on secrets vaults, see Vault Facility.

MFFTP_ASCII_CMD_XLATE

For EBCDIC datasets, translates from EBCDIC to ASCII using a PUT, and ASCII to EBCDIC using a GET.
Syntax
MFFTP_ASCII_CMD_XLATE={Y|N}
Parameters
Y
Converts from EBCDIC to ASCII in PUTs and from ASCII to EBCDIC in GETs, for files cataloged as EBCDIC when TYPE A or ASCII sub command is also issued.
N
Standard conversion.
Default
MFFTP_ASCII_CMD_XLATE=N

MFLOCKING

Enables Locking Support.

PROCLIB

Under a mainframe emulation, determines whether a status of 37 is returned.
Syntax
PROCLIB={ON|OFF}
Parameters
ON
Under a mainframe emulation, returns a file status of 37 when you open an existing VSAM file for OUTPUT and the file has or previously had some data written to it, or if the file format is different from the file on disk.
OFF
No file status is returned.
Default
PROCLIB=OFF

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, or 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.
Default
STRICTVSAM=OFF

TXFILEP

The location of Micro Focus VSAM files.
Syntax
TXFILEP={path-name|datastore-location}
Parameters
path-name
The full path to the VSAM files on disk.
datastore-location
For database-hosted files, the location of the datastore containing the VSAM files. Use the notation described in the The dbfhdeploy Command Line Utility topic under Category > data.

XFHLOG

Determines the location of the log file when the LOG option is active.
Restriction: This environment variable applies to Windows platforms only.
Syntax
XFHLOG=DEFAULT
Parameter
DEFAULT
Generates the log file in the current working directory.
Default
Not set. The log file is generated in %ProgramData%\Micro Focus\File Handler\version-number, where version-number represents the version of your Micro Focus product.
Comments
The effect of this variable can be overridden by the LOGFILENAME configuration option.