How does the PREP_PROCESS script function work and how can it be customized?
The documentation says:
This script function uses specific Job objects (event jobs) in order to process commands on a computer and it returns the Console output that can be used for further processing as an internal list (data sequence).
What does that mean in detail?
Each time the script function is processed a JOBS object is executed in the background. The command, the agent and the login information specified in the script function are passed on to the Job. In general the output (standard out) of the command is returned to the script function and can be processed with a data sequence (Script Statement “PROCESS”).
So it’s basically a way to get the result of simple operating system commands right back to the Automic script and work with the result.
Explanation, customization and hints
For better understanding, demonstration of the powerful customization possibilities and some useful hints, “UNIXCMD” and a simple “ls” command is used as an example:
- The first parameter is used to specify the Agent, in this case: “VWGSUP01”
- The second parameter specifies the Job object, which is activated to execute the command, “EVENT.” is added as a prefix. Therefore we will get the object name “EVENT.UNIXCMD” in this example.
The system will try to find this object in the current client, if it’s not available there, it will try to find it client 0. In case the object is not found, the script will fail, e.g.:
U00010000 '<client>', Object 'EVENT.UNIXCMD.NIEDA' was not found. Please enter the correct name.
Per default the Job “EVENT.UNIXCMD” is available in client 0 in the “PREP_PROCESS” folder. The Jobs in this folder are considered as proposals or as examples. The way the work may fit to the needs or may not. Therefore the following customizations are possible:
- Create your own objects, for instance duplicate “EVENT.UNIXCMD” to “EVENT.UNIXCMD.CUSTOM” and modify it according to the requirements.
Note: Specify “UNIXCMD.CUSTOM” at the script function PREP_PROCESS to use the new object!
- Take a copy of the default object in client 0 to your current client and modify it according to the requirements. In this case you may stay with the default name.
- It’s not recommended to modify the default objects in client 0, because any modification will be overwritten during an Initial Data update, regardless if it’s major, minor, service pack or hotfix update!
- It’s not recommended to enable the report in the object – tick the Database or File checkbox – because it will create useless reports wasting space. However, this might be of help for troubleshooting only.
- The third parameter is used to set a filter for the output lines, which are retrieved in the following PROCESS loop. Here “*” in used, so all lines will be processed.
- With the Action parameter “cmd” the command which should be executed on a specific Host is specified, in this case “ls /home/scj -l” is the operating system command.
- The parameter UC_LOGIN defines the Login object used by the Job, this needs to match with the Agent specified with the first parameter.
More details about the syntax and the script function in general can be found in the documentation:
Common problems using PREP_PROCESS
After an update PREP_PROCESS has change behavior
Make sure to create you own Event Jobs, whenever modifications of the example objects in the “PREP_PROCESS” folder in client 0, are necessary. Modification will be overwritten during an Initial Data update.
EVENT.UNIXCMD aborts with return code and the data sequence could not created
The default object is designed to remove the output file (event file) in case the commands gets a return code greater than 0:
In case the path or file specified at the “ls” command doesn’t exist, it will terminate with return code 1 ($? = 1). The output file is removed due to the if statement in the default EVENT.UNIXCMD. The following messages will appear in the message window:
U00011003 Job 'EVENT.UNIXCMD' (RunID '0004369133') on Host 'VWGSUP01' aborted (return code='0000000001'). Remote ID=8030U00011000 'REPORT' (RunID: '0004369134') could not be started on 'VWGSUP01'. See next message.U00029003 Cannot open file '/home/scj/EAAJORQO.TXT(ReadFileAuthority())', error code '2', error description: 'No such file or directory'.U00010038 Runtime error: Could not create data sequence 'FILETRANSFER'. Status: '0000001820', return code: '0000000000'.
Knowing that, the “Cannot open file” error is no longer misleading. It’s just because the file was deleted and not because of an authorization problem.
Create your own EVENT.UNIXCMD object, for instance:
Now, the following messages will appear in the message window:
U00011003 Job 'EVENT.UNIXCMD.RB' (RunID '0004370773') on Host 'VWGSUP01' aborted (return code='0000000001'). Remote ID=8254U00012109 Script 'SCRI.PREP_PROCESS_UNIXCMD' (RunID '0004370772') ended normally.
And the data sequence was created and loos like that:
2017-02-21 08:53:33 - U00007000 'EVENT.UNIXCMD.RB' activated with RunID '0004370773'.2017-02-21 08:53:33 - U00020408 ls: /home/scj/nieda: No such file or directory
Some error handling for the command executed by the PREP_PROCESS needs to be included in the PROCESS loop!
With the information provided in this article, it’s possible using the full potential of this powerful script function.