CMDEXIT How to Do a Command Exit

CMDEXIT HOW TO DO A COMMAND EXIT TAACMEM
The system supports the capability (as of V4R5) to retrieve a command that is about to be run or to change a command that is about to be run. This function provides significant capability, but there are important considerations. The exit program cannot be used to guarantee all command usage will be changed and you can expose yourself to errors by using an exit program. This tool is a documentation member plus sample source in a CL member on how to do an Exit program. The code shown handles the case where you want to ensure that a parameter value is not used. You can provide an Exit program for most commands with the major exceptions being: ** Any 'CL compiler only' command (such as DCL, ENDDO, RCVF) and any RTV command that returns a value (such as RTVJOBA). ** The CALL command. There are a few significant considerations when you use an Exit program: ** If the user specified a command with a library qualifier, you cannot change it. For example, CRTxxx can be changed, but QSYS/CRTxxx cannot. The intent of this is to allow system code that uses CL commands to run without modification, but it also allows a 'back door' for users who want to bypass your change function. In addition to system commands, you cannot change a user command if it is library qualified. ** When you change the operation of a command, you are exposed to problems caused by running code written by other individuals that are not aware of any potential changes. The system protects against this by library qualifying all command use in its CL programs. TAA Tool commands do not always use library qualifiers within CL programs. Other products and code that you have written yourself or picked up from outside sources will also not be aware of your changes. ** Your exit program will only be called once. If the command is prompted for, your exit program will gain control and should change and protect the prompted version. If you don't protect the parameter (prevent it from being changed by the ?* function), the user could overkey and defeat your intention. Your exit program is not called again when the command is run. The example code shows how to provide this protection. ** You cannot send an escape message and get the command to fail. The system monitors for any escape messages sent and ignores them. Consequently, if you are attempting to use the function to prevent the use of a certain command or parameter, you can only change a parameter or change to a different command. For example, you could run the TAA NOOP command. If you want to send an escape message and prevent the use of the command, see the later discussion of the SNDESCMSG4 command. In order to have the system invoke your Exit program, you must 'register' the request with the ADDEXITPGM command. See the later discussion. Retrieve Exit ------------- The 'Retrieve' function allows you to determine that a command is being run. This function may not seem very exciting, but you could use it to: ** Prevent the use of a command or prevent the use by a specific user. ** Log the fact that a specific command occurred. This is the same function you can get with object level auditing which only requires commands to invoke (not writing a program). ** Log a command if a particular parameter value was used. You could also do this using object level auditing plus a program that scanned for the parameter use. ** Notify someone immediately that a command or parameter was being used. Note that it is too late to stop the command from running. If you want to write a Retrieve Exit, follow the example provided with this tool for the Change Exit along with the system documentation for the 'Command Analyzer Retrieve Exit Program'. Change Exit ----------- The 'Change' function is where the real meat is. For example, you could add or change a parameter value, or use a totally different command. Remember, however, that there are exceptions and considerations as described earlier. The Exit program is not a 'fail safe' form or protection. Reading about the details ------------------------- You can read about the Exit programs by using the Info Center CD and successively clicking on: - Programming - CL and APIs - APIs - APIs by Category - Program and CL Command Then roll to the section on 'Exit Programs'. Look at the details of: - Command Analyzer Change - Command Analyzer Retrieve Change Example -------------- Registering the Exit -------------------- If you want to use a Change Exit, you probably want to practice on a command that is unlikely to be used until you get familiar with the process. For this reason, the example code uses the CRTDKTF command and prevents the user from using FILETYPE(*DATA) which is the default. Instead, the example exit program changes all CRTDKTF commands to FILETYPE(*SRC). While this is an 'academic example', it is typical of what many users may want to do. You need to register your Exit program for the command you want to change. Because you can have multiple Exit programs, the system uses the PGMNBR parameter to provide a unique ID. To allow for inserting a later exit, you might assign a value such as 50 to begin with. As QSECOFR (or a user with security rights), enter the ADDEXITPGM command. The name of your exit program goes in the PGM parameter. The example requests the program be called whenever the CRTDKTF command in QSYS is used. ADDEXITPGM EXITPNT(QIBM_QCA_CHG_COMMAND) FORMAT(CHGC0100) PGMNBR(n) PGM(yyy/xxx) CRTEXITPNT(*YES) PGMDTA(*JOB 20 'CRTDKTF QSYS ') If you want to remove an Exit, use the RMVEXITPGM command such as: RMVEXITPGM EXITPNT(QIBM_QCA_CHG_COMMAND) FORMAT(CHGC0100) PGMNBR(n) You can only have one change exit per command. There is also a WRKREGINF command that will let you see what is registered. You will find lots of system function is already registered. In fact, the Exit points for CHG and RTV are already in the list, but may not have any programs. Use Option 8 to 'Work with exit programs'. A list of the programs is displayed along with the unique PGMNBR value you assigned. Removing is easy here, but adding is more difficult because you cannot re-prompt the command in case of errors. You may prefer to use command entry when you want to do an Add. Writing the Exit program ------------------------ The 'Change Exit' documentation (on the Info CD) describes the details of how to code the exit. The exit program gets called in the following situations: ** Prompting the command ** Performing interparmeter checks ** Calling the validity checker program ** Transferring control to the command processing program (CPP) but the program is only called once. This means if the command is prompted, has a validity checker, and is run, your program will only get one shot at changing the command. Since prompting would occur first, that is when your exit program will gain control. If the command is prompted, you can insert your value before the prompter displays the value, but you will want to make sure that the operator cannot change your value. The example code provides for this. The exit program receives a standard parameter list that includes the command name and any parameters along with the keyword names. A return parameter is used for the command to be run. If you want to send an escape message from the exit, a discussion exists in the example as well as a 'commented out' line of code. See the later discussion on SNDESCMSG4. The example code is fairly standard if you have the same requirement of forcing the use of a command parameter value. The example assumes that you always want CRTDKTF to use FILETYPE(*SRC) instead of the default of FILETYPE(*DATA). Note that CHGCMDDFT will allow you to change the default of a command, but you cannot enforce its use. The sample Change Exit will enforce the use of *SRC (unless the command is qualified as QSYS/CRTDKTF as described earlier). Your requirements could be different in which case you will need to make several changes to the example code. You can view the example code with the command: DSPTAA TAACMEMC You can copy this code to your source file and member by specifying: CPYTAA TAAARCMBR(TAACMEMC) TOMBR(xxx) TOSRCFILE(yyy/zzz) SNDESCMSG4 for sending an escape message ---------------------------------------- The system monitors for any escape messages sent from the Command Exit program and ignores them. Consequently, you cannot use SNDPGMMSG or a TAA command like SNDESCMSG to cause an escape message that will prevent the use of the original command. You cannot return with a different command that is a CALL to a program that will send an escape message because CALL is prevented as a return command. You can however, use a different command from what was entered that invokes a CPP that sends an escape message to cause the original command to fail. This is the purpose of the TAA command SNDESCMSG4. You must build up this command as a string and then use it as the replaced command. The function exists in the example code, but the branch to the function is 'commented out'. SNDESCMSG4 sends the TAA1020 message from TAAMSGF in TAATOOL. The second level text identifies it as coming from SNDESCMSG4. Prerequisites ------------- None, but the following TAA Tools are used in the example. SCNVAR Scan variable SCNVARRGT Scan variable from the right SNDAUDE Send audit entry SNDESCMSG4 Send escape message 4 Implementation -------------- None, this is only a documentation tool. Objects used by the tool ------------------------ Object Type Attribute Src member Src file ------ ---- --------- ---------- ---------- TAACMEMC QATTCL Only source is provided for the example.


