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 IT Mgmt/Careers Site Links Solutions Store Events UK Centre Jobs System iPortal Home Content Control CL Commands with Command Exit Programs - Part 2 Article ID: 55130Posted July 16th, 2007 in RPG Programming Systems Management By:Dan Riehl Do you want to be alerted when someone tries to restore objects onto your system , starts a TCP/IP server program, or saves a particular library? In the past, it was difficult to collect these events in realtime, but with the i5/OS capabilit y to monitor for sensitive commands, collecting these events becomes a rather tr ivial task. In part one of this series, I focused on the exit points available for CL comman ds, and dealt specifically with the Change Command exit point (article ID 54958 at SystemiNetwork.com). As noted in that article, another exit point can be used to monitor and audit commands as they are executing. This is the Command Analyz er Retrieve exit point. This capability lets you capture commands as they execute and use the informatio n that you collect. Unlike the Command Analyzer Change exit point discussed last month, the Command Analyzer Retrieve exit point does not let you send informati on back to the command analyzer. This limits the capabilities of this exit point to essentially only a logging and auditing exit point. The example program in this article is called whenever someone executes the Rest ore Object (RSTOBJ) command. The program retrieves the command information and r ecords the RSTOBJ command string and other useful information in the system's QH ST history log. You can certainly do other things with the command string data, but the purpose of this simple example is to illustrate the process of creating and registering a CL command exit program.

The Command Analyzer Retrieve Exit Point Each IBM-supplied exit point has an assigned name and an exit-point interface. T he exit-point interface is a list of parameters that the command analyzer exchan ges with your exit program. The name of the exit point for the Command Analyzer Retrieve command exit point is QIBM_QCA_RTV_COMMAND. This exit point occurs afte r the command analyzer has done much of its work but before control is passed to the Command Processing Program (CPP). Because this exit program is called before the CPP, the exit program cannot pred ict whether the command will complete normally or abnormally. It only knows that the command is being attempted, with no knowledge of, or potential impact on, t he outcome of the CPP (i.e., whether the operation will fail or succeed). The name of the exit-point interface for this exit point is named RTVC0100. This exit-point interface is similar to the CHGC0100 interface discussed in the last issue. The exit program is passed the RTVC0100 interface as one big lump of dat a. Your program needs to parse out the individual data elements of the RTVC0100 parameter as illustrated in Figure 1. Figure 1: The Retrieve Command Exit-Point Interface

Parameter 1

Description Values Type and Length Exit Point Name QIBM_QCA_RTV_COMMAND Char 20 Exit Point Interface Format Name RTVC0100 Char 8 Command Name Name of the command for which the exit program is registered Char 10 Command Library Name Name of the library where the command resides Char 10 Reserved for Future Use Char 4 Offset to original Command String

The offset to the beginning of the original command string Binary (4) Length of Original Command String The length of the original command string Binary (4) Offset to Replacement Command String The offset to the beginning of the replacement command string if the command wa s changed by the Change Command exit point. Otherwise, the value is 0. Binary (4) Length of Replacement Command String The length of the replacement command string if the command was changed by the Change command exit point. Otherwise, the value is 0. Binary (4) Original Command String The original command string before any changes Char * (Variable Length) Replacement Command String The command string that you want to run in place of the original command Char * (Variable Length) As with all registered exit points, you can add your own exit point program usin g the Add Exit Program (ADDEXITPGM) command. In the case of the Retrieve Command exit point, you need to specify the name of the command and the library in whic h the command resides in the PGMDTA parameter. For the Retrieve command exit poi nt, you can register up to 10 programs per command, incrementing the PGMNBR para meter for each consecutive program. This lets you run a sequence of programs, a third party, or vendor-supplied exit program and still run your own program. ADDEXITPGM EXITPNT(QIBM_QCA_RTV_COMMAND) + FORMAT(RTVC0100) + PGMNBR(1) + PGM(MYLIB/RSTOBJEXIT) + TEXT('Exit program for RSTOBJ') + PGMDTA(*JOB 20 'RSTOBJ 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. The command analyzer i s directed to use the exit program RSTOBJEXIT in library MYLIB whenever a reques t is made to run the RSTOBJ command found in the QSYS library. Figure 2 contains a sample exit program that can be used for the RSTOBJ command. The sample is written in pre-V5R3 CL syntax, so it can be used by all readers o n V5R4 and higher. The exit program sends a message to a message queue each time the RSTOBJ command is used. It also sends a message to the QHST history log. Th e processing performed in this program is quite simple, however it does provide a template that you can use to create your own program. Note that this exit program is registered to monitor for the usage of only the R STOBJ command. However, you can use the same program to monitor for all RSTxxx c ommands by adding the same exit point program (ADDEXITPGM) for each RSTxxx comma nd (e.g., RSTLIB, RST, RSTLICPGM, etc).

Figure 2: Command Exit Point Program Example -------------------------------------------------------------------------------/* /* /* /* /* /* PGM Program Name: RSTOBJEXIT */ Purpose: This is the exit program for the Command RSTOBJ. */ Exit Point is QIBM_QCA_RTV_COMMAND */ Parameter format is RTVC0100. */ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */ Copyright 2007 Dan Riehl, All rights reserved */ PARM(&ExitInfo) *Char 2000 *Char *Char 10 10 /* RTVC0100 Interface Data */

DCL &Exitinfo DCL &User DCL &JobName DCL &OffsetDec DCL &CmdLenDec

*Dec (7 0) *Dec (7 0) point */ */ */ */ */ */ */ */ */ */ */

/* Exit point interface RTVC0100 for QIBM_CA_RTV_COMMAND exit 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 &OffsetO *CHAR 4 /* Offset to command string DCL &CmdLengthO *CHAR DCL &OffsetR *CHAR DCL &CmdLengthR *CHAR DCL &CmdString /* Error handling DCL &MsgID DCL &MsgFile DCL &MsgFLib DCL &MsgData MONMSG CPF0000 4 4 4 /* Command string length /* Offset to command string /* Command string length /* Command String

*CHAR 2000 variables *CHAR 7 *CHAR 10 *CHAR 10 *CHAR 512

EXEC(GOTO ERROR) */ 1 20) 21 8) 29 10) 39 10) 53 4) 57 4) 61 4) 65 4)

