JobRescue and ElectroPage can be configured to execute an MPE command file whenever a $STDLIST or report spoolfile has been processed. A command file can perform functions such as copying the spoolfile, triggering an alert system, transmitting a file, or most any task associtated with the job or spoolfile that was examined by JobPak.

This document is not intended to teach you how to write a command file, but rather show you how JobPak can perform special processing when a spoolfile is examined. To learn the full syntax of the MPE command interpreter please consult the appropriate MPE/iX documentation.

Having said that, if you have a particular need for writing a specialized command file, and don't have the expertise available, Nobix is always happy to help. If we can do it, we'll write it for you usually at no cost to you. If we can't, we'll explain why.

In the following sections, we will discuss how a command file for JobPak is constructed and how best to utilize them for advanced spoolfile processing with JobRescue and ElectroPage.

• How it works
• Considerations when running a command file from JobPak
• Command file example
• Checking for exceptions
• The PARM line
• Parameter values
• Using the parameters
• Command file characteristics
• More examples

After JobRescue or ElectroPage is finished looking for exception messages and storing a local copy of the spoolfile, any command file or files that have been configured are then executed. The command file execution comes before the EXCPTLST (the printed copy of the exception $STDLIST, if any was configured) is generated, and before JobQue (if used) is notified that the job has logged off.

The processing sequence goes like this:

1. MPE notifies JobPak that a $STDLIST or report is now ready in the spool system.
2. The JobPak program JP06SXL springs into action.
3. A local copy of the spoolfile is created.
4. Exception messages are checked for.
5. An index record is written to JOBDATA.PUB.NSD.
6. Console messages are sent.
7. If configured, file compression begins on the local copy.
8. Command files are executed, up to 6 global (first) and 6 job/report specific (after the global) may be configured.
9. EXCPTLST or spoofile copy is generated.
10. If licensed, JobQue is notified of the job/spoolfile completion.
11. The saved generation count is checked, and old generations of the same spoolfile are deleted.
12. If configured, the spoolfile is emailed to its distribution list.
13. If configured, ElectroPage generates bannered copies of the spoolfile.
14. Processing for the spoolfile is completed.

If any command files are executed by JobPak, they are executed from within the JobPak job. A few considerations are necessary to prevent command file interference with the JobPak job.


• Command files should never read $STDIN without having the command file redirect its $STDIN to a file. Otherwise the JobPak job's job control will be used to satisfy the read request of the command file.
  
  
• There are normally five JP06SXL programs running that provide for simultaneous examination of multiple spoolfiles. However, during the execution of a command file the JP06SXL program assigned to the spoolfile is suspended. If the command file being executed runs for a long period of time it may affect JobPak's ability to process spoolfiles in a timely manner. Once five long-running command files are executing (from five spoolfiles being processed), JobPak will suspend until one or more of the command files completes.
  
  
• Command files execute as part of the JobPak job. JobPak uses privilege mode (PM) to aquire system manager (SM) capability, without which it could not perform its intended function. This means that any command file you execute will also be running with SM capability. Command files should be stored in the NSD account or another secure account, where they cannot be modified without proper authorization.
  
  
• Note that more than one spoolfile may be examined at the same time, which means that more than one instance of your command file may be executing at the same time from within the same JobPak job. This may create a conflict problem for any :FILE commands that share the same naming, as well as any temporary or permanent files that may be accessed during the execution of the command files. Whenever using tempoary files in a JobPak command file, try making the DFID part of the filename, which then makes the file unique. Remember to delete temporary files before the command file exits.
  
  
• Just before command file execution, JobPak creates a temporary file named Xnnn, where the "nnn" is the numeric DFID of the spoolfile that was just examined. This temp file contains up to the 10 lines of text that JobPak found as exception text in the $STDLIST. It is automatically deleted when all command file execution is completed. The file may be accessed by using this syntax for the filename:
  
  X!DFID
  
  

