Controlling the use of specific 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.
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 use of 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.
Command rule severity levels
You can use either of the following severity levels for a rule:
- DISALLOW
- A DISALLOW rule indicates that any use of the specified restricted commands and keywords will cause the CICS translator to issue an severe error message during translation, and result in the translation completing with a return code of 12.
- WARN
- A WARN rule indicates that any use of the specified restricted commands and keywords will cause the CICS translator to issue a warning message, and result in the translation completing with a return code of 4.
Command rule formats
As described in CICS API format, 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.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.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.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.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.
- 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
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.
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.