Sunteți pe pagina 1din 8

System iNetwork Head Nav

Subscribe My Profile Contact Us Advertise


Search


Primary links
Forums Archives Code Blogs Podcasts Webcasts e-Learning Guides Newsletters About
Us Contact Us About the Network Tech Editor Profiles Editorial Calendar Writers
Kit Advertise Join Network
Categories
RPG Programming
Other Languages
Application Development
Database/SQL
Availability
Security
Systems Management
Networking/Connectivity
IT Management/Careers
Site Links
Solutions

Store

Events

Jobs

System iPortal
Home Content
Control CL Commands with Command Exit Programs -- Part 1
Article ID: 18422Posted June 19th, 2007 in RPG Programming Security Systems Mana
gement
By:Dan Riehl
Ever since the first version of the CPF operating system was shipped with the Sy
stem/38, system administrators have grappled with the problems inherent in custo
mizing the IBM-supplied CL command set. One major source of irritation was that
when a new release of the operating system was installed, any changes made direc
tly to the IBM supplied commands in the QSYS library were obliterated. So, for e
ach new operating system release, the system administrator would have to re-appl
y all of the command changes.
Over time, we all got a bit smarter and figured out that we could make a copy of
the IBM-supplied command in our own library and modify the copy. By strategical
ly placing our own library, perhaps named ALTQSYS, ahead of QSYS in the system p
ortion of the library list, we could effectively override the IBM-supplied versi
on. When a new release of the operating system was installed, it would replace t
he IBM-supplied version of the command in the QSYS library but leave our customi
zed version in our ALTQSYS intact.
Because CL commands do not often undergo fundamental changes that affect the maj
ority of us, the ALTQSYS copy of a command that was created at a previous releas
e of the operating system typically functioned correctly. However, there were ce
rtainly exceptions in which the ALTQSYS version of the commands would fail after
a new release of the operating system was installed. Still not a perfect soluti
on, but manageable.
If you examine the system portion of the library list on your System i using the
command DSPSYSVAL QSYSLIBL, you will most likely see an ALTQSYS library ahead o
f QSYS. You will often also see the name of a vendor-supplied library. Some soft
ware vendors make a habit of placing their library on your system library list a
head of QSYS in order to override the processing of the IBM-supplied command set
. This is particularly true in the case of software utility and tool vendors.
Most of us have accepted the fact that we need libraries above QSYS in our libra
ry list to support both our customized versions and vendor-supplied versions of
CL commands (and other objects). But there is an inherent danger in this scheme.
Any library existing above QSYS on the system library list can potentially open
the system to a severe security exposure -- the Trojan Horse. If a user can cre
ate or change objects in a library above QSYS, or in QSYS itself, that user can
introduce his or her own program or command that can do major damage to your sys
tem.
In an attempt to eliminate the need for libraries above QSYS, IBM, back in OS/40
0 V4R5, enabled a facility that may make it possible to remove the libraries abo
ve QSYS from the system portion of the library list. I say may because the suppo
rt provided in V4R5 deals specifically with CL command customization, but it doe
s not account for other customized objects that may need to appear before QSYS.
The enhanced support that came in V4R5 is the CL command analyzer exit points. T
hese exit points provide the ability to change the processing done by a CL comma
nd at runtime.
CL Command Exit Point Programs
CL has always had validity checking programs and command processing programs. Ov
er the years, IBM added prompt override programs, prompt choice programs, and pr
ompt control programs. V4R5 added the new support for command analyzer exit prog
rams that further enhance CL's capabilities, and more importantly, can enhance a
nd simplify your system administration, configuration, and security.
Two new exit points were added to the OS/400 registration facility (WRKREGINF) t
hat let you control the processing of CL commands. These two exit points are the
Command Analyzer Change exit point and the Command Analyzer Retrieve exit point
. This article focuses on the Command Analyzer Change exit point, the Command An
alyzer Retrieve exit point will be covered in part two in a later issue.
The Command Analyzer Change Exit Point
This exit point lets you intercept a CL command before it is executed and perfor
m your own custom processing, which could range from changing some parameter val
ues to running a totally different command in a totally different library.
As an example, if the SBMJOB command is run, you can use the exit point program
to tell the command analyzer to run the SBMJOB command found in another library
instead of the one found first on the job's library list. It is this capability
that allows us to possibly remove our libraries from the system portion of the l
ibrary list.
Here's another example that points out other possibilities and is the theme of t
he sample exit program provided in this article. If the command WRKJOB is execut
ed by someone with a user class *USER, you can, in the exit program, tell the co
mmand analyzer to run the DSPJOB command instead. Simple, but still a usable fun
ction.
This exit point opens a whole new world of possibilities for software vendors an
d System i system administrators.
When I first heard of this new capability, I assumed I would be able to add an e
xit program to a CL command using the Change Command (CHGCMD) CL command. After
all, that's how you change the command processing program and the validity check
er. Upon my first inspection of the documentation for these exit points, it beca
me clear to me that my assumption was incorrect. Over the last several releases
of OS/400 and i5/OS, IBM has really embraced the exit point registration facilit
y. The exit point programs are added to a command through the Registration facil
ity Work with Registration Information (WRKREGINF) and the Add Exit Program (ADD
EXITPGM) commands.
Exit Points and Exit Programs Revisited
An exit point is a point in an application at which an external program can opti
onally be called to perform customized processing. The OS/400 command analyzer i
ncludes exit points where you can hook your own program into the command process
ing logic. To identify your exit program, and the command for which it will be c
alled, use the ADDEXITPGM command, specifying the command name and library for w
hich this exit program will be used and the name and library of your exit progra
m that will process the particular command. When a request is made to the comman
d analyzer to run a command, the analyzer checks the exit point registry to see
whether you have an exit program assigned to the requested command. If you do, i
t calls your exit program, passing parameters that contain the information about
the requested command. Your exit program then processes that information and ta
kes the appropriate action.
Each exit point has an assigned name and an exit-point interface. The exit-point
interface is a list of input and output parameters that the command analyzer ex
changes with your exit program. The name of the exit point for the command analy
zer change command exit point is QIBM_QCA_CHG_COMMAND. This exit point occurs be
fore the command analyzer prompts the command and before the validity checking p
rogram is called. The name of the exit-point interface for this exit point is na
med CHGC0100. This exit-point interface is different than most in that your exit
program is passed the CHGC0100 interface as one big lump of data rather than in
separate parameters. Your program needs to parse out the individual data elemen
ts of the CHGC0100 parameter. In addition to the CHGC0100 parameter, your exit p
rogram is passed two additional parameters, as shown in the following table.

