Configuring the TSO Client environment

Your environment definition defines user-specific values for a particular software development project. For example, the host name, port number, and whether the project uses Unified Change Management (UCM) are values that you must set for the development environment. To use the client component of TSO Client, set up at least one environment definition.

Before you begin

Previous step: Creating copy areas on the remote system

About this task

The environment definition is used to map your distributed system files to the mainframe system copy areas. When you create your environment definition, you must specify which distributed files to store in the client component of the TSO Client copy area. You do this by mapping distributed files to the copy area by using the copy area name.

Store environment definitions in a partitioned data set (PDS) that is installed with the TSO Client feature. The PDS is named defaultHLQ.versionnumber.TSCENV, where defaultHLQ is the default high-level qualifier you specified during installation, and versionnumber is a unique number identifying this product version. This PDS contains information common to the project, such as the host name and port number.

Procedure

To specify a new environment definition, do these steps:

Create a PDS member in the defaultHLQ.versionnumber.TSCENV data set (previously described).
Choose a meaningful member name, such as the name of your development project.
Add the following lines to the PDS member you created.
The following example shows the required parameters for an environment definition. Profile parameters describes all valid parameters for an environment definition file and the values you can specify for each.
```
HOST hostID
PORT portnumber
PLATFORM ( WINDOWS | UNIX )
DISTRIBUTED_ADD_PERMISSIONS permissions
VIEW_TYPE ( DYNAMIC | SNAPSHOT )
UCM ( YES | NO )
```
On the next line in your PDS member, map file names from your distributed DevOps Code ClearCase® views to specific partitioned data sets in your mainframe copy area by using file name patterns. You must specify at least one mapping (one line) to create a valid environment definition.
```
distributedFilePattern mainframeFilePattern ALLOCATION dataSetCharacteristics
```
For each set of distributed files you want to map, list the following fields, separated by at least one space:
- distributedFilePattern - The pattern name of the distributed files you want to map. For example, on a Windows® distributed system, typing vob-dir\rcc\src\*.h specifies all files in the distributed \rcc\src directory, in the vob-dir VOB, with the file extension of h. To map files in a snapshot view on Windows®, ensure that you specify a drive letter. To map files in a snapshot view on Linux® and the UNIX® system, ensure that you specify the directory path and VIEW_TYPE ( SNAPSHOT ) in your environment definition.
  When file names (not including file extension type) are greater than 8 characters long, the first 8 characters must be unique. Otherwise, they will be overlaid when uploaded into the copy area PDS. This requirement is due to the MVS™ 8-character restriction for member names. Likewise, because of the ambiguity, the download of the member might not update the proper file.
  Important: Do not use .bat, .err, or .out as file extensions.
- mainframeFilePattern - The mapped file suffix for the partitioned data set. For example, typing SRC.H maps all files in the distributed /rcc/src directory with the suffix of .h to the file suffix SRC.H. SRC.H is the mapped distributed file name and the last part of the copy area name. The file suffix is limited to five (or fewer) characters.
- ALLOCATION dataSetCharacteristics - Allocation parameters for the partitioned data set. If the data set is not already allocated, these allocation parameters are used to attempt to create it when you type 2.1 on the option line of the TSO Client Main Menu panel. If the data set is already allocated, the allocation parameters are ignored.
Mappings in the environment definition can be longer than a single line. To specify a mapping longer than one line, the last character of the previous line must not be blank, that is, the space character. If the character in position 251 of the previous line is any character other than a space character, the current line is a continuation of the previous line. No mapping can end on the last character of any line. If you want to end the mapping, ensure that the character in column 251 is a blank (space character). To increase readability, you can add as many blank lines as you want to the environment definition file.
The following is an example of a mapping that contains an allocation:
```
/var/tmp/tsc_lnx390_vob/*.foo TSC.FOO ALLOCATION LRECL(80)BLKSIZE(3120) RECFM (F B) SPACE(939,10) BLOCK(512) DSORG(PO)DIR(30) NEW CATALOG UNIT(SYSALLDA) 
```
The allocation specifications following the keyword ALLOCATION conform to the requirements of the TSO/E ALLOCATE command . Refer to the z/OS® TSO/E Command Reference for the applicable rules.

Example

The following is an example of the contents of an environment definition file.

HOST elmerf 
PORT 12345 
DISTRIBUTED_ADD_PERMISSIONS 755 
PLATFORM UNIX 
VIEW_TYPE DYNAMIC 
UCM YES 
PARMBUILD_SCRIPTS \\CCHOSTNAME\ccstg_d\Triggers
/uVOB/uDYNAMIC/src/*.h SRC.H 
/uVOB/uDYNAMIC/src/*.c SRC.C 
/uVOB/uDYNAMIC/src/*.asm SRC.ASM 
/uVOB/uDYNAMIC/src/*.obj SRC.OBJ 
/uVOB/uDYNAMIC/src/*.obj SRC.JCL

Note: The PLATFORM UNIX and/or the DISTRIBUTED_ADD_PERMISSIONS statements imply that this definition is only for Linux® and the UNIX® system.

The file mapping specification example shown above is for the specified configuration. The following are examples for specifying the file mapping to SRC.H for other configurations (besides the PLATFORM UNIX and VIEW_TYPE DYNAMIC example shown above).

For PLATFORM UNIX, VIEW_TYPE SNAPSHOT: /uVOB/uSNAPSHOT/src/*.h SRC.H
For PLATFORM WINDOWS, VIEW_TYPE DYNAMIC: wVOB\wDYNAMIC\src\*.h SRC.H
For PLATFORM WINDOWS, VIEW_TYPE SNAPSHOT: L:\wVOB\wSNAPSHOT\src\*.h SRC.H

The distributed file name patterns are specified differently according to the platform and the view type.

Note: If your SERVER_CODEPAGE is IBM-930, IBM-939, IBM-1390, or IBM-1399, then the backslash character used to indicate a file path delimiter is displayed as a Yen sign character.

What to do next

Next step: Verify and troubleshoot TSO Client connectivity