PARM Dfid ExCnt MissingCnt JobPreFix JobNo FileDes="" JobName="" & UserName="" AcctName="" ElapMin CpuSec DateLogon="" & TimeLogon="" DateLogoff="" TimeLogoff="" JobPakFname="" # only execute on error conditions if !ExCnt = 0 AND !MissingCnt = 0 then     return endif STREAM MYJOB.MYGROUP.MYACCT

Example 1 - Streaming a job when an error is detected.

The simple example above shows a command file that when executed, if the $STDLIST it was executed for has an exception, the job control file MYJOB.MYGROUP.MYACCT is streamed.

In the above example, the line:

if !ExCnt = 0 AND !MissingCnt = 0 then
 
checks the exception count and the missing message count. The exception and missing counts are the second and third parameters being passed to this command file (ExCnt and MissingCnt are NOT command interpreter variables).

If both counts are zero, then JobRescue did not find any exceptions or errors in the job that was just examined. If there are no exceptions, then the next statement, the return is executed, causing the command file to immediately stop execution.

The "endif" is a required terminator for the "if" command.

If exceptions were found in the job that was examined, then the command file continues and the command:

STREAM MYJOB.MYGROUP.MYACCT
 
is executed, causing that job to be streamed.

Note the exclamation characters in front of the two command line parameters ExCnt and MissingCnt. Using the exclamation is how a command line parameter is dereferenced.

Notice in the above example the lines at the beginning of the file:

PARM Dfid ExCnt MissingCnt JobPreFix JobNo FileDes="" JobName="" &
UserName="" AcctName="" ElapMin CpuSec DateLogon="" &
TimeLogon="" DateLogoff="" TimeLogoff="" JobPakFname=""


The parameter declaration line for JobPak command files has a specific format, delclaring each of the parameters being passed to it from the JobPak job. When creating your own command files, you may copy the contents of the file PARMLINE.JPAK.NSD into the beginning of your command file. The PARMLINE file contains only the example PARM line -- do not overwrite this file, leave it as it was supplied.

All command files for use by JobPak must have this specific PARM line at the beginning. Notice the ampersands. The first two lines have ampersands at the end. The ampersand is the continuation character that MPE command files use to indicate that the command line continues onto the following line.

Dfid The numeric portion of spool ID of the spoolfile just examined. For #O123 this parameter contains only the 123 part. ExCnt A value from 0 through 10 indicating the number of exception messages found in the spoolfile while it was being examined. If the number is 10, there may actually be more than 10 exceptions, however JobPak stops looking after 10 have been found. MissingCnt A value indicating the number of missing messages that JobRescue/ElectroPage expected to find in the file but did not find. Missing text is configured on the Job Specific Values page of the CONFIGIX program. The missing text ":EOJ" is automatically configured when you tell JobPak to ensure that an EOJ exists at the end of the job. JobPrefix The job number prefix, one of #J, #J', #S, or #S', depending on the spoolfile creator. JobNo The numeric portion of the job or session number that created the spoolfile. FileDes The name of the spoolfile in the spool system. This name may be blank. JobName The job or session name that created the spoolfile. This name may be blank. UserName The user name that created the spoolfile. This name may be blank. AcctName The account name that the spoolfile was created in. This name may be blank. ElapMin For a $STDLIST, the number of minutes that the job was running. For other types it is 0 (zero). CpuSec For a $STDLIST, the number of CPU seconds that the job used. For other types it is 0 (zero). DateLogon For a job, the eight-character date the job logged on, as in 20100531. For others, 00000000. TimeLogon For a job, the eight-character time the job logged on, as in 17:05:00. For others, 00:00:00. DateLogoff For a job, the eight-character date the job logged off, as in 20100531. For others, the eight-character date the spoolfile became ready in the spool system. TimeLogoff For a job, the eight-character time the job logged off, as in 17:23:00. For others, the eight-character time the spoolfile became ready in the spool system. JobPakFname The POSIX filename of the copy of the spoolfile saved by JobPak, relative to the /NSD root directory.

