CRASRV.properties, the RSE interface to CARMA

The Common Access Repository Manager (CARMA) server provides a standard API for other products that use host systems to access one or more Software Configuration Managers (SCMs). However, it does not provide methods for direct communication with a client computer. For this communication, it relies on other products, such as the Remote System Explorer (RSE) server. The RSE server uses the settings in CRASRV.properties to start and connect to a CARMA server.

# CRASRV.properties - CARMA configuration options
#
clist.dsname=''
crastart.configuration.file=crastart.conf
#connect.timeout=60
#port.start=0
#port.range=100
#system.exit='/usr/lpp/IBM/zee/samples/craexit.rex'
#user.exit='FEL.SFELSAMP(CRAEXIT)'
#startup.script.name=carma.startup.rex
#crastart.stub=CRASTART
#crastart.syslog=Partial
#crastart.timeout=420
#crastart.steplib=FEL.SFELLPA
#crastart.tasklib=TASKLIB

clist.dsname

Defines the startup method for the CARMA server. For more details about the different startup methods, see Select the server startup method and active RAM.

• *CRASTART indicates that the CARMA server should be started as a subtask within RSE using CRASTART. If you specify *CRASTART, you must also specify the crastart.* directives, or use their default values.
• Any other value defines the location of the CRASUBMT CLIST, using TSO-like naming conventions. With single quotation marks (') the data set name is an absolute reference, without the single quotation marks (') the data set name is prefixed with the client's user ID, not the TSO prefix. The latter requires that all CARMA users must maintain their own CRASUBMT CLIST.

The default is a null string, to indicate that CARMA is not configured.

crastart.configuration.file

Specifies the name of the CRASTART configuration file. The default is crastart.conf. This file specifies the data set allocations and program invocations that are needed to start a CARMA server. This directive is used only if the clist.dsname directive has *CRASTART as value. The file name can be specified in several ways:

• Null string, which means that the variable is not specified. The default value is used.
• Only a file name, which is the default method. CARMA searches your configuration directory (/etc/zexpl by default) to find the file.
• Relative path, which is the directory and file name, without a leading forward slash (/). CARMA adds your configuration directory (/etc/zexpl/ by default) to the provided path to make it an absolute path.
• Absolute path, which is the directory and file name, with a leading forward slash (/). CARMA uses the specified file location.

#connect.timeout

Specifies (in seconds) how long CARMA miner (active in RSE) waits for CARMA server (load module CRASERV) to start up and connect to the port on which CARMA miner is listening. The default is 60 seconds. Uncomment and customize to change the wait time.

#port.start

When the value of port.start is 0 (zero), CARMA uses an ephemeral port for communication between CARMA and the RSE server. In this scenario, TCP/IP assigns a random free port number. When the value of port.start is non-zero, it is interpreted as the starting point of a port range used for communication between CARMA and the RSE server, in which case the port.range variable must also be defined. The default port is 0. To specify the start of the port range, uncomment and customize. Communication on this port is confined to your host system.

Note: Before selecting a port, verify that the port is available on your system by using the NETSTAT and NETSTAT PORTL commands. For more information, see "Reserved TCP/IP ports" in the Host Configuration Reference (SC27-9934) .

#port.range

Range of ports, starting at port.start, which is used for CARMA communication if port.start is non-zero. The default is 100. To specify the size of the port range, uncomment and customize. For example, when port.start is 5227 and port.range is 100, port 5227 until 5326 (both inclusive) can be used by CARMA. Each CARMA connection uses a port exclusively, so specifying a port range limits the maximum number of concurrent CARMA sessions.

#system.exit

Defines user-specified code to be executed before creation of the CARMA server address space. The user-specified code is also executed after termination of the CARMA server address space to allow for cleanup actions. Uncomment and specify the (z/OS® UNIX) file name of the code to be executed. The file name can be specified in several ways:

• Only a file name. CARMA searches the directories in the PATH environment variable to find the file.
• Relative path, which is the directory and file name, without a leading forward slash (/). CARMA adds your configuration directory (/etc/zexpl/ by default) to the provided path to make it an absolute path.
• Absolute path, which is the directory and file name, with a leading forward slash (/). CARMA uses the specified file location.

