Compressing REXX execs

Compression provides a potential performance benefit by reducing the size of the in-storage image of the exec. This could have benefits for all users on a system for execs that are stored in VLF. If you do not want certain execs to be compressed, you can do any one of the following:

allocate the exec data set to the SYSPROC user level file using the TSO/E ALTLIB command, or to a file that can contain only REXX execs, such as SYSEXEC
include the character string SOURCELINE in the exec, outside of a comment
specify the compression indicator COMMENT.

REXX execs in the SYSPROC system level, or a CLIST application level library as defined by ALTLIB, are eligible for compression. TSO/E REXX can automatically compress an exec, or you can request that a REXX exec be compressed.

In general, compression eliminates comment text and leading and trailing blanks, and replaces blank lines with null lines, which preserves the line numbering in the exec. For comments, the system removes the comment text but keeps the beginning and ending comment delimiters /* and */. This preserves the exec line numbering if the comment spans more than one line. Blanks and comments within literal strings (delimited by either single or double quotation marks) are not removed. Blanks or comments within a Double-Byte Character Set (DBCS) string are not removed.

Automatic Compression
- If the system automatically compresses the exec, it replaces the first line of the exec (the comment line containing the characters "REXX") with the comment /*%NOCOMMENT*/. If you review a dump of VLF, the /*%NOCOMMENT*/ comment is an indicator that the exec is compressed. For example, if the initial line 1 comment contains:
```
/* REXX */
```
  then after compression, line 1 contains:
