Using REXX EXECs

The user can call REXX EXECs, and Control-M JCL Verify functions and variables can be used in the REXX EXEC for site standards and enforcement.

This chapter includes the following topics:

Call Format

The following formats can be used to call the REXX EXEC for site standards and enforcement:

  • Function call

    Copy 
    var = CTJRXX("function","%%variable = value")

  • ADDRESS

    Copy 
    ADDRESS JVER("function","%%variable = value")

  • The function call format is mandatory for the initial call CTJRXX("INIT"), since it sets up the support for ADDRESS JVER format. After the initialization, either format can be used.

  • The following functions are supported only under ENFORCEMENT rules:

    ENFORCE, IBEFORE, IAFTER, DELREC

Tab.JV.5.1 REXX EXEC call functions

Function

Description

INIT

Initiates the JVER environment under the REXX environment.

Format:

Copy 
I = CTJRXX("INIT")

SETVAR

Sets local variables, which can be used later in other DO REXX actions or even in any other DO action.

Formats:

Copy 
S = CTJRXX("SETVAR","%%A = B")
ADDRESS JVER "SETVAR %%A = B"

SYSINREAD

Reads data from SYSIN statements (in-stream, PDS members, and sequential files).

Formats:

Copy 
S = CTJRXX("SYSINREAD","varname lines start")

where

varname - is the name of the stem variable

               After the execution:

               %%varname.0 - holds the number of records read

               %%varname.1 - holds the first data record (80 chars)

lines - maximum number of lines to read

start - number indicating the first line to read

To read the entire SYSIN, “lines start” can be omitted and the following call can be used:

Copy 
S = CTJRXX("SYSINREAD","varname")

The function returns the following return codes:

  • 0 - Success

  • 4 - Some of the data was read but one or more of the concatenated datasets were not available, did not exist, or the LRECL was different than 80

  • 8 - No data was read (e.g. empty SYSIN, none of the concatenated datasets could be accessed)

  • 16 - Error

  • The SYSIN statements will become available in the ON DDSYSIN invocations only.

  • ON DDSYSIN will be invoked once for each DD name instead of for each DD statement (therefore concatenated DD statements will be processed in one single rule invocation).

  • The entire SYSIN, which includes all the concatenated datasets, will be accessible as a whole in the rule itself.

  • Only datasets with LRECL=80 (sequential and PDS members) are supported, besides in-stream (DD *) statements.

Copy 
 S = CTJRXX("SYSINREAD","DAT")
 If S >= 8 then
  CTJRXX("DOMSG","SYSIN READ FAILED")
 Else 
  DO I = 1 TO DAT.0
      Say DAT.I
   END

DOMSG

Issues a JVER message in the JVER report, similar to DO MSG in the site standards.

Formats:

Copy 
M = CTJRXX("DOMSG","<severity>","<text>")
ADDRESS JVER "DOMSG <severity> <text>"

where:

  • severity can be I (information), W (warning), or E (error)

  • text is the message that is added to the output

ADJMSG

Suppresses JVER messages or changes their severity in a dynamic manner.

Formats:

Copy 
M = CTJRXX("ADJMSG","<msgid>","<suppress>","<severity>")
ADDRESS JVER "ADJMSG <msgid> <suppress> <severity>"

where:

  • msgid is the 7-character message ID for the Control-M JCL Verify message that you want to adjust. The message ID must begin with CTJ*.

  • suppress - whether to suppress the message, either Y (yes) or N (no)

  • severity - adjusted level of severity for the message: E (error), W (warning), or I (information)

If suppress is set to Y, severity is not required (and, if specified, is ignored).

DORC

Sets the JVER return code (RC) and reason code (RS) of the JVER report, similar to DO RETURN in the site standards.

Formats:

Copy 
R = CTJRXX("DORC","8","0")
ADDRESS JVER "DORC 8 A"

RESOLVE

Resolves a local, system, or data variable, and gets its value.

Format:

Copy 
A = CTJRXX("RESOLVE","%%A")

ENFORCE

Assigns a value to a variable. Applicable only for enforcement rules and the enforcement process.

Format:

Copy 
S = CTJRXX("ENFORCE","%%X=B")
ADDRESS JVER "ENFORCE %%X = B"

Where %%X is a user defined variable or global AutoEdit variable.

The variables that can be set are only those that belong to the current statement.

IBEFORE

Insert a new record before the current statement. Applicable only for enforcement rules and the enforcement process.

Format:

Copy 
S = CTJRXX("IBEFORE","rec")
ADDRESS JVER "IBEFORE rec"

Where rec is the new record to be inserted, limited to the first 72 characters.

IAFTER

Insert a new record after the current statement. Applicable only for enforcement rules and the enforcement process.

Format:

Copy 
S = CTJRXX("IAFTER","rec")
ADDRESS JVER "IAFTER rec"

Where rec is the new record to be inserted, limited to the first 72 characters.

DELREC

Deletes the current statement. Applicable only for enforcement rules and the enforcement process.

Format:

Copy 
S = CTJRXX("DELREC")
ADDRESS JVER "DELREC"

Example 1

In the following example, REXX user exit is initiated and then the jobname is retrieved with the RESOLVE function. When the jobname is K68 the following message is printed out: INFORMATION: THE JOBNAME IS K68.

Fig.JV.5.1 Example 1 of REXX call

Copy 
/* REXX  */
I = CTJRXX("INIT")
A = CTJRXX("RESOLVE","%%$JOBNAME")
IF A = "K68" THEN DO
 M = CTJRXX("DOMSG","I","THE JOBNAME IS K68")
END
RETURN

Example 2

The index values %%$JCLCURF and %%$JCLCURL can be used to access the JCL cards of the current JCL statement by combining %%$JCL with the index as in the following REXX sample:

Fig.JV.5.2 Example 2 of REXX call

Copy 
 /* REXX */
 INIT = CTJRXX("INIT")
 REC_NUM = CTJRXX("RESOLVE","%%$JCLCURF")
 LAST = CTJRXX("RESOLVE","%%$JCLCURL")
 DO WHILE REC_NUM <= LAST
   TEMP = CTJRXX("RESOLVE","%%$JCL"REC_NUM)
   SAY TEMP
   REC_NUM = REC_NUM + 1
END
RETURN

Example 3

Using %%$ORIGIN we can verify if the parameters were added by the user, as shown in the following REXX sample:

Fig.JV.5.3 Example 3 of REXX call

Copy 
 /* REXX */
 INIT = CTJRXX("INIT")
 REC_NUM = CTJRXX("RESOLVE","%%$JCLCURF")
 LAST = CTJRXX("RESOLVE","%%$JCLCURL")
 DO WHILE REC_NUM <= LAST
   TEMP = CTJRXX("RESOLVE","%%$JCL"REC_NUM)
   SAY TEMP
   REC_NUM = REC_NUM + 1
END
RETURN

Example 4

In the following example, REXX user exit is initiated and then the program name and DD card name are retrieved with the RESOLVE function. When the DD name is TTCNTL and it is used under PGM=IEF000, message CTJD05W, "DSN not found," is suppressed.

Fig.JV.5.4 Example 4 of REXX call

Copy 
/* REXX  */
I = CTJRXX("INIT")
PGM = CTJRXX("RESOLVE","%%$EXECPROG")
DDNM = CTJRXX("RESOLVE","%%$DDNAME")
IF PGM = "IEF000" AND DDNM = "TTCNTL" THEN DO
M = CTJRXX("ADJMSG","CTJD05W","Y","I")
END
RETURN