A sample user exit is provided as /usr/lpp/IBM/zee/samples/craexit.rex. This sample also documents the startup arguments passed to the user exit. For more information see (Optional) CARMA user exit.

#user.exit

Defines user-specified code to be executed after the creation of the CARMA server address space, just before the CARMA server is started. The user-specified code is also executed after the CARMA server ends, before address space termination, to allow for cleanup actions.. Uncomment and specify the data set name of the code to be executed.

With quotes (') the data set name is an absolute reference, without quotes (') the data set name is prefixed with the client's user ID, not the TSO prefix. The latter requires that all CARMA users must maintain their own exit code.

A sample user exit is provided as FEL.SFELSAMP(CRAEXIT). This sample also documents the startup arguments passed to the user exit. For more information see (Optional) CARMA user exit.

startup.script.name

Defines the CARMA startup script. The default is carma.startup.rex. This REXX exec triggers the startup of a CARMA server. The file name can be specified in several ways:

• Null string, which means that the variable is not specified. In this case, the default value is used.
• Only a file name, which is the default method. CARMA searches the directories in the PATH environment variable to find the file. The directory holding Developer for z/OS executables (/usr/lpp/IBM/zee/bin by default) is automatically added to the PATH environment variable.
• Relative path, which is the directory and file name, without a leading forward slash (/). CARMA adds your configuration directory (/etc/zexpl/ by default) to the provided path to make it an absolute path.
• Absolute path, which is the directory and file name, with a leading forward slash (/). CARMA uses the specified file location.

#crastart.stub

z/OS UNIX stub for calling CRASTART. The default is CRASTART. This stub makes the MVS based CRASTART load module available to z/OS UNIX processes. To specify a specific path, uncomment and customize. This directive is used only if the clist.dsname directive has *CRASTART as value. The file name can be specified in several ways:

• Null string, which means that the variable is not specified. The default value is used.
• Only a file name, which is the default method. CARMA searches the directories in the PATH environment variable to find the file. The directory holding Developer for z/OS executables (/usr/lpp/IBM/zee/bin by default) is automatically added to the PATH environment variable.
• Relative path, which is the directory and file name, without a leading forward slash (/). CARMA adds your configuration directory (/etc/zexpl/ by default) to the provided path to make it an absolute path.
• Absolute path, which is the directory and file name, with a leading forward slash (/). CARMA uses the specified file location.

#crastart.syslog

Specifies how much information is written to the system log while CRASTART starts a CARMA server. The default is Partial. Valid values are listed in the following table.

Value	Description
A (All)	All tracing information is printed to SYSLOG
P (Partial)	Only connect, disconnect, and error information is printed to SYSLOG
anything else	Only error conditions are printed to SYSLOG

To specify the required detail level for system log messages, uncomment and customize. This directive is used only if the clist.dsname directive has *CRASTART as value.

#crastart.timeout

The length of time, in seconds, before a CARMA server ends due to lack of activity. The default is 420 (7 minutes). To specify the required timeout value, uncomment and customize. This directive is used only if the clist.dsname directive has *CRASTART as value.

Note: System abend 522 for module CRASERV will occur if the JWT parameter in the SMFPRMxx parmlib member is set to a value lower than the crastart.timeout value in CRASRV.properties. This occurrence does not impact CARMA operations because the server is restarted automatically if needed.

#crastart.steplib

The location of the CRASTART module when accessed through the STEPLIB directive in zee.env. The default is FEL.SFELLPA. If the CRASTART module cannot be part of LPA or LINKLIST, uncomment and customize this directive. Program control and APF issues might arise if the CRASTART module is not in LPA. This directive is used only if the clist.dsname directive has *CRASTART as value.

#crastart.tasklib

Alternate name for the TASKLIB DD name in crastart.conf. The default is TASKLIB. If the DD name TASKLIB has a special meaning for your SCM or RAM and cannot be used as STEPLIB replacement, uncomment and customize this directive. This directive is used only if the clist.dsname directive has *CRASTART as value.