```
/*%NOCOMMENT*/
```
  However, if the line 1 comment also contains other special options (the comment starts with /*%), TSO/E REXX inserts the option NOCOMMENT ahead of the other keyword options in line 1. The remaining keyword options of line 1 are not removed (compressed) from the line 1 comment. For example, if the initial line 1 comment contains:
```
/*% REXX xxxxxxx yyyyyyy */
```
  then after compression line 1 contains:
```
/*%NOCOMMENT REXX xxxxxxx yyyyyyy */
```
  If the system finds an explicit occurrence of the characters SOURCELINE outside of a comment in the exec, it does not compress the exec. For example, if you use the SOURCELINE built-in function, the exec is not compressed. If you use a variable called "ASOURCELINE1", the system does not compress the exec because it locates the characters SOURCELINE within that variable name. Note that the system does compress the exec if the exec contains a "hidden" use of the characters SOURCELINE. For example, you may concatenate the word SOURCE and the word LINE and then use the INTERPRET instruction to interpret the concatenation or you may use the hexadecimal representation of SOURCELINE. In these cases, the system compresses the exec because the characters SOURCELINE are not explicitly found.
Controlled Compression
- To request compression of the REXX exec, the exec must begin with a special comment in line 1. A comment is called a special comment if it is the first comment in line 1 and the begin comment delimiter /* is immediately followed by the special comment trigger character %. That is,
```
/*%
```
  The trigger character is followed by one or more keyword options. If you specify more than one keyword option, separate them by one or more blanks. You can also use blanks between the trigger character and the first keyword option for better readability. Keyword options can be lower case, upper case, or mixed case. The following are some examples of using a special comment. Note that there are no changes to the special comment after compression.
```
/*% REXX xxxx yyyy NOCOMMENT */
```
  then after compression the line is unchanged, except trailing blanks are removed, and the line contains:
```
/*% REXX xxxx yyyy NOCOMMENT*/
```
  The scan for keyword options ends by:
  - an end comment delimiter (*/)
  - another begin comment delimiter /* to start a nested comment
  - the end of the line.
  Keyword options cannot continue onto the second physical line, even if the comment itself continues to line two. If TSO/E REXX does not recognize a keyword option, it is ignored.

Rule: DBCS characters cannot be used within the special comment in line 1 to specify keyword options. All keyword options must be specified using the EBCDIC character set.

The compression indicator keyword options are COMMENT and NOCOMMENT, where:

COMMENT: indicates the exec is NOT to be compressed (the exec will contain comments).
NOCOMMENT: indicates the exec is to be compressed (the exec will NOT contain comments).

The COMMENT and NOCOMMENT compression indicators are only valid for execs which are invoked implicitly and are found in either a SYSPROC library or an application level CLIST library.

The following are some examples of using COMMENT and NOCOMMENT. In all of these examples the exec is invoked implicitly and is found in the SYSPROC CLIST library.

To indicate an exec is to be compressed, the author of the REXX exec might code the following:

/*%NOCOMMENT   REXX */
Say 'This exec will be compressed'
x = 5       /* This comment will be removed from the exec */
say 'x is ' x
exit 0      /* leave the exec */

To indicate an exec is NOT to be compressed, the author of the REXX exec might code the following:
```
/*%COMMENT   REXX */
Say 'This exec will not be compressed'
x = 5       /* This comment will not be removed from the exec */
say 'x is ' x
exit 0      /* leave the exec */
```
Recommendation: The REXX identifier must still be specified within a comment in the first line of any interpreted exec found in SYSPROC. Otherwise, the procedure is treated as a CLIST.
If you specify the NOCOMMENT keyword option, the NOCOMMENT keyword option, and any other options are not removed from the special comment in line 1 after compression. For example, if the initial line 1 comment contains:
```
/*% xxxxxxx yyyyyyy NOCOMMENT /*REXX*/ */
```
then after compression line 1 contains:
```
/*% xxxxxxx yyyyyyy NOCOMMENT*/
```
Note: The REXX identifier was removed from the line 1 comment because it is not a keyword option in this instance. The nested delimiter /* ended the scan for special keyword options.

If a compression indicator is specified, the exec is not scanned for the string SOURCELINE. TSO/E REXX determines whether to compress the exec based only on the value of the compression indicator.

The following are examples of using the compression indicator option. In all of these examples the exec is invoked implicitly and is found in the SYSPROC CLIST library.

Example of correct placement of the trigger character:
In the following example NOCOMMENT is a valid compression indicator option recognized by TSO/E REXX and indicates that the exec should be compressed. The string REXX is seen both as a keyword option and as the REXX REXX identifier.
```
/*% NOCOMMENT  REXX */
```
Examples of incorrect placement of the trigger character:
In each of these examples NOCOMMENT is not treated as a compression indicator option because the trigger character (%) does not immediately follow the first begin comment delimiter /*. The string REXX in the first comment is seen as a valid REXX identifier.
```
/*REXX*/  /*%NOCOMMENT */
```
```
/*REXX  /*%NOCOMMENT */ */
```
```
/* %NOCOMMENT REXX */
```
Example of specifying the compression indicator in mixed case:
In the following example the compression indicator option is specified in mixed case. The compression indicator option can be specified in uppercase, lowercase, or mixed case. The "NOcomment" indicator is a valid keyword option and indicates that the exec should be compressed. The start of the nested comment ends scanning for keyword options. The string "REXX" is seen as a REXX identifier and not as a keyword option. The words within the nested comment are not treated as keyword options.
```
/*% NOcomment       /*REXX - Remove any comment text*/ */
```
Example of using two compression keyword options:
If both COMMENT and NOCOMMENT are specified in the set of keyword options in the comment in line 1, TSO/E REXX uses the last value specified. In this example, the exec sees the last compression indicator COMMENT and the exec is not compressed.
```
/*% NOCOMMENT  COMMENT  - REXX */
```
Example of SOURCELINE that does not prevent compression:
In the following example the string SOURCELINE is not apparent in the source text of the exec because it is formed dynamically during the processing of the INTERPRET statement. Use of the COMMENT keyword option informs TSO/E REXX not to compress this exec. Without the COMMENT indicator this exec would be compressed and this would have caused the SOURCELINE built-in function to obtain a null comment, that is /**/, for the source text of line 2.
```
/*%COMMENT    REXX */
/* Second line of exec */
interpret 'line2 = SOURCE'||'LINE(2)'
if substr(line2,1,25) = '/* Second line of exec */' then
  do
    say 'Found the correct line 2 source text'
    say '... Exec executed correctly'
  end
 else
  do
    say 'Did not find correct line 2 source text'
    say '... Exec executed incorrectly'
  end
 exit 0
```
Example of a missing REXX identifier:
In this example, NOCOMMENT is specified as a keyword option but is not recognized because no REXX identifier appears in the line 1 comment. Any procedure invoked implicitly from a SYSPROC library that does not contain the REXX identifier is treated as a CLIST. Therefore, no scan for keyword options is performed and the system attempts to run this exec as a CLIST.
```
/*%NOCOMMENT      */
```
Example of incorrectly specified compression indicator:
In the following example, the NOCOMMENT indicator is not recognized. The REXX identifier should be separated from the NOCOMMENT indicator by at least one blank. TSO/E REXX views NOCOMMENTREXX NOCOMMENTOREXX as a single unrecognized exec keyword option. Note, however, the word REXX imbedded within the keyword option NOCOMMENTREXX is seen as a valid REXX identifier string.
```
/*%NOCOMMENTREXX*/
```
Rule: Avoid concatenating data sets of unlike RECFM attributes to the SYSEXEC or SYSPROC libraries or to any of the REXX exec or CLIST libraries that are defined by using the ALTLIB command. In addition, if RECFM=FB data sets are used in the library allocated to SYSEXEC, or in any exec library allocated by using the ALTLIB command, all the data sets which comprise that library concatenation should have the same LRECL. Follow these directives or various failures, including abends or loops, during REXX exec load processing, can result.