CMDEXIT HOW TO DO A COMMAND EXIT TAACMEM
The system supports the capability (as of V4R5) to retrieve a command that is about to be run or to change a command that is about to be run. This function provides significant capability, but there are important considerations. The exit program cannot be used to guarantee all command usage will be changed and you can expose yourself to errors by using an exit program. This tool is a documentation member plus sample source in a CL member on how to do an Exit program. The code shown handles the case where you want to ensure that a parameter value is not used. You can provide an Exit program for most commands with the major exceptions being: Any 'CL compiler only' command (such as DCL, ENDDO, RCVF) and any RTV command that returns a value (such as RTVJOBA). The CALL command. There are a few significant considerations when you use an Exit program: If the user specified a command with a library qualifier, you cannot change it. For example, CRTxxx can be changed, but QSYS/CRTxxx cannot. The intent of this is to allow system code that uses CL commands to run without modification, but it also allows a 'back door' for users who want to bypass your change function. In addition to system commands, you cannot change a user command if it is library qualified. When you change the operation of a command, you are exposed to problems caused by running code written by other individuals that are not aware of any potential changes. The system protects against this by library qualifying all command use in its CL programs. TAA Tool commands do not always use library qualifiers within CL programs. Other products and code that you have written yourself or picked up from outside sources will also not be aware of your changes. ** Your exit program will only be called once. If the command is prompted for, your exit program will gain control and should change and protect the prompted version. If you don't protect the parameter (prevent it from being changed by the ?* function), the user could overkey and defeat your intention. Your exit program is not called again when the command is run. The example code shows how to provide this protection. You cannot send an escape message and get the command to fail. The system monitors for any escape messages sent and ignores them. Consequently, if you are attempting to use the function to prevent the use of a certain command or parameter, you can only change a parameter or change to a different command. For example, you could run the TAA NOOP command. If you want to send an escape message and prevent the use of the command, see the later discussion of the SNDESCMSG4 command. In order to have the system invoke your Exit program, you must 'register' the request with the ADDEXITPGM command. See the later discussion. Retrieve Exit ------------- The 'Retrieve' function allows you to determine that a command is being run. This function may not seem very exciting, but you could use it to: Prevent the use of a command or prevent the use by a specific user. Log the fact that a specific command occurred. This is the same function you can get with object level auditing which only requires commands to invoke (not writing a program). Log a command if a particular parameter value was used. You could also do this using object level auditing plus a program that scanned for the parameter use. ** Notify someone immediately that a command or parameter was being used. Note that it is too late to stop the command from running. If you want to write a Retrieve Exit, follow the example provided with this tool for the Change Exit along with the system documentation for the 'Command Analyzer Retrieve Exit Program'. Change Exit ----------- The 'Change' function is where the real meat is. For example, you could add or change a parameter value, or use a totally different command. Remember, however, that there are exceptions and considerations as described earlier. The Exit program is not a 'fail safe' form or protection. Reading about the details ------------------------- You can read about the Exit programs by using the Info Center CD and successively clicking on: - Programming - CL and APIs - APIs - APIs by Category - Program and CL Command Then roll to the section on 'Exit Programs'. Look at the details of: - Command Analyzer Change - Command Analyzer Retrieve Change Example -------------- Registering the Exit -------------------- If you want to use a Change Exit, you probably want to practice on a command that is unlikely to be used until you get familiar with the process. For this reason, the example code uses the CRTDKTF command and prevents the user from using FILETYPE(DATA) which is the default. Instead, the example exit program changes all CRTDKTF commands to FILETYPE(SRC). While this is an 'academic example', it is typical of what many users may want to do. You need to register your Exit program for the command you want to change. Because you can have multiple Exit programs, the system uses the PGMNBR parameter to provide a unique ID. To allow for inserting a later exit, you might assign a value such as 50 to begin with. As QSECOFR (or a user with security rights), enter the ADDEXITPGM command. The name of your exit program goes in the PGM parameter. The example requests the program be called whenever the CRTDKTF command in QSYS is used. ADDEXITPGM EXITPNT(QIBM_QCA_CHG_COMMAND) FORMAT(CHGC0100) PGMNBR(n) PGM(yyy/xxx) CRTEXITPNT(YES) PGMDTA(JOB 20 'CRTDKTF QSYS ') If you want to remove an Exit, use the RMVEXITPGM command such as: RMVEXITPGM EXITPNT(QIBM_QCA_CHG_COMMAND) FORMAT(CHGC0100) PGMNBR(n) You can only have one change exit per command. There is also a WRKREGINF command that will let you see what is registered. You will find lots of system function is already registered. In fact, the Exit points for CHG and RTV are already in the list, but may not have any programs. Use Option 8 to 'Work with exit programs'. A list of the programs is displayed along with the unique PGMNBR value you assigned. Removing is easy here, but adding is more difficult because you cannot re-prompt the command in case of errors. You may prefer to use command entry when you want to do an Add. Writing the Exit program ------------------------ The 'Change Exit' documentation (on the Info CD) describes the details of how to code the exit. The exit program gets called in the following situations: Prompting the command Performing interparmeter checks Calling the validity checker program Transferring control to the command processing program (CPP) but the program is only called once. This means if the command is prompted, has a validity checker, and is run, your program will only get one shot at changing the command. Since prompting would occur first, that is when your exit program will gain control. If the command is prompted, you can insert your value before the prompter displays the value, but you will want to make sure that the operator cannot change your value. The example code provides for this. The exit program receives a standard parameter list that includes the command name and any parameters along with the keyword names. A return parameter is used for the command to be run. If you want to send an escape message from the exit, a discussion exists in the example as well as a 'commented out' line of code. See the later discussion on SNDESCMSG4. The example code is fairly standard if you have the same requirement of forcing the use of a command parameter value. The example assumes that you always want CRTDKTF to use FILETYPE(SRC) instead of the default of FILETYPE(DATA). Note that CHGCMDDFT will allow you to change the default of a command, but you cannot enforce its use. The sample Change Exit will enforce the use of *SRC (unless the command is qualified as QSYS/CRTDKTF as described earlier). Your requirements could be different in which case you will need to make several changes to the example code. You can view the example code with the command: DSPTAA TAACMEMC You can copy this code to your source file and member by specifying: CPYTAA TAAARCMBR(TAACMEMC) TOMBR(xxx) TOSRCFILE(yyy/zzz) SNDESCMSG4 for sending an escape message ---------------------------------------- The system monitors for any escape messages sent from the Command Exit program and ignores them. Consequently, you cannot use SNDPGMMSG or a TAA command like SNDESCMSG to cause an escape message that will prevent the use of the original command. You cannot return with a different command that is a CALL to a program that will send an escape message because CALL is prevented as a return command. You can however, use a different command from what was entered that invokes a CPP that sends an escape message to cause the original command to fail. This is the purpose of the TAA command SNDESCMSG4. You must build up this command as a string and then use it as the replaced command. The function exists in the example code, but the branch to the function is 'commented out'. SNDESCMSG4 sends the TAA1020 message from TAAMSGF in TAATOOL. The second level text identifies it as coming from SNDESCMSG4. Prerequisites ------------- None, but the following TAA Tools are used in the example. SCNVAR Scan variable SCNVARRGT Scan variable from the right SNDAUDE Send audit entry SNDESCMSG4 Send escape message 4 Implementation -------------- None, this is only a documentation tool. Objects used by the tool ------------------------ Object Type Attribute Src member Src file ------ ---- --------- ---------- ---------- TAACMEMC QATTCL Only source is provided for the example.

Added to TAA Productivity Tools October 15, 2001

Home Page

Last modified on July 15, 2010