In order to access the value passed through a parameter, it must be dereferenced using the exclamation character (!). It is important to note that parameters that are passed on a command line to an MPE command file are not MPE command interpreter variables. CI variables are automatically dereferenced by MPE when used in various contexts such as the IF and SETVAR commands, and do not always require the exclamation. Parameters on the otherhand, are not variables, and must always be dereferenced.

In cases where a parameter may contain a null or blank value, meaning a zero length text string, it may be necessary to enclose the dereferenced parameter in quotes. Enclosing in quotes indicates to the command interpreter that a value is being passed, just that it is empty. Not enclosing a parameter that contains an empty value is the same as not specifying it on a command line.

Command files used by JobPak are generally ASCII format files. You may use any suitable text editor to create and/or modify the file text. Nobix recommends that command files be kept as variable record length ASCII files to minimize restrictions when working with commands in the file that may be of a greater length than a fixed record length would allow.

Example 2 below shows how a desktop alert is triggered by JobPak in the Nobix Alert product. When JobRescue finds an exception, it formats an HTML page that is then sent to the Nobix Alert server. The server then displays the desktop pop-up on the PC's included in the distribution list named "JobRescue".

PARM Dfid ExCnt MissingCnt JobPreFix JobNo FileDes="" JobName="" & UserName="" AcctName="" ElapMin CpuSec DateLogon="" & TimeLogon="" DateLogoff="" TimeLogoff="" JobPakFname="" if !ExCnt = 0 and !MissingCnt = 0 then     return endif # --------------------------------------------------------------------- # Modify the SETVAR command and change the nobixalertserver (in between # the quotes) to the hostname or ip address of your actual Nobix Alert # Server. Do not remove the quotes, only change the value inside them. setvar nalertserver "nobixalertserver" # --------------------------------------------------------------------- # The next SETVAR sets the name of the distribution list that Nobix Alert # will send JobRescue exceptions to. You do not need to change the # value. In Nobix Alert, on the Recipients pane, configure a distribution # list named "jobrescue" and add the appropriate recipients to it. setvar distlist "jobrescue" # --------------------------------------------------------------------- print HTMLHEAD.NALERT > z!Dfid echo #!JobPreFix!JobNo - !JobName,!UserName.!AcctName >> z!Dfid echo >> z!Dfid echo Logon: !DateLogon !TimeLogon >> z!Dfid echo Logoff: !DateLogoff !TimeLogoff >> z!Dfid echo Elapsed: !ElapMin Cpu_Secs: !CpuSec >> z!Dfid echo >> z!Dfid echo !ExCnt Exceptions, !MissingCnt Missing Messages. >> z!Dfid echo >> z!Dfid echo Error Lines: >> z!Dfid continue print X!Dfid >> z!Dfid print HTMLFOOT.NALERT >> z!Dfid echo nalert.nalert "-plain -play siren.wav -secs 5 !nalertserver '!distlist'" # --------------------------------------------------------------------- # To change the sound that is played, change siren.wav on the line # below, to one of: # # none, beep, klaxon.wav, risingfast.wav, risingslow.wav, # siren.wav, tone1.wav, tone2.wav, tone3.wav # nalert.nalert "-plain -play siren.wav -secs 5 !nalertserver '!distlist'" < z!Dfid purge z!Dfid,temp

Example 2 - Start a desktop alert in the Nobix Alert Server product.




---




Example 3 below shows how the EXCPTLST (the copy of a $STDLIST that is made when an exception is found) is redirected to a different print device, depending on the current state of the preferred print device. If the preferred device, 6, is not currently "ok", then device 7 is used. This example makes use of a temporary message file (FIFO) to process the readback from a SHOWDEV command. Note how the temp file is named based on the spoolfile's DFID.

