Rules for coding profiles

JVM profiles are text files encoded in EBCDIC when stored on the USS file system. When JVM profiles are created in a CICS® bundle, they can be edited on a workstation using any text editor. They must be converted to EBCDIC when they are transferred to USS. CICS Explorer® performs this conversion automatically when exporting a CICS bundle project to USS.

Case sensitivity

All parameter keywords and operands are case-sensitive, and must be specified exactly as shown in Options for JVMs in a CICS environment, JVM system properties, or Node.js profile and command line options.

Comments

To add comments or to comment out an option instead of deleting it, begin each line of the comment with a # symbol. Comment lines are ignored when the file is read by the launcher.

Blank lines are also ignored. You can use blank lines as a separator between options or groups of options.

The profile parsing code removes inline comments. An inline comment is defined as follows:

The comment starts with a # symbol
It is preceded with one or more spaces (or tabs)
It is not contained in quoted text

Table 1. Inline comment examples
Code	Result
`MYVAR=myValue # Comment`	MYVAR=myValue
`MYVAR=#myValue # Comment`	MYVAR=#myValue
`MYVAR=myValue "# Quoted comment" # Comment`	MYVAR=myValue "# Quoted comment"

Continuation

For options the value is delimited by the end of the line in the text file. If a value that you are entering or editing is too long for an editor window, you can break the line to avoid scrolling. To continue on the next line, terminate the current line with the backslash character and a blank continuation character, as in this example:

STDERR=/example/a/long/path/which/you/would/like\
 /to/break/over/a/line

Do not put more than one option on the same line.

Including files

Use %INCLUDE=<file_path> to include a file in your profile. The file can contain common system-wide configuration that can be maintained separate to the profile. This enables configuration that is common to several profiles to be shared, giving more control and providing easier maintenance for profiles.

The following rules apply:

<file_path> must be a fully qualified file in zFS.
- Avoid use of relative directories at the start of <file_path> such as . and ... They are interpreted by UNIX System Services as relative to the Language Environment® current working directory, which can change in processing.
- If <file_path> does not exist, or if the CICS region user ID does not have read access to <file_path> message DFHSJ1308 is issued.
<file_path> can contain symbols, for example &USSCONFIG;.
- Symbols &DATE; and &TIME; are not allowed due to the formatting for these being set via the time zone option (TZ) that can be before or after the %INCLUDE directive.
The contents of <file_path> replace the %INCLUDE directive.
A profile can contain any number of %INCLUDE directives.
Cyclic references result in message Skipping duplicate. For example, Profile-A can include Profile-B, and Profile-B include Profile-C; but if Profile-B includes Profile-A the directive is ignored.

Multiple instances of options

If more than one instance of the same option is included in a profile, the value for the last option found is used, and previous values are ignored.

UNIX System Services directory paths

Do not use quotation marks when specifying values for zFS files or directories in a profile.

Rules specific to JVM profiles

Appending values

Use the + character before a variable to append the value specified to the existing value of that variable using a comma separator, for example:

LIBERTY_INCLUDE_XML=/path/file1
+LIBERTY_INCLUDE_XML=/path/file2

This is the equivalent to:

LIBERTY_INCLUDE_XML=/path/file1,/path/file2

CEDA: The CEDA panels accept mixed case input for the JVMPROFILE field irrespective of your terminal UCTRAN setting. However, you must enter the name of a JVM profile in mixed case when you use CEDA from the command line or when you use another CICS transaction. Ensure that your terminal is correctly configured with uppercase translation suppressed. You can use the supplied CEOT transaction to alter the uppercase translation status (UCTRAN) for your own terminal, for the current session only.

Class path separator character: Use the : (colon) character to separate the directory paths that you specify on a class path option, such as CLASSPATH_SUFFIX.

Name of a profile

The name of a JVM profile can be up to eight characters in length.
JVM profiles on the file system must have the file extension .jvmprofile. The file extension is set to lowercase and must not be changed (only applies to JVM profiles).
The name can be any name that is valid for a file in z/OS® UNIX System Services. Do not use a name beginning with DFH, because these characters are reserved for use by CICS.
Because profiles are UNIX files, case is important. When you specify the name in CICS, you must enter it using the same combination of uppercase and lowercase characters that is present in the z/OS UNIX file name.

Referencing environment variables: Environment variables can be referenced in other variables in the JVM profile using the symbol notation syntax. For more information , see Symbols used in the JVM profile.

Storage sizes

When specifying storage-related options in a JVM profile, specify storage sizes in multiples of 1024 bytes. Use the letter K to indicate KB, the letter M to indicate MB, and the letter G to indicate GB. For example, to specify 6 291 456 bytes as the initial size of the heap, code -Xms in one of the following ways:

-Xms6144K
-Xms6M