C H A P T E R 2 |
Setting Region Environment Variables |
This chapter describes the tasks involved in defining an application region. A region is a set of processes, tables, files, and environment variables that defines a unique application.
The chapter contains the following topics:
The first step in configuring your Sun MTP application environment is to define a region. Before you start, however, design a directory structure and move your application's data and program files into the appropriate directories. FIGURE 2-1 shows an example of a directory structure.
Defining a region involves several tasks:
After setting the environment variables, read Chapter 3, which explains how to start and stop a region and make a local client connection.
Using your operating environment's facilities, create a directory structure similar to the one in the following figure, which shows some of the environment variables that correspond to specific directories. The environment variables you set must point to the directories in your structure.
This section describes most of the environment variables you will need to set up a region. You might need other environment variables depending on your application.
The following table describes the environment variables that the region uses to locate program files and applications. Most of these variables are set in the region setup file. Variables set elsewhere are also noted in the table.
If using COBOL, set to the directory containing your COBOL copy library and the $UNIKIX/copy library. This is a colon-separated list of directories. |
|||
If using COBOL, set to the full path name where COBOL is installed. $COBDIR/bin must be in your Path. |
|||
Set to the directory containing programs started with the CALL command. |
|||
Maximum number of concurrent inbound requests for SNA connections from ECI/EPI clients and remote Sun MTP or CICS regions. The value must be greater than zero. If there are more requests than available sessions, the extra requests are queued until a session becomes available, which might affect performance. Required if configuring the unikixdcl process. See Configuring a Region for SNA. |
|||
Maximum number of concurrent outbound requests for SNA connections to remote Sun MTP or CICS regions. The value must be greater than zero. Additional requests are queued, which might affect performance, and are timed out if a session does not become available within 30 seconds. Required if configuring the unikixdcl process. See Configuring a Region for SNA. |
|||
Set to any value to ensure that asynchronously started transactions that span the period when the Daylight Savings Time change occurs, honor Daylight Savings Time. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide for more information about using this environment variable with the EXEC CICS START INTERVAL API. |
|||
If set, Sun MTP passes through the user name and password obtained from an ECI client request to a remote region without any local validation. |
|||
An alternate directory for an executable version of unikixtran. If $KIXBIN is set, that directory is searched first to load transaction servers when the region is started or restarted after an abort or CINI transaction. If $KIXBIN is absent or NULL, or a transaction server is not present in the $KIXBIN directory, all current search algorithms apply. The description of unikixmain -l in the Sun Mainframe Transaction Processing Software Reference Guide describes the search rules. |
|||
A colon-separated list of directories that contain batch shell scripts. A directory name can be followed by start and end times surrounded by brackets (for example, [HHMM-HHMM]). These times indicate the hours to search the preceding directory for shell scripts to run. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide for more information about $KIXBTCH. |
|||
Enables conversion tracing. To enable tracing, set this environment variable to YES. Output is written to the $KIXSYS/unikixmain.dbg file. Use this environment variable only under the direction of technical support. |
|||
Set this variable to YES to disable the use of Java programs in the region. The Java virtual machine (JVM) will not be loaded into the transaction processors. |
|||
Set to a directory where all internal trace dump files will be written. If not set, the files will be written to the $KIXSYS/debugkix directory. |
|||
If set, Sun MTP calls the dynamic routing exit before allocating a session during outbound Function Shipping, Distributed Program Link (DPL), Asynchronous Processing or Transaction Routing requests. |
|||
Required if you are connecting 3270 SNA clients. Set to the name of the UNIX host that is running the Sun MTP server. Must be set before starting Sun MTP. |
|||
If set to YES, Sun MTP remembers the userid the user signed in with during an inbound Transaction Route request. This userid will be returned in the EXEC CICS ASSIGN USERID command. The default value, NO, maintains the behavior of previous versions of Sun MTP, which returned blanks. |
|||
This variable, which modifies the behavior of the JVM, is typically only set for debugging. You can set KIX_JVM_OPTIONS to include any startup flags that would normally be given to a standalone JVM as command-line parameters to the java executable. |
|||
A colon-separated list of directories that is searched in left to right order when Sun MTP attempts to load a shared object or shared library for C or PL/I. If $KIXLIB is not set, the loader looks in $KIXSYS. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide for information about using C or PL/I. |
|||
Set to the directory where the license file resides. Refer to the Sun Mainframe Transaction Processing Software Installation Guide for installation instructions. |
|||
A colon-separated list of directories that is searched in left to right order when Sun MTP attempts to load a map. Maps are loaded from $KIXMAPS to $KIXSYS/_kix_reserved_maps or to the directory specified by the _KIX_RESERVED_MAPS environment variable. |
|||
The maximum number of ECI/EPI clients and remote Sun MTP or CICS regions that can autoinstall into a Sun MTP region. A request from a remote region is rejected if there are no available entries to install the region. See also Configuring a Region for ECI/EPI Clients. |
|||
A colon-separated list of directories that is searched in left to right order when Sun MTP attempts to load a COBOL program. |
|||
Set to any value (for example, KIXRDBMS_BYPASS=1) to start Sun MTP without connecting to a configured RDBMS. See Starting a Region With an RDBMS. |
|||
Specify batch read-locking for a list of VSAM files. This specification overrides each file's "batch read-locking" definition in the VSAM catalog for the duration of the batch job step or until another environment variable setting is encountered. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide. |
|||
Specify a list of VSAM files that will not be locked for batch updating. This specification overrides each file's "batch read-locking" definition in the VSAM Catalog for the duration of the batch job step or until another environment variable setting is encountered. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide. |
|||
Set to the port number Sun MTP will use for Micro Focus COBOL Remote Animation. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide. |
|||
Set to a timeout period, in seconds, that Sun MTP will wait for a cross-animation server before returning an error. Default value is 5 seconds. Refer to the Sun Mainframe Transaction Processing Software Developer's Guide. |
|||
Set to a directory from which Sun MTP loads mapsets. When loading a mapset from disk, Sun MTP searches $_KIX_RESERVED_MAPS first and uses that version, if present. If the target mapset is not present, Sun MTP searches $KIXMAPS and uses that version, which is copied to $_KIX_RESERVED_MAPS. If you do not set this variable, Sun MTP creates the default directory $KIXSYS/_kix_reserved_maps. Do not set this variable to $KIXMAPS. Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for more information. |
|||
Set to a directory where the kixsnap utility will write its output files. If you do not set this variable, Sun MTP writes the files to the directory $KIXSYS/debugkix. Refer to the Sun Mainframe Transaction Processing Software Reference Guide for more information about kixsnap. |
|||
To disable the dynamic password changing feature, you must set the environment variable KIXSNT_NOMEMUPDATE to any value (for example., KIXSNT_NOMEMUPDATE=1) before starting the region. When dynamic password changing is disabled, you must restart the region before any changes to the SNT take effect. Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for more information. |
|||
Set to the directory that contains the system tables. This environment variable uniquely defines a region. Many regions can run concurrently on the same host, but each region must have a unique value for $KIXSYS. Users who need to update Sun MTP tables must have write permission to this directory. |
|||
Shared library directory(s). Must be set to include $UNIKIX/lib. For Server Express, include $COBDIR/lib. If you are using the Sun Mainframe Administration Tool (Sun MAT), you must include the location of the JVM. |
|||
If you are using Sun MAT, set to a numeric value of at least 1 to enable debug tracing of the unikixadmin server. |
|||
Tells the shell where to search for executables. Colon-separated list of path names that are searched in left to right order. Set automatically by the shell; you must add the directories $UNIKIX/local/bin and $UNIKIX/bin, in that order. For COBOL, also add the bin directory ($COBDIR/bin) to the PATH variable. If using an RDBMS, add the executables directory of the RDBMS to the PATH variable. For example, $ORACLE_HOME/bin. |
|||
Maximum number of concurrent inbound requests for TCP/IP connections from ECI/EPI clients and remote Sun MTP or CICS regions. If there are more requests than available sessions, Sun MTP queues the extra requests, which might affect performance. Required if configuring the TCP Server process. See Configuring a Region for TCP/IP. |
|||
Maximum number of concurrent outbound requests for TCP/IP connections to remote Sun MTP or CICS regions. If there are more requests than available sessions, Sun MTP queues the extra requests, which might affect performance. Required if configuring the TCP Server process. See Configuring a Region for TCP/IP. |
|||
Set to the user's terminal type. A tput init (or similar terminal initialization command) is required after setting the value of TERM to initialize the terminal as defined by the cursor definitions. It also determines how the function keys are mapped to standard 3270 keys, such as program function keys (PF keys), Enter, Clear, and others. See Chapter 8 and Appendix A. |
|||
Set to the directory you use for temporary files; for example, /tmp. |
|||
Set to the full path name of the Sun MTP installation directory. |
You can implement transaction security either by using transaction security keys defined in the Sun MTP tables or by using Sun MTP Secure. Sun MTP Secure is an interface to an external security manager that provides both transaction and resource security checking. The Sun MTP software provides an external security system, Sun Mainframe Security Facility (Sun MSF), as well as security user exit code that you can use to develop a site-specific external security application. Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for information about security.
TABLE 2-2 describes the optional environment variables that enable and disable the use of Sun MTP Secure and an external security manager, and defines the level of security checking for each resource class. Set these variables in your region setup file.
By default, Sun MTP Secure is disabled (KIXSEC=NO), and the administrator-defined transaction security key mechanism is used; no resource security mechanism is available. If Sun MTP Secure is enabled (KIXSEC=YES), then external security checking is done for all transactions and resources, and any administrator-defined transaction security key is ignored. You can selectively disable external security checking for a resource type by specifying its corresponding KIXxxxSEC environment variable as NO (for example, KIXFCTSEC=NO).
The following table describes the environment variables that relate to the Sun MSF software. Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for instructions on using these variables.
You define a region's environment by setting the necessary environment variables in a file. This file can be an individual user's login file or a setup file that many users can execute.
A setup file for the COBOL version of the Primer sample application, $UNIKIX/test/primer/cobol/kixprimer, is shipped with the Sun MTP software.
The following example shows a sample Bourne or Korn shell setup file that sets the environment variables for a region. Note the following about the file:
To execute a setup file named kixsetup, which sets the environment variables for a region, use the syntax appropriate to your system's shell:
There must be a space between the . and kixsetup.
To Set the Environment Variables for the User Automatically at Login |
1. Perform one of the following:
Add the settings to the user's .profile file. Also, for Bourne shell users, you can add environment variables that are common to all users to the system shell script, /etc/profile.
Add the settings to the user's .login file.
2. For X users, run all X terminals with the -ls option so that .profile or .login is processed by the X terminal's internal shell.
Users can also set variables at the shell prompt.
The .profile file is the login file for Bourne and Korn shell users. In the user's home directory, edit or create a .profile file that sets the environment variables for a region. The following example illustrates a login file for a Bourne or Korn shell user.
The values for these variables are provided as examples. The script must contain the export command to export the variables.
The .login file is the login file for C shell users. The syntax is different from the Bourne/Korn shell .profile file. The C shell does not require that you export environment variables. The following example illustrates a .login file for a C shell user. The values for these variables are provided as examples only.
Copyright © 2004, Sun Microsystems, Inc. All rights reserved.