Parameter 1
Description
Input or Output
Values
Type and Length

Exit Point Name
Input
QIBM_QCA_CHG_COMMAND
Char 20

Exit Point Interface Format Name
Input
CHGC0100
Char 8

Command Name
Input
Name of the command for which the exit program is registered
Char 10

Command Library Name
Input
Name of the library where the Command resides
Char 10

Change Allowed Indicator
Input
0= No Change allowed
1= Change Allowed
Char 1

Command Prompt Indicator
Input
0= Command has not been prompted
1= Command has been prompted
Char 1

Reserved for future use
Input
Char 2

Offset to Original Command String
Input
The offset to the beginning of the original Command String
Binary (4)

Length of Original Command String
Input
The length of the original Command String
Binary (4)

Original Command String
Input
The original Command String before any changes
Char * (Variable Length)

Parameter 2
Replacement Command String
Output
The Command String that you want to run in place of the original command
Char * (Variable Length)

Parameter 3
Length of Replacement Command
Output
The length of the Command String that you want to run in place of the original
command
Binary (4)

As with all registered exit points, you can add your own exit point program usin
g the ADDEXITPGM command. In the case of the Change Command exit point, you need
to specify the name of the command and the library in which the command resides
in the PGMDTA parameter, as in the following example.
ADDEXITPGM EXITPNT(QIBM_QCA_CHG_COMMAND) +
FORMAT(CHGC0100) +
PGMNBR(1) +
PGM(MYLIB/WRKJOBEXIT) +
TEXT('Exit program for WRKJOB') +
PGMDTA(*JOB 20 'WRKJOB QSYS')The PGMDTA parameter must be specifie
d with a data length of 20. You must specify the command name in the first 10 po
sitions, and the command library in the next 10 positions, as in the example. Th
e command analyzer is directed to use the exit program WRKJOBEXIT in library MYL
IB whenever a request is made to run the WRKJOB command found in the QSYS librar
y.
There are certain commands for which exit point programs cannot be defined. Thes
e include CL compiler directing statements, commands found in libraries QSYS38,
and a few others. The following is a list of commands for which exit programs ca
nnot be registered.
CALLPRC
CHGVAR
CNLRCV
COPYRIGHT
DCL
DCLF

