Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA Argent Job Scheduler ENCYCLOPEDIA and Argent Queue Engine Directory Structure ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... ...................................................................... © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA Contents Introduction 4 Argent Job Scheduler Home Directory 5 Sub-Directories 5 \_KEY 5 \DBF\History 5 \DBF\History\JobLog 5 \JobDiagram 5 \Logs 5 \MAPS 6 Argent Queue Engine Home Directory 7 Sub-Directories 7 \BenchMarks 7 \Dashboard 7 \JobArchive 7 \JobDef 7 \JobLog 8 \Logs 8 \Simulate 9 \Temp 9 \Word_Files 9 Configurable\Standalone Files 10 Configuration Information Files 10 Exit Code Files 10 License Key Files 10 Internal Tables 10 © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 2 Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA Environment Strings, Substitution Variables, and Global Text String Macros 11 Environment Strings 11 Substitution Variables 12 Global Text String Macros 12 Notes on Critical Configuration Settings 13 System Options 13 Job Control Panel Options 13 Email Options 14 Security 14 Job List 15 Service Restart 15 Backup Node 16 Rollover and Archiving 16 Licensing 17 © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 3 Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA Introduction This document describes the directory structure of the Argent Job Scheduler and the Argent Queue Engine. © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 4 Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA Argent Job Scheduler Home Directory \JobDiagram This directory contains customer-created job diagram files. Files The default value for the root/home directory of the installed program in this directory are named using the name of the job and a product is typically C:\ARGENT\SchedulingEngine. Customers can .DGR file extension. An example is: change the directory name during product installation. Throughout the remainder of this document, the term “home directory” will be used to TEST_JOB.DGR refer to the name of the installed product root directory. The files in this directory are perpetual and are not purged. Sub-Directories \Logs The following directories are installed under the home directory: This is used to store the product service log files. The service log file is, effectively, a running commentary on the actions a \_KEY given product takes on behalf of the customer. A service log This directory contains the Argent Job Scheduler license file. There is file can have varying degrees of detail. Four levels of detail are typically only one file in this directory. The license file name is made currently supported: up of the product name and the issue date of the product license. An 1 – LOG_NONE example is: This level of detail avoids writing text, if possible. Error mes- ARGENT_JOB_SCHEDULER_04_AUG_2008_14_19_27.LIC sages and other important information are written to the log. 2 – LOG_NORMAL \DBF\History This level of detail provides some status information, such as This directory contains archived job information. the routine starting and stopping of services. This level of detail is adequate in most production environments. When the archive format is configured as “Excel comma delimited”, the archived job information is stored in files with a .CSV extension. 3 – LOG_DETAILED When “Argent Job Scheduler History File” format is used, the archived This level of detail provides some feedback information about job information is stored in files with a .ARC extension. When “ODBC completed API calls, completed function calls within the prod- compliant database” format is used, the archived job information is uct, and enhanced information about progress of multi-step stored in files with a .SQL extension. These files are not SQL queries. processing. The use of the .SQL file extension can be confusing in that regard. 4 – LOG_HIGHLY_DETAILED \DBF\History\JobLog This level of detail provides the greatest level of information about the product as the code executes. This level of detail This directory contains job logs for completed jobs. During rollover and should only be invoked on the recommendation of experienced archival processing, the job logs for jobs that are eligible to be purged and trained Argent technical professionals. are stored in a sub directory for each date. The job logs from jobs purged on 2 Aug, 2008 are stored in \DBF\History\JobLog\20080802, Changing the level of service file logging level requires changing for example. a Windows registry entry for the product. Job history information is stored for the length of time configured on the J9P settings display. © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 5 Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA For many Argent products, the level of service log file logging can be The result of this approach is that all Argent product service changed directly from the user interface.In some cases, direct access log files can be deleted at any time. The very next service log to the service log file detail value is not supported directly using the file message request invoked by the Argent product code will user interface. trigger a new file to be created within the \Logs sub-directory, if needed. For the Argent Job Scheduler, the value of the service log file level of detail is controlled by the \MAPS HKLM\Software\Argent\SchedulingEngine\DEBUG_LEVEL This directory contains customer-created Argent SuperMap registry key. After a typical product installation, this value is set to 2 graphic files. (LOG_NORMAL). On the advice of experienced and trained Argent The files in this directory are perpetual and are not purged. technical support professionals, customers may wish to set this value to a higher level. The service log level of detail can be set to a value between 1 (LOG_NONE) and 4 (LOG_HIGHLY_DETAILED). After making a change, the Argent Queue Engine service should be re-started to be sure the changed value is read in to memory and used for all components of the product. The current service log file within the \Logs sub-directory will have the name svc_log.txt. Each Argent product supports the specification of a maximum service log file size. When the maximum log file size has been reached, the service log file will be renamed, and a new service log file will be created. Typically, the value for the maximum service log file size defaults to 5Mb (5,120Kb). When the maximum size of a given service log file has been reached, the Argent product will rename the current log file to a name that includes that date and time the service log file reached its maximum size. As mentioned above, the current service log file for the Argent Job Scheduler is named svc_log.txt. When the service log file maximum size is reached, the current service log file is renamed and further service log file messages are stored in svc_log.txt. The Argent Job Scheduler user interface program log file is named gui_log.txt. When the service log file maximum size is reached, the current user interface program log file is renamed and further log file messages are stored in gui_log.txt. All Argent products use a standardized approach to writing service log file messages and managing product service log files. This approach calls for opening and closing the service log file for each service log file message that needs to be written. © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 6 Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA Argent Queue Engine Home Directory \JobDef This directory is used as a work area during job execution. The default value for the root/home directory of the installed program product is typically C:\ARGENT\QueueEngine. Customers can change The files stored in this directory include transient files with the the directory name during product installation. Throughout the remain- following general form: <queue_name>.nnn, where nnn is an der of this document, the term “home directory” will be used to refer to ascending sequence number. These files are created by the the name of the installed product root directory. QSHOW command and also by a worker thread controlled by the Job Scheduler user interface. The files are work files used Sub-Directories to temporarily store information returned from the XSGetJobsIn- QueueByFile() API. The following directories are installed under the home directory: When the QSHOW HIGH_PRIORITY /JOBS command is execut- \BenchMarks ed, for example, the list of jobs is retrieved using the XSGetJob- sInQueueByFile() API and stored in a file named HIGH_PRIOR- This directory contains command files that can be used to bench-mark ITY.001. The QSHOW command reads the data in the file and the performance and throughput of the Argent Queue Engine. The display the results. The file is then deleted using the Windows command files are organized within sub-directories focused on single- DeleteFile() API. and multiple process environments. The command files are not needed in production environments and the \BenchMarks sub-directory can be A worker thread within the Job Scheduler user interface also safely deleted after product installation. uses the AQEGetJobsInQueueByFile() API within AQE_API.dll to retrieve job information. The files have the same names as for Customers that want to run bench-mark tests to verify the capabilities QSHOW. The files are deleted when the AQEGetJobsInQueueBy- of the Argent Queue Engine should retain this directory. File() API completes. \Dashboard The type of files stored in this directory include .JS1 and .JS2. Both .JS1 and .JS2 files will have the assigned job number This directory contains sample files that can be used by developers at formatted into the full name. The full name of a .JS1 file will be customer sites. This directory contains files that customer developers J_nnnnnn.JS1, where nnnnnn is the assigned job number. can use as examples of how the Argent Queue Engine information can be used in dashboarding tools. The .JS1 files are used as a signaling mechanism be- tween XS_Main.exe and XS_Load.exe. They are transient \JobArchive and are deleted after an operator request has been pro- cessed. An operator request to abort a job, for example, This directory contains job archive information. Files in this directory will result in a .JS1 file being created. After the abort have names similar to “JOBS_4_Aug_2008.ARC”. Each .ARC file in request has been processed, the .JS1 file is deleted. the directory contains job slot information from JobsSlot.bin for each obsolete job detected during routine processing within XS_Main.exe. Any I/O failure during the creation of a .JS1 file will result in a If the JobsSlot.bin file contains slots for 150 jobs and 30 jobs are service log file message similar to the following: eligible for archiving, a single JOBS_d_Mon_CCYY.ARC file is created that contains the job slot information for all of the 30 eligible jobs. “Failed to write temporary job definition file for job JOB_SAM- PLE (J000156)” The \JobArchive sub-directory is perpetual and is not purged by the Argent Queue Engine. The C:\ARGENT\QueueEngine\JobsSlot.bin file is the master list of jobs to be processed. A .JS1 file contains the job slot information for a single job. © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 7 Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA .JS2 files are similar to .JS1 files: .JS2 files are used as a signaling 1 – LOG_NONE mechanism between XS_Load.exe and XS_Main.exe. This level of detail avoids writing text, if possible. Error mes- sages and other important information are written to the log. A .JS2 file is created after an operator request has been processed 2 – LOG_NORMAL and the job status information has been updated. This level of detail provides some status information, such as the routine starting and stopping of services. This level of detail Summary: is adequate in most production environments. The C:\ARGENT\QueueEngine\JobsSlot.bin is master list of jobs to be processed. A J_nnnnnn.JS1 file is an image of single 3 – LOG_DETAILED job slot and represents a request. A J_nnnnnn.JS2 file is also This level of detail provides some feedback information about an image of a single job slot and represents the result of a completed API calls, completed function calls within the prod- request. uct, and enhanced information about progress of multi-step processing. \JobLog 4 – LOG_HIGHLY_DETAILED This directory is used to store job log files. A job log is a text file con- This level of detail provides the greatest level of information taining the standard output from each individual job. In addition, each about the product as the code executes. This level of detail job log file contains information about how the associated job was should only be invoked on the recommendation of experienced started and ended. and trained Argent technical professionals. The name of each job log file typically contains the job name as well Changing the level of service file logging level requires changing as the job number. An example of a job log filename within the \ a Windows registry entry for the product. JobLog sub-directory is: For many Argent products, the level of service log file logging JOB_PROD_PAYROLL_01_J000156.TXT can be changed directly from the user interface. In some cases, direct access to the service log file detail value is not supported The contents of the \JobLog directory are purged by AJSPurge.exe directly using the user interface. during rollover and archival processing based on the job retention interval. For the Argent Queue Engine, the value of the service log file level of detail is controlled by the It is important to note that although the Argent Queue Engine supports storing job log files in a directory other than the \JobLog sub-directory, HKLM\Software\Argent\ArgentQueueEngine\DebugLevel the only directory purged by AJSPurge.exe is \JobLog. registry key. After a typical product installation, this value is set Given the typical product home directory of C:\ARGENT\QueueEngine, to 2 (LOG_NORMAL). On the advice of experienced and trained the name of the job log directory will be C:\ARGENT\QueueEngine\ Argent technical support professionals, customers may wish to JobLog. If a customer configures the Argent Queue Engine so that job set this value to a higher level. log files are stored in D:\JobLog_Files, for example, that directory is not purged during archival and rollover processing. The service log level of detail can be set to a value between 1 (LOG_NONE) and 4 (LOG_HIGHLY_DETAILED). After making a \Logs change, the Argent Queue Engine service should be re-started to be sure the changed value is read in to memory and used for This is used to store the product service log files. The service log file all components of the product. is, effectively, a running commentary on the actions a given product takes on behalf of the customer. A service log file can have varying degrees of detail. Four levels of detail are currently supported: © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 8 Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA The current service log file within the \Logs sub-directory will have \Temp the name log.txt. Each Argent product supports the specification of This sub-directory is a work area used by Argent program a maximum service log file size. When the maximum log file size has products. It is created during product installation and contains been reached, the service log file will be renamed, and a new service transient and temporary files. log file will be created. Typically, the value for the maximum service log file size defaults to 5Mb (5,120Kb). This file is not used during execution of production customer jobs. When the maximum size of a given service log file has been reached, the Argent product will rename the current log file to a name that Argent does not recommend deletion of this sub-directory, includes that date and time the service log file reached its maximum although files within this directory can be safely deleted. size. \Word_Files As mentioned above, the current service log file for the Argent Queue Engine is named log.txt. When the service log file maximum size is This sub-directory contains word processing files that are help- reached, the current service log file is renamed to log_dd_Mon_ ful to customers. The word processing files constitute relevant CCYY.TXT and further service log file messages are stored in log.txt. information for IT professionals and interested parties at customer sites that may need extended operational or technical All Argent products use a standardized approach to writing service log information about Argent products. file messages and managing product service log files. This approach calls for opening and closing the service log file for each service log This sub-directory is provided as a benefit to customers’ IT file message that needs to be written. professionals and can be safely deleted at any time. The result of this approach is that all Argent product service log files can be deleted at any time. The very next service log file message request invoked by the Argent product code will trigger a new log.txt file to be created within the \Logs sub-directory, if needed. \Simulate This sub-directory contains one relevant file: simulation.cmd. This command file is very powerful and changes the system clock on the system where it is invoked. The Argent Queue Engine supports the capability to test and anticipate the possible impact on a produc- tion environment by date/time changes, specifically, changes that oc- cur when the definition of Daylight Savings Time (or the local, cultural equivalent) takes place. This is not a production command file and should only be invoked on carefully prepared test-bed systems where changes to the system clock can be managed and controlled. Production systems where the impact of a date/time change has been adequately tested do not require this support. On the advice of experienced and trained Argent technical profession- als, this sub-directory can be safely deleted. © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 9 Argent Job Scheduler and Argent Queue Engine Directory Structure ENCYCLOPEDIA Configurable\Standalone Files When a job definition is configured for exit code file processing using the J20E display, the Argent Queue Engine server looks in Some file processing performed by the Argent Job Scheduler is con- the installed product home directory for a file with the following figurable and is not tied to a specific directory. general name: Configuration Information Files <job_name>_nnnnnn.CC Where nnnnnn is the job number assigned by the Queue Engine. Both the Argent Job Scheduler and the Argent Queue Engine maintain configuration information in three files: An example would be • hosts.dat COPY_DAILY_FILES_000156.CC • timeouts.dat After the job exit code is retrieved from the exit code file, the file • users.dat is deleted. The hosts.dat and timeouts.dat files contain information about Queue Engine server connections. The users.dat file contains mapping infor- License Key Files mation used to translate a Job Scheduler user account to a different account on a given Queue Engine server system. A license key received from Argent will have the product name and a date expression in the name, followed by a .LIC exten- The Job Scheduler GUI Remote/UNIX/iSeries/SAP Server Management sion. dialog (Screen ID J87A and J87B) is used to maintain these files. Customers should only manipulate these files on the advice of trained An example of a product license file for the Argent Job Sched- and experienced Argent technical and support professionals. uler is: Exit Code Files ARGENT_JOB_SCHEDULER_4_AUG_2008_14_22_33.LIC Product license files must not be deleted. Typically, a customer job returns an exit code directly to the operating system. In C++, for example, the return statement is used to do this. Argent recommends storing all license files received from A customer job that calls a C++ .exe file will use the return state- Argent in the _KEY sub-directory. ment to tell Job Scheduler its result. The result is an exit code that can be used to configure exit code processing on the J20I display of a job Internal Tables definition. The Argent Queue Engine maintains status information in four In some cases, the customer executable that is invoked runs a script. critically important files within the product home directory: Visual Basic scripts, for example can be invoked using VBScript.exe. Even though the script does not complete successfully, VBScript.exe • JobsSlot.bin will complete successfully. To provide a way for the Argent Queue En- • JobTemplate.bin gine and thus Argent Job Scheduler to retrieve the result of the script, • PerfData.bin a customer-developed application can format an exit code file that • QueueSlot.bin contains the result of the script. These files contain product-specific internal information about each job, job template, and queue supported by the Argent Queue Engine. Each of these files are assumed and required to be available to the Argent Queue Engine at all times. These files can not be inspected, opened, read, or manipulated in any way by customer processes, including anti-virus programs. © ArgSoft Intellectual Property Holdings, Limited. 1991 - 2010 10