ANYPARM Dfid="" ExCnt="" MissingCnt JobPreFix JobNo FileDes="" JobName="" & UserName="" AcctName="" ElapMin="" CpuSec="" DateLogon="" & TimeLogon="" DateLogoff="" TimeLogoff="" JobPakFname="" # redirects the STDCOPY and EXCPTLST file commands # depending on the spooled state of the device. # build a message file with the output of the SHOWDEV. # read it back in the loop, each record that is read is deleted. BUILD Z!Dfid;MSG;TEMP FILE Z!Dfid,OLDTEMP SHOWDEV 6 > *Z!Dfid ECHO EOF >> *Z!Dfid # to terminate the loop, set LINE to a null string # don't return without purging Z!Dfid setvar SPOOLEROKAY FALSE setvar LINE "X" while str(LINE,1,3) <> "EOF" do     continue     input LINE < *Z!Dfid > $NULL     if pos("SPOOLED",ups(LINE)) > 0 then         setvar SPOOLEROKAY TRUE         setvar LINE "EOF"     endif endwhile PURGE Z!Dfid,TEMP RESET Z!Dfid if SPOOLEROKAY then     FILE EXCPTLST;DEV=6     FILE STDCOPY;DEV=6 else     FILE EXCPTLST;DEV=7     FILE STDCOPY;DEV=7 endif

Example 3 - Redirect the EXCPTLST depending on the preferred device spooled state.

---




Example 4 below shows how to create a temp file and anonymously ftp it to a remote system. This example creates a trouble ticket file, which is then ftp'd, which then is used by the remote system to initiate a ticket in the company's support system.

PARM Dfid ExCnt MissingCnt JobPreFix JobNo FileDes="" JobName="" & UserName="" AcctName="" ElapMin CpuSec DateLogon="" & TimeLogon="" DateLogoff="" TimeLogoff="" JobPakFname="" # if no exceptions, then return and don't do anything if !ExCnt = 0 AND !MissingCnt = 0 then     return endif # note that JobRescue is multiprocessing, meaning that more than one # job examination can take place at the same time. Do not use any # filenames or CI variables are not somehow unique. This command file # uses the Spool ID (Dfid) to create uniqueness. Remember, Spool ID's # can be up to 7 characters long, so only use one alpha character in the # front when comming up with a filename. # The resulting file is a temporary file named E1234 where 1234 would be # the Spool ID. echo !HPDATEF !HPTIMEF > e!Dfid echo !JobPreFix!JobNo, !JobName,!UserName.!AcctName HAS AN EXCEPTION >> e!Dfid echo Spool ID #O!Dfid >> e!Dfid echo JOB NUMBER: !JobPreFix!JobNo >>e!Dfid echo NAME: !JobName,!UserName,!AcctName >>e!Dfid echo LOGON: !DateLogon, !TimeLogon >>e!Dfid echo LOGOFF: !DateLogoff, !TimeLogoff >>e!Dfid echo ELAPSED: !ElapMin >>e!Dfid echo CPU: !CpuSec >>e!Dfid echo NUMBER OF EXCEPTIONAL TEXT LINES FOUND FOR !JobName IS !ExCnt. >>e!Dfid echo NUMBER OF MISSING TEXT LINES FOUND IS !MissingCnt. >>e!Dfid echo EXCEPTION LINES FOUND WERE: >>e!Dfid echo >>e!Dfid print X!Dfid >>e!Dfid # Do the file transfer here. Example system is named "remote.mydomain.com" echo anonymous > f!Dfid echo my.email.addr@mydomain.com >> f!Dfid echo Put e!Dfid destination/directory/e!Dfid >> f!Dfid echo Quit >> f!Dfid FTP.ARPA.SYS remote.mydomain.com < f!Dfid # purge the temp files when done. save f!Dfid save e!dfid

Example 4 - FTP an error description to a remote system.