Controlling the use of CICS API and SPI commands

The CICS® translator can help you govern the commands used in application programs at development time. You can use this function to restrict the use of specific CICS API and SPI commands in application programs, as an additional means of enforcing coding standards in application development.

Note: This function applies only to CICS API and SPI commands. It does not apply to EXEC CICS GDS, EXEC DLI, EXEC CICS FEPI, and EXEC CPSM commands. It does not apply to programs that are interpreted, such as REXX execs.

About this task

The CICS translator uses a PARMLIB member to enforce rules that identify restricted commands and keywords. This parmlib member must be named DFHAPIR. It is not possible to identify this member in the JCL that is used to compile or translate application programs. It can only be detected and used from PARMLIB. The lack of authorization to read PARMLIB, or the absence of a DFHAPIR PARMLIB member, means that no rules are used and the full set of commands are translated without any restriction.

During translation, the CICS translator detects any restricted commands and keywords in the source programs and issues warning or error messages based on the severity level that is used in a rule.

CICS mandates that the SDFHLOAD library must not be APF-authorized. The CICS translator uses z/OS® services to read the DFHAPIR member. Use of those services will result in a U0101 abend if SDFHLOAD is APF-authorized.

Command rule severity levels

You can use either of the following severity levels for a rule:

DISALLOW: Indicates that any use of the specified restricted commands and keywords causes the CICS translator to issue an severe error message during translation and the translation completes with a return code of 12.
WARN: Indicates that any use of the specified restricted commands and keywords causes the CICS translator to issue a warning message and the translation completes with a return code of 4.

Important: DISALLOW cannot be overridden by WARN. If DISALLOW is set for a command, then WARN statements for the same command or any subset of the same command will have no effect and only DISALLOW will be used.

Command rule formats

Syntax

As described in EXEC CICS command format and programming considerations, the general format of a CICS command is EXEC CICS command option(arg)...., and, in terms of the command rule format, EXEC CICS verb [adverb] [keyword] [keyword()]....

So command refers to either a verb or a verb adverb. Typically, an adverb is used where there are several commands with the same verb (for example, WRITEQ TD and WRITEQ TS).

keyword refers to options and data values specified with a command.

You can code DISALLOW and WARN rules in any of the following formats:

DISALLOW | WARN verb

Detects the use of a given verb in the source programs, for example:

DISALLOW DELETEQ

This specification disallows use of EXEC CICS DELETEQ, including both EXEC CICS DELETEQ TD and EXEC CICS DELETEQ TS. In case of detection, an error message will be issued, and the translation will fail.

DISALLOW SET

This specification disallows use of EXEC CICS SET, which means that all CICS SPI SET commands are prevented from use in application programs. In case of detection, an error message will be issued, and the translation will fail.

DISALLOW | WARN verb adverb

Detects the use of a given verb adverb pair in the source programs, for example:

WARN WRITEQ TS

This specification warns about the use of EXEC CICS WRITEQ TS. In case of detection, a warning message will be issued.

DISALLOW | WARN verb keyword

Detects the use of a particular keyword on a command in the source programs, for example:

Example:

WARN CONVERTTIME DATESTRING

This specification warns about use of any EXEC CICS CONVERTTIME command that contains the DATESTRING keyword. In case of detection, a warning message will be issued.

DISALLOW | WARN verb adverb keyword

Detects the use of a particular keyword on a command with an adverb in the source programs, for example:

DISALLOW LINK PROGRAM SYSID

This specification disallows use of the SYSID keyword on EXEC CICS LINK commands. In case of detection, an error message will be issued, and the translation will fail.

Any rule which specifies a verb, adverb or keyword that is not recognized by the translator is ignored.

An unlimited number of comment lines can be specified in the parmlib member. Use an asterisk character (*) at the start of a line to indicate a comment line.

Important:

The restricted commands parmlib member should contain a maximum of 100 DISALLOW and WARN rules. If more than 100 DISALLOW and WARN rules are specified, only the first hundred rules are read and used by the CICS translator.
The restricted commands parmlib member must use a fixed record length of 80. The rule text must be contained within the first 72 characters.
The restricted commands parmlib member must be coded in EBCDIC.

Procedure

Define restricted commands and keywords by specifying DISALLOW and WARN lines in the restricted commands parmlib member DFHAPIR.
Ensure that the restricted commands member is in a parmlib that was used in the IPL of the system.

For example, it can be included in the LOADxx member of SYS1.PARMLIB.

For information about the parmlib concatenation (logical parmlib), see Using parmlib concatenation (logical parmlib) in z/OS Planning for Installation.

By default, the command rules apply to every user on the LPAR. If you need to exempt some users or LPARs, you need to define profiles for the DFHAPIR parmlib member to RACF®. Continue with step 3.

Optional: Define FACILITY class profiles for the DFHAPIR parmlib member to RACF.

For example, you can set up a general profile DFHAPIR.** with UACC(NONE) to enforce the rules on all LPARs and all users, and use an access list to grant exempt users READ access to the profile if required. You can also set up DFHAPIR.lpar profiles where lpar is the four-character LPAR name to enforce the rules on particular LPARs.

For instructions, see API and SPI restrictions DFHAPIR parmlib member.

Results

The CICS translator attempts to read a DFHAPIR member. If a DFHAPIR member is not found, informational message IEF764I is issued. If a DFHAPIR member is found, informational message IEE252I is issued stating in which PARMLIB the member was located.

If a DFHAPIR member is found, the CICS translator reads the list of restricted commands and keywords defined and uses this list to check program source during translation. If a DFHAPIR member is not found, no restrictions are applied.

The check is performed only when a source program is being translated, and does not affect translated programs. If you want to ensure compliance by all application programs, you need to recompile your programs.