Table of Contents

1.0 Interface Introduction
1.1 Install
1.2 Updating Cross References
1.3 Source File Structure
1.4 Importing Source Data
1.5 Running the Interface Automatically
1.6 Log Files

1.0 Interface Introduction

The JOB HQS Text File Interface software is used for transfer of daily values from text files with comma separated values (.txt) to JOB Plus/Cal.  JOB Plus/Cal then summarizes the data based upon the user-specified statistic and the resulting value is placed into the JOB Plus/Cal Meter Readings database table.

1.1 Install

JOB Plus/Cal and the Interface MUST be installed on the same computer.  The TXT files created by HQS must be accessible from the JOB Plus/Cal computer (either through a network connection, local drive, or by copying onto a disk). 
To install JOB PLUS/CAL Interface, follow these steps:

1. Place the Interface Disk 1 in drive A:  If you are installing from drive B:, use B: instead of A: in these instructions.
2. In Windows, close all programs that are currently running.
3. Choose [Start], [Run] from the Start Bar.   Windows will prompt for the Command Line, type a:setup and click OK.   
4. Follow the instructions on the screen and the installation program displays the following box:
   
   
   
5. Install the program in the same directory that you installed JOB Plus/Cal (Usually C:\Job).  Click Extract to begin the installation.  From this point, the installation will copy the program to your computer. 

1.2 Updating Cross References

In order for the transfer of data to occur, you must first set up a cross-reference between HQS tags and JOB Plus/Cal equipment.
To update cross-references, bring up the Equipment Record and click hand-shake button. The following form will be displayed.

The example shown cross-references the HQS signal tag “EFF_FLOW” with the JOB Plus/Cal equipment “ABW1”.

Field Descriptions

• Signal Tag The HQS Tag to import data from.
  