/* Parse out CHGVAR CHGVAR CHGVAR CHGVAR CHGVAR CHGVAR CHGVAR CHGVAR

the exit info data &ExitPoint %SST(&ExitInfo &ExitFormat %SST(&ExitInfo &CmdName %SST(&ExitInfo &CmdLib %SST(&ExitInfo &OffsetO %SST(&ExitInfo &CmdLengthO %SST(&ExitInfo &OffsetR %SST(&ExitInfo &CmdLengthR %SST(&ExitInfo

/* Check to see whether command was replaced by Change Command Exit */ IF (%BIN(&OffsetR) = 0) DO /* Command not replaced */ CHGVAR &CmdLenDec %BIN(&CmdlengthO) CHGVAR &OffsetDec (%BIN(&OffsetO) + 1) /* Set offset */ ENDDO ELSE DO /* Command was replaced */ CHGVAR &CmdLenDec %BIN(&CmdlengthR)

CHGVAR &OffsetDec (%BIN(&OffsetR) + 1) /* Set offset */ ENDDO CHGVAR &CmdString %SST(&ExitInfo &OffsetDec &CmdLenDec) RTVJOBA JOB(&JobName) USER(&User)

SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Restore + operation in progress from user' *BCAT + &User *BCAT 'from job' *BCAT &JobName + *TCAT '. The command executed is:' *BCAT + &CmdString) TOMSGQ(RESTORE QHST) 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 RSTOBJ Command Exit Program The exit program receives only one parameter. As previously mentioned, this para meter contains the RTVC0100 data structure that must be parsed into its individu al fields. In Figure 2, the fields defined are those that will be used to store the RTVC0100 format data after it is parsed. Then the RTVC0100 format is parsed into it's component parts. Next, a determination is made as to whether the original command was replaced by a Command Analyzer Change exit program. If it was replaced, the command string that is being executed is found at the offset stored in the variable &OFFSETR, o therwise the offset to the command is found in the variable &OFFSETO. As you can see, the determination is made by checking the replacement offset (&OFFSETR) fo r a value of zero. If the replacement offset is zero, the command was not replac ed by a Command Analyzer Change exit program. Later in the code, the User and Job name are retrieved from the job running the RSTOBJ command. This information is collected so that it can be included in the informational message that is sent. The message is sent to the message queues RE STORE and QHST. You can replace these in the code to suit your individual requir ements. Figure 3 shows the resulting Display Messages screen after a few RSTOBJ commands are executed. The same information is written to the QHST history log to help a udit for the use of the RSTOBJ command. Figure 3: Resulting Display Messages Screen -------------------------------------------------------------------------------Display Messages Queue . . . . . : Library . . . : RESTORE QUSRSYS System: MYAS400 Program . . . . : *DSPMSG Library . . . :

Severity . . . :

00

Delivery . . . :

*BREAK

Type reply (if required), press Enter. Restore operation in progress from user TESTUSER from job QPADEV0013. The command executed is: RSTOBJ OBJ(QXXXXX) SAVLIB(MYLIB) DEV(*SAVF) SAVF(MYSAVF). Restore operation in progress from user ANYUSER from job QPADEV0015. The command executed is: RSTOBJ OBJ(QCLSRC) SAVLIB(YOURLIB) DEV(*SAVF) SAVF(ANYSAVF). Restore operation in progress from user QSYSOPR from job QPADEV0010. The command executed is: RSTOBJ OBJ(MYPROGRAM) SAVLIB(QGPL) DEV(*SAVF) SAVF(OPERSAVE). Bottom F3=Exit F11=Remove a message F12=Cancel F13=Remove all F16=Remove all except unanswered F24=More keys -------------------------------------------------------------------------------Time to Exit? IBM has added numerous exit points over the last several releases. As you become familiar with command exit points and the customized processing that you can pe rform, you may want to delve further into more of the exit points. There are exi t points for all kinds of things including Save and Restore functions, User Prof ile maintenance, and Network Access Control for functions such as FTP, ODBC, rem ote commands, and more. Third party software is often available for those of us that do not want to write and maintain dozens of exit programs. You can use exit point programs to make your system administration tasks easier than they might have been in the past. Bookmark/Search this post with: Email this page Printer-friendly version Related Links IBM-Supplied Help Text Generator for User-Written Commands Enhance Security with CL Command Exit Point Programs Managing Restricted Commands Having Problems Passing Parameter Variables Using SBMJOB? Killer Club Tech ProVIP Sponsors ProVIP Sponsors

Featured Links IT Leaders Forum - Gartner, IBM, and more in Denver. Sponsored Links Modernizing Apps to the Web is way Easier & more Affordable with BCD's WebSmart! Hear how your peers have evolved their legacy apps with RAMP from LANSA Replacing Query/400? View "Elevator, Act 1" with Randall Munson. 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