DO
ENDDO
ENDPGM
ENDRCV
GOTO
IF

MONMSG
PGM
RCVF
RETURN
SNDF
SNDRCVF

TFRCTL
WAIT
CALL
RTVxxxxxx

The next figure contains a sample exit program that you can use for the WRKJOB c
ommand. The exit program checks to see whether the user running the WRKJOB comma
nd has a user class of *USER. If so, the program tells the command analyzer to r
un the DSPJOB command instead. While the functionality of the example is quite s
imple, it does address the difficult parts of writing your own exit program.
Note: This program is written in CL syntax for V5R2 and earlier so that those wh
o have not yet upgraded to V5R3 (or higher) can still use the program. If you ar
e on V5R3 or higher, the program will still work, but you may want to update the
syntax.
Command Exit Point Program Example
--------------------------------------------------------------------------------
/* Program Name: WRKJOBEXIT */
/* Purpose: This is the exit program for the Command WRKJOB. */
/* Exit Point IS QIBM_QCA_CHG_COMMAND */
/* Parameter format for parm1 is CHGC0100. */
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
/* Copyright 2002-2007 Dan Riehl All rights reserved */
PGM PARM(&ExitInfo &NewString &Newlength)
DCL &Class *CHAR 10
DCL &OffsetDec *DEC (7 0)
DCL &CmdLenDec *DEC (7 0)
DCL &ExitInfo *CHAR 2000 /* CHGC0100 interface data */
/* Exit point interface CHGC0100 for QIBM_CA_CHG_COMMAND exit point */
/* Input parameters */
DCL &ExitPoint *CHAR 20 /* Exit Point name */
DCL &ExitFormat *CHAR 8 /* Exit Point Format */
DCL &CmdName *CHAR 10 /* Command name being executed */
DCL &CmdLib *CHAR 10 /* Command Library */
DCL &Change *CHAR 1 /* Change allowed? 1=yes 0=no */
DCL &Prompt *CHAR 1 /* Prompt requested? 1=yes 0=no */
DCL &Filler *CHAR 2 /* Reserved by IBM */
DCL &Offset *CHAR 4 /* Offset to command string */
DCL &CmdLength *CHAR 4 /* Command string length */
DCL &CmdString *CHAR 2000 /* Command String */
/* Output Parameters */
DCL &NewString *CHAR 2000 /* Replace with this command */
DCL &NewLength *CHAR 4 /* Length of new command */
/* 0 = no new command */
/* Error handling variables */
DCL &MsgID *CHAR 7
DCL &MsgFile *CHAR 10
DCL &MsgFLib *CHAR 10
DCL &MsgData *CHAR 512
MONMSG CPF0000 EXEC(GOTO ERROR)
/* Parse out the exit info data */
CHGVAR &ExitPoint %SST(&ExitInfo 1 20)
CHGVAR &ExitFormat %SST(&ExitInfo 21 8)
CHGVAR &CmdName %SST(&ExitInfo 29 10)
CHGVAR &CmdLib %SST(&ExitInfo 39 10)
CHGVAR &Change %SST(&ExitInfo 49 1)
CHGVAR &Prompt %SST(&ExitInfo 50 1)
CHGVAR &Filler %SST(&ExitInfo 51 2)
CHGVAR &Offset %SST(&ExitInfo 53 4)
CHGVAR &CmdLength %SST(&ExitInfo 57 4)
CHGVAR &CmdLenDec %BIN(&Cmdlength)
CHGVAR &OffsetDec (%BIN(&Offset) + 1) /* Set offset */
CHGVAR &CmdString %SST(&ExitInfo &OffsetDec &CmdLenDec)
IF (&Change = '0') GOTO ENDIT /* If Change is not allowed */
RTVUSRPRF USRCLS(&Class)
IF (&Class = '*USER') DO /* If a user class of *USER */
CHGVAR &NewString 'QSYS/DSPJOB'
CHGVAR %BIN(&Newlength) 11
ENDDO
ENDIT: RETURN /* Normal end of Program */
/* Error handling */
ERROR: RCVMSG MSGTYPE(*LAST) MSGDTA(&MsgData) +
MSGID(&MsgID) MSGF(&MsgFile) +
SNDMSGFLIB(&MsgFLib)
MONMSG CPF0000 EXEC(RETURN)
SNDPGMMSG MSGID(&MsgID) MSGF(&MSGFLIB/&MsgFile) +
MSGDTA(&MsgData) MSGTYPE(*ESCAPE)
MONMSG CPF0000 EXEC(RETURN)
ENDPGM
--------------------------------------------------------------------------------
Examining the WRKJOB Command Exit Program
You can see that the exit program receives the three parameters that were discus
sed previously. As mentioned, the first parameter contains a CHGC0100 data struc
ture that must be parsed into its individual fields. Then the fields that will b
e used to store the CHGC0100 format data once it is parsed are defined. The CHGC
0100 format is then parsed into its component parts. In this example, some extra
work is done to parse the command string and to determine the offset to the com
mand. While the sample doesn't need nor use this information, the code is provid
ed for instructional purposes so that you can use this section as a template to
write your own exit programs.
Next, the change indicator is queried to determine whether the command is change
able by the exit program. If a command is library-qualified when it is passed to
the command analyzer, as in the command QSYS/WRKJOB, it is not changeable by th
e exit program and the change indicator will have a value of '0'. There are a fe
w other occasions when a command cannot be changed, these consist of commands th
at
have a parameter defined with RTNVAL(*YES), for example all CL retrieve (RTVxxxx
) commands
have parameters defined with DSPINPUT(*NO) or DSPINPUT(*PROMPT)
are running in a System State program
Back in V4R5, IBM introduced the new qualifier value of *SYSTEM. The purpose of
this new qualifier was to allow a sort of "non-qualified" qualified reference to
an object. For example, if a command is specified as *SYSTEM/WRKJOB, the WRKJOB
command in the QSYS library will be used. The *SYSTEM qualifier gets the object
from QSYS, while not explicitly identifying QSYS. If you want to qualify comman
ds in your applications and still want to use exit programs to change the comman
ds, use the *SYSTEM qualifier, which under the covers will actually be a qualifi
cation to library QSYS.
In the next piece of code, the replacement command is set to QSYS/DSPJOB if the
user running the WRKJOB command has a user class of *USER. The exit program then
ends.
You may notice that CL variables used in the exit program to store command strin
gs are 2,000 bytes long. Prior to V5R3, CL character variables could not be long
er than 2,000 bytes; now the CL limit is 9,999. While 2,000 bytes is certainly s
ufficient to hold the WRKJOB command string in this example, the actual length o
f a command string that can be processed through the exit point interface is 32,
000 bytes.
The sample program is written in CL in an attempt to make the exit program simpl
e to read and understand. Exit programs do not need to be written in any particu
lar language, and although they can be, do not need to be written for ILE.
The Exit Point
Hopefully this walk-through and example code will be helpful to you. This capabi
lity to control commands at runtime opens realms of possibilities in application
development and system administration. Try this out on a few commands that you
want to customize and you may find that you can remove a library or two that sit
above QSYS on your system library list. Wouldn't that be worth the time and eff
ort?
In part two of this series I will cover the Command Analyzer Retrieve Command ex
it point.
Bookmark/Search this post with:
Email this page Printer-friendly version Post new comment
Your name:
E-mail:
The content of this field is kept private and will not be shown publicly.
Comment: *
Web page addresses and e-mail addresses turn into links automatically.
Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
Lines and paragraphs break automatically.
More information about formatting options

Math Question: * 19 + 0 =
Solve this simple math problem and enter the result. E.g. for 1+3, enter 4.


Related Links
Managing Restricted Commands
Killer Club Tech
Killer Club Tech
Tech Tips
Killer Club Tech
ProVIP Sponsors
ProVIP Sponsors
Featured Links
IT Leaders Forum - Gartner, IBM, and more in Denver.
Sponsored Links
GO GREEN: Reduce energy cost & data center space. Get IBM's free eKit.
Automate iSeries Report Distribution as PDF, Excel, Forms... Try it Free!.
Replacing Query/400? View "Elevator, Act 1" with Randall Munson.
Hear how your peers have evolved their legacy apps with RAMP from LANSA
Modernize CA 2E and CA Plex applications automatically -- ADC Austin
Modernize to J2EE/JSF/RPGILE- with X-Analysis & Rational Webinar
Footer Site Links
Home Subscribe Now Advertise Contact Us Feedback Terms & Conditions Trademarks P
rivacy Policy Copyright Penton Media

S-ar putea să vă placă și