Getting started with IBM Open Enterprise Foundation for z/OS

In order to use the IBM® Open Enterprise Foundation tools and libraries, a script named ".env" has been installed in the root installation directory. This script, when sourced, sets the appropriate PATH, LIBPATH, MANPATH, and other environment variables, enabling you to use the tools and libraries.

To start using the tools and libraries, navigate to the root installation directory and source the .env script by using the source or dot (.) command as below:

. ./.env # note we are using the dot builtin followed by a space to source the .env file

Note, sourcing refers to the process of loading variables defined in a file into your current shell session.

For example, if your Open Enterprise Foundation installation is at /usr/lpp/IBM/foz/v1r1, run:

cd /usr/lpp/IBM/foz/v1r1

Next, source the .env script by running the command:

. ./.env

The tools are now available in your environment.

Alternatively, set your PATH/LIBPATH/MANPATH environment variable to the corresponding directories as follows:

 export PATH=/usr/lpp/IBM/foz/v1r1/bin:$PATH
 export LIBPATH=/usr/lpp/IBM/foz/v1r1/lib:$LIBPATH
 export MANPATH=/usr/lpp/IBM/foz/v1r1/share:$MANPATH

It is recommended that you add the sourcing of the .env or the environment variables into your system profile or user .profile script.

Note: Due to tools such as GNU Make potentially conflicting with /bin/make, they are not exposed by default. Rather, you can use them with the g prefix, as in gmake. If you prefer to use tools such as GNU Make without the prefix, you can source the .altenv script as follows:

. ./.altenv

Verifying your installation

After you have sourced the environment scripts, you can verify installation with the install_test.sh script as shown here.

/usr/lpp/IBM/foz/v1r1/install_test.sh && echo $?

The expected return code is 0.

As an example, to verify that the git command is operational, verify the version number by passing in the --version option.

git --version

The version number of Git that is installed is displayed.

General environment variable settings

It is recommended that you enable enhanced ASCII auto-conversion with the following environment variables as all IBM Open Enterprise Foundation for z/OS® tools are compiled as ASCII programs; and therefore, rely on file tags for auto-conversion between various code pages.

To set the auto conversion environment variables, run the following commands.

export _BPXK_AUTOCVT='ON'
export _CEE_RUNOPTS='FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)'

To set the file tagging environment variables, run the following commands.

export _TAG_REDIR_ERR=txt
export _TAG_REDIR_IN=txt
export _TAG_REDIR_OUT=txt

Supported Environment variables

This section details the environment variables that can influence the behavior of Open Enterprise Foundation tools. These environment variables allow for customization based on your specific needs.

Note: Only use these customization when necessary as they may impact tool functionality.

Codepages and File Tagging

Standard Stream CCSIDs

  • __STDIN_CCSID=<ccsid>
  • __STDOUT_CCSID=<ccsid>
  • __STDERR_CCSID=<ccsid>

These variables define the CCSID (Coded Character Set Identifier) for the standard input (stdin), standard output (stdout), and standard error (stderr) file descriptors, respectively.

  • Default: If not set and the file descriptor is an untagged TTY (teletype), the CCSID defaults to 1047.

New File Encoding

  • _ENCODE_FILE_NEW=<codeset>

This variable controls the encoding and tagging of newly created files.

  • Default: ISO8859-1 - Creates files with ISO8859-1 encoding and tagged as ISO8859-1.
  • Options:
    • IBM-1047: Creates files with IBM-1047 encoding and tagged as IBM-1047.
    • BINARY: Creates files without translation and tagged as BINARY.
  • Tools Not Affected: The following tools do not respect this environment variable:
    • Git
    • GPG
    • GNU Make
  • Caveats: This environment variable does not work with the DSFS file-system.

Untagged File Read Mode

  • __UNTAGGED_READ_MODE=<option>

This variable determines how Open Enterprise Foundation tools handle untagged files or files tagged with CCSID 1047 where the "txtflag" is turned off.

  • Default: AUTO - Reads and checks up to 4KB of data. If found to be in CCSID 1047, it is converted.
  • Options:
    • ASCII: Always converts data from CCSID 1047 to CCSID 819 (ASCII).
    • NO: Ignores files with CCSID 1047 and txtflag off.
    • STRICT: No explicit conversion of data.
    • WARN: Same as AUTO but issues a warning if conversion occurs.

Debugging / Logging

Memory Usage Logging

  • __MEMORY_USAGE_LOG_LEVEL=<value>

    Sets the logging level for memory allocation and deallocation events.

    • Values:
      • 1: Displays warnings only.
      • 2: Displays all messages, including process start/termination with memory usage summary and any errors.

  • __MEMORY_USAGE_LOG_FILE=<filepath>

    Specifies the file for memory usage log messages.

    • Default: stdout or stderr.

Runtime Debugging

  • __RUNDEBUG=<value>

    Enables or disables debug mode.

    • Values include setting to any non-empty value to enable debug mode and unset or empty to disable debug mode.

Examples

1. Disabling explicit conversion for untagged files:

To read untagged files without heuristic interpretation, set the following environment variable:

export __UNTAGGED_READ_MODE=STRICT

2. Change the default file tag for new files:

The default file tag for newly created files is ISO8859-1. To change it to IBM-1047, set the environment variable as follows:

export _ENCODE_FILE_NEW=IBM-1047
vim newfile.txt # newfile.txt will now be created and tagged as IBM-1047