• Statistic The statistic to perform on the source data.  The following options are available from the drop down list box:
   Last Good Reading – Takes the last reading for the day and places it in the Meter Reading Table.
   Add to Previous – Takes the maximum reading for the day and adds it to the last meter reading in JOB Plus/Cal for the equipment.  Add to Previous is typically used when the value to be transferred is the daily runtime and is reset everyday. 
   Accumulate Difference – Takes the last reading for the current day minus the last reading for the previous day and adds that value to the last meter reading.  Detects if the meter reading has rolled over.  For example:
      Date  Last Reading Meter Reading Stored
      12/13/99 950  14000 
      12/14/99 985  14035 (14000 + (985 – 950)
      12/15/99 10  14060 (14035 + 25 (Rollover assumed at 1000))
      12/16/99 42  14092 (14060 + (42 – 10)
   If there is no value for the previous day, the current days last reading will be added to the last meter reading value found in JOB Plus/Cal.
   Cycle Count – Counts the number of times that the value went from 0 to something else during a day and adds it to the last meter reading in JOB Plus/Cal for the equipment.  Cycle Count is typically used when you want to schedule maintenance after for example 500 starts. Note that you currently have to type this statistic in the list box instead of picking it from the drop down list box.
  
• Scale Factor Used as a multiplier to scale the statistic before placing the value in the database.  For example, if HQS is storing the number in tenths of hours use a scale factor of .1 to convert the reading to hours.  If HQS is storing the runtime in minutes, use a scale factor of 0.0167 (1/60) to convert the reading to hours. 

1.3 Source File Structure

CSV file names can be in several formats.
The most common is for each day to have its own csv file with the MMDDYYYY.csv filename.  It is strongly recommended that this is the filenaming convention that you use.  The following table shows sample days and the corresponding filename.
Date FileName
1/1/97        01011997.txt
1/31/97      01311997.txt
2/15/98      02151998.txt
12/31/98    12311998.txt
5/29/00      05292000.txt

Note:  The following formats (MDYYYY, MDYY, MDYYYY? and MDYY?) are not recommended due to the fact that different days will have the same filename.  If you use MDYYYY you are going to be overwriting files, Ex. 1/11/03 and 11/1/03 are both going to be written to 1112003.csv.  If these formats are used the program will check the modified date of the file and check it against the filename to make sure they are within a day or two of each other and if they aren’t, the file will not be used.

Each day’s text file must be in the following structure. This is according to sample files we received from HQS:

• The first column is the signal tag
• The second column is the value
• The third column is the date

Here is a sample of a source text file (filename was like 20100701.txt, notice the date column):

33LS1-DY-TIME,.19,01-JUL-10 12.00.00.000 AM,0,0
33LS2-DY-TIME,.09,01-JUL-10 12.00.00.000 AM,0,0
BB1-DY-GAL,51.7,01-JUL-10 12.00.00.000 AM,0,0
BB1-DY-KWH,0,01-JUL-10 12.00.00.000 AM,0,0
BB11-DY-TIME,0,01-JUL-10 12.00.00.000 AM,0,0
BB12-DY-TIME,0,01-JUL-10 12.00.00.000 AM,0,0
BB2-DY-GAL,0,01-JUL-10 12.00.00.000 AM,0,0
BB2-DY-KWH,0,01-JUL-10 12.00.00.000 AM,0,0
BB21-DY-TIME,3.72,01-JUL-10 12.00.00.000 AM,0,0
BB22-DY-TIME,4.84,01-JUL-10 12.00.00.000 AM,0,0
CB1-DY-GAL,0,01-JUL-10 12.00.00.000 AM,0,0
CB1-DY-KWH,0,01-JUL-10 12.00.00.000 AM,0,0
CB1-DY-TIME,5.03,01-JUL-10 12.00.00.000 AM,0,0
CB2-DY-TIME,5.98,01-JUL-10 12.00.00.000 AM,0,0
FB1-DY-GAL,0,01-JUL-10 12.00.00.000 AM,0,0
FB1-DY-KWH,0,01-JUL-10 12.00.00.000 AM,0,0
FB1-DY-TIME,6.09,01-JUL-10 12.00.00.000 AM,0,0
FB2-DY-TIME,0,01-JUL-10 12.00.00.000 AM,0,0
G2A-DY-GAL,0,01-JUL-10 12.00.00.000 AM,0,0
G2A-DY-KWH,0,01-JUL-10 12.00.00.000 AM,0,0
G3A-DY-GAL,0,01-JUL-10 12.00.00.000 AM,0,0
G3A-DY-KWH,0,01-JUL-10 12.00.00.000 AM,0,0
G4A-DY-GAL,0,01-JUL-10 12.00.00.000 AM,0,0

1.4 Importing Source Data

You can create an icon on your desktop, which can be used to start the program.  To do this open Windows Explorer and find the directory where JobHQS_Text.exe is located which is usually C:\Job.  Right click on the executable and select Send To/Desktop (Create Shortcut).

Click on the JOB Interface icon to start the import program or click on Start/Programs/Ops Systems/Job Interface.  The Interface main form will display:

Using the Interface

Fill in the start and end dates.  Enter the Format of text files and the file location and list the JOB Plus/Cal databases you want to import to and click OK.  In Autorun mode the start date defaults to the last date imported plus one day.  The end date defaults to yesterday.   Data will be imported from the text files for the date range for the JOB Plus/Cal Equipment that is cross-referenced. 

Field Descriptions

• Start Date The beginning date to collect data.  In Autorun mode the start date will default to the last date that was successfully imported plus one day. 
  
• End Date The ending date to collect data for.  In Autorun mode the end date will default to yesterday.
  
• Start Time The starting time that data is collected each day in hours and minutes (HH:MM). For most installations this should be set to 00:00.
  
• Stop Time The ending time that data is collected each day in hours and minutes (HH:MM). For most installations this should be set to 23:59 and Same Day as Start should be checked.
  
• Same Day as Start If the Stop Time is on the same day as the start time, select this option.  For example, to summarize data from 01:00 AM till 10:00 AM, set Start Time to “01:00" and Stop Time to “10:00" and select Same Day as Start. 
  
• Day After Start If the Stop Time is on the day after the start time, select this option For example to collect data from 8:00AM to 8:00AM, set Start Time to “08:00" and Stop Time to “08:00" and select Day After Start.

Note: Data is always stored on the start time day. The Start and Stop Time along with whether you checked Same Day as Start     or Day After Start determine the time span that is looked at for each day."

Most installations will use:
  00:00 as the Start Time.
  23:59 as the Stop Time.
  And Same Day as Start will be checked.

However, what if your meters were reset at 7 a.m. every morning, then you might want to use the following:
  07:05 as the Start Time.
  06:55 as the Stop Time.
  And Day After Start will be checked.

• Format of Text Files See section 1.3 Source File Structure.
  
• Source File Location The directory that contains the source text files.  Use the ... button to select the directory.
  
• Job Databases Lists the JOB Plus/Cal databases that will be imported to.  Use the Add button to select a database to be imported to.  The Remove button will delete the database from the list so that data will not be imported to that database.  You can list up to nine (9) databases.

Buttons

... Elipse button is used to select the CSV File Location.  Displays the following form:

Select the drive and directory and click OK.  Click Cancel to return without saving changes.

OK - Perform the import.
Exit - Exit the program.

1.5 Running the Interface Automatically

Method 1 (This is the recommended method). To run the interface on a scheduled basis use the Autorun settings.  Each setting is described below.

To run the interface every day at a set time:

1. Select the “Daily” option button.
2. Enter a time of day to run.
3. Click Start.

To run every hour:

1. Select the “Hourly” option button.
2. Enter a Run every hour time.
3. Click Start.

Reduce the interface by clicking on the minimize button to reduce the interface to the taskbar.  The interface will now run on the scheduled basis.

NOTE: YOU MUST LEAVE THE INTERFACE RUNNING TO ALLOW THE INTERFACE TO AUTORUN.  If you shutdown the program the interface will not run. 

Method 2 (Method 1 is the recommended method). The interface can be run automatically on a scheduled basis using command line arguments.  There are several programs on the market that allow you to run a program on a scheduled basis including Microsoft System Agent (older Microsoft Operating Systems, Windows95), Microsoft Task Scheduler (newer Microsoft Operating Systems, including 98, 2000 and XP), Norton Program Scheduler, WIN NT AT command, and several others.  If you invoke the interface with a command line argument the program will perform the import for the default dates and exit the program.  The start date will be set to the day after the last date the interface was run and the end date will vary according the command line argument, if it is 1 the end date will be set to yesterday and if it is 2 the end date will be set to today.

Understanding Task Scheduler (newer Microsoft Operating Systems, including 98, 2000 and XP).  Task Scheduler starts each time you start Windows.  It runs in the background starting programs at the scheduled times.  You can schedule a new program or change the schedule for a program that is already scheduled.  To use Task Scheduler, click the Start button, point to Programs, point to Accessories, point to System Tools, and then click Scheduled Tasks

Double click on Add Scheduled Task to bring up the Schedule Task Wizard.

Click on the browse button.

Find JobHQS_Text.exe usually located at C:\Job
 

Select how often you want to run the task.

Select at what time to run the task.
 

Enter your logon name and password.

Check the Open advanced properties checkbox and then click Finish.

Remember to enter either a 1 or 2 for the command line argument as explained above.  Click Apply.

Using Windows NT AT command to autorun interface:

The AT command is an NT service used to autorun windows applications.  It can be used to autorun the interface.   The SERVICE “Schedule” must be running for the AT command to work. See “Schedule service” in WINNT HELP for more details.  To setup the AT command, go to the Command Prompt. Enter the following command line to autorun the interface at 1:15 AM.
AT 1:15 /EVERY:M,T,W,TH,F,S,SU “C:\Job\JobHQS_Text.exe” 1
Note: The parameter 1 is OUTSIDE the quotes.

Understanding System Agent (older Microsoft Operating Systems, Windows95 where it is included on the Microsoft Plus! For Windows 95 CD-ROM)

System Agent starts each time you start Windows. It runs in the background, checking your computer for low disk space and starting programs at the scheduled times.  You can schedule a new program or change the schedule for a program that is already scheduled.  When System Agent is running, this icon appears next to the clock on the taskbar: If the System Agent is not running, click the Start button, point to Programs, point to Accessories, point to System Tools, and then click System Agent. 

1.6 Log Files

This program generates log files that are used for troubleshooting.  They are located in the Logs subdirectory beneath the directory where JobHQS_Text.exe is located on the users local computer, in most cases it will be C:\Job\Logs. The name of the files have the following format: JobWWLogmmddyyyy.txt where mm is the month, dd is the day and yyyy is the year (example JobWWLog10172002.txt).