Before you start if you're using some other EPG plugin, be sure to properly uninstall it before installing mc2xml.

Here are the steps for using zap2xml:

1.  Download and install Strawberry Perl from here: http://strawberryperl.Com
     (I'm using the 32-bit version -- probably doesn't make any difference)
2.  Download the Perl script version of zap2xml from here: http://zap2xml.Awardspace.Info
3.  Edit and test your zap2xml Perl script.
4.  Install and configure the mc2xml plug-in from within SageTV. 

     Note -- Whenever downloading files from the internet, always remember to right click on them and select properties. At the bottom of the general properties tab, will be a checkbox allowing you to unblock the file if it has been blocked. Most files downloaded from the internet are blocked, simply check the unblock box and click okay.

         Editing the zap2xml Perl script:

Open zap2xml.Pl In a text editor. ( I use notepad ++)
Search for this line:

        return sprintf("I%s.labs.zap2it.com", $stations{$s}{stnNum});

And replace it with this line:

        return sprintf("I%s.%s.zap2it.com", $stations{$s}{number},$stations{$s}{stnNum});

This will change the channel id into a format that the mc2xml plugin is looking for. This will effectively make zap2xml compatible with the mc2xml plugin. The next change involves fixing a bug in zap2xml that causes some characters in the extra program details to be improperly displayed. You see, zap2xml has a command line option (-D = include extra program details). This option replaces the single line description in the Zap2it program schedule with the more extensive description that pops up if you click on that program. These extra program details come from a Javascript file that contains special HTML characters. Zap2xml does not decode these characters properly. This edit will fix this problem.

Near the top of the script you will find a list with these entries:

use Compress::Zlib;
use Encode;
use File::Basename;  -- ect.

Simply add use HTML::Entities;  to the top of the list like so.

use HTML::Entities;
use Compress::Zlib;
use Encode;
use File::Basename;  -- ect.

Then search for this line:

        if (!defined($options{U})) {$t = Encode::decode('utf8', $t);}

Which will be in a block of code that looks like this: 

sub enc {
  my $t = shift;						  
  if (!defined($options{U})) {$t = Encode::decode('utf8', $t);}
  if (!defined($options{E}) || $options{E} =~ /amp/) {$t =~ s/&/&/gs;}
  if (!defined($options{E}) || $options{E} =~ /quot/) {$t =~ s/"/"/gs;}
  if (!defined($options{E}) || $options{E} =~ /apos/) {$t =~ s/'/'/gs;}
  if (!defined($options{E}) || $options{E} =~ /lt/) {$t =~ s/</&lt;/gs;}
  if (!defined($options{E}) || $options{E} =~ /gt/) {$t =~ s/>/&gt;/gs;}
  if (defined($options{e})) {
    $t =~ s/([^\x20-\x7F])/'&#' . ord($1) . ';'/gse;
  }
  return $t;

Between the two lines:

  my $t = shift;
  if (!defined($options{U})) {$t = Encode::decode('utf8', $t);}

Add these lines:

  $t = Encode::decode('utf8', $t);

  if (defined($options{U})) {
	$t = decode_entities($t);
	$t = Encode::encode('utf8', $t);  
	} 

So that the code now looks like this:

sub enc {
  my $t = shift;

  $t = Encode::decode('utf8', $t);

  if (defined($options{U})) {
	$t = decode_entities($t);
	$t = Encode::encode('utf8', $t);  
	}
  if (!defined($options{U})) {$t = Encode::decode('utf8', $t);}
  if (!defined($options{E}) || $options{E} =~ /amp/) {$t =~ s/&/&amp;/gs;}
  if (!defined($options{E}) || $options{E} =~ /quot/) {$t =~ s/"/&quot;/gs;}
  if (!defined($options{E}) || $options{E} =~ /apos/) {$t =~ s/'/&apos;/gs;}
  if (!defined($options{E}) || $options{E} =~ /lt/) {$t =~ s/</&lt;/gs;}
  if (!defined($options{E}) || $options{E} =~ /gt/) {$t =~ s/>/&gt;/gs;}
  if (defined($options{e})) {
    $t =~ s/([^\x20-\x7F])/'&#' . ord($1) . ';'/gse;
  }
  return $t;
} 

You're done save your changes and exit. 


       Creating a batch file and testing your Perl script. 


The first thing that you need to do is create an account at zap2it.Com. The account is free and is only required in order to save your channel lineup and preferences such as your favorite channels. Follow the instructions at http://zap2xml.awardspace.info labeled "zap2xml zap2it.com setup:" in regards to setting up your account. Ignore the instructions pertaining to running zap2xml, I'm going to show you how to set it up with the correct command line options. As far as Perl libraries are concerned, I didn't have any issues when running Strawberry Perl 32-bit. When running the Perl script, if Perl complains about missing libraries, simply make note of the library that is missing which will be apparent in the console output. Do a search on the internet in regards to how to install these libraries, it's not that complicated really. 

You're going to be running your Pearl script from a batch file. Simply open notepad and paste these lines:

set TZ=GMT
perl zap2xml.pl -u user@email.xx -p password -U -F -L -T -D -d 14 -N 7 -r 20 

The user and password are of course yours. Make sure you edit this line and replace "user@email.xx" and "password" with yours. I assume that you know how to create a batch file, however I will remind you that when saving the file you must click on "Save as type:" at the bottom of the dialogue and select "all files". Then give your file the ".bat" extension. If you do not select "all files" then your file will be saved with the extension ".bat.txt" and you don't want that. Name your file "mc2xml.bat". 

Some of the command line options listed in the batch file are required by the mc2xml plugin. Others are not. The "-D" option is the option that includes the extra program details as opposed to the simple one line descriptions. You do not have to use this option, however I highly recommend it. The one line descriptions can be insufficient at times. However, without the -D option, your downloads will be much faster. 

One of the options in particular is very important and without it you will get terrible results. I'm referring to "-N 7". At this point let me explain just a little bit about how zap2xml works so that you can understand why this option is so important. By default zap2xml will download and cache all program schedules and program details and save them in a subdirectory labeled cache. Upon subsequent runs, zap2xml will search this directory before it searches the website. If it finds a program schedule in this directory that's the one it will import. Over time this will give you horrible results. Your program schedules will be highly inaccurate. At first they'll be fine, however as the days go by, after a couple of weeks you will find the schedules to be useless. That's because the schedule that you're looking at will have been downloaded a couple of weeks ago. The zap2it schedules start off very inaccurate when they are first entered but become more accurate as the current day draws near. What you want is for today's schedule to have been downloaded within the last couple of days. On the command line above the number of days worth of scheduling to download is 14 (-d 14). What the -N option does is tell zap2xml not to cache the first N days worth of schedules. So in the command line above the first seven days worth of scheduling will not be cached and will be downloaded fresh daily. This will ensure that the next week worth of scheduling will be very accurate. The schedule you're looking at today will have only been downloaded yesterday. When I first used zap2xml I got horrible results until of course I figured this out. The program descriptions will always be cached which is fine because of course they never change. The program schedules download very quickly, however the program extra details take a long time to download so it's a very good thing that they cache. For an explanation of all the command line options, simply review the zap2xml website. However, If you want to change anything, keep in mind that some of these options are required by the mc2xml plugin. The mc2xml plug-in will call the batch file with a command line like this: 

C:\SageEPG\mc2xml.bat, -L, -u, -U, -F, -d, 336, -D, C:\Program Files (x86)\SageTV\SageTV\plugins\mc2xmlepg\Comcast\mc2xml.dat, -o, C:\Program Files (x86)\SageTV\SageTV\plugins\mc2xmlepg\Comcast\xmltv.xml

The options on this command line were meant for the mc2xml program. They're not intended for zap2xml even though they're very similar, however, since we're using a batch file they will be ignored in favor of the command line options I placed inside the batch file. I used the correct command line options to make zap2xml compatible with the mc2xml plugin.

If you selected "Show only my favorite channels in the grid" when setting up your Zap2it account preferences as recommended on the zap2xml website then these are the only channels that will be imported by the mc2xml plugin. If you did not select this preference then your entire channel lineup will be downloaded. This could take zap2xml quite some time. I highly recommend against it. 

     Testing your batch file 

The mc2xml plug-in has a bug. It will not be able to find your batch file if the folder you put it in has spaces in its path. This of course is a very common bug. Create a folder in your root directory. Name it mc2xml, zap2xml, EPG or whatever you want but place it in your root directory and make sure that it doesn't have any spaces in it like so: 

C:\EPG 

Place the batch file that you created above along with your edited zap2xml.pl script in this folder. Simply double-click on your batch file and zap2xml will start downloading the program information. When it's finished it will create a file named xmltv.xml. On its first run this may take a very very long time. This is especially the case if you have a lot of favorite Channels selected. However, keep in mind that upon its first run zap2xml builds up a huge cache. Subsequent runs of zap2xml will be much quicker. 

     Setting up the mc2xml plugin 

The following is an edited version of the original mc2xml plugin instructions:

Go to the list of available SageTV plugins in your Sage STV and choose to install the mc2xml EPG plugin.

*IMPORTANT:* If Sage says you must restart SageTV *DO NOT* perform the restart at this time.  Click "Restart Later" and continue on with the steps below.  Restarting now is not catastrophic, but it just means you'll have to do a second restart later on.

== Remove video sources ==

Now it's time to cut ties with the SageTV EPG service.  You *must* reconfigure all your video sources within SageTV, there is no choice.

From the standard STV, go to *Setup > Setup Video Sources*.

Click on each video source you have configured and on the next screen for each, click "Remove Source" on the left hand side.  Once you have removed all video sources then continue on to the next step.

== Configure plugin ==

It's now time to configure the EPG plugin.  Using the standard STV, select *Setup > SageTV Plugins > Installed Plugins*

Scroll down and click on the *mc2xml EPG Plugin* item then click on *Configure Plugin*.  *NOTE:* If the Configure Plugin option is not available then you must restart SageTV at this point then come back and load the plugin configuration screen.  In this case, you won't be able to avoid the multiple restarts.

*Location of mc2xml.bat:* Click the button on the right and point it to the location of mc2xml.bat that you created earlier.

Set "Number of Days to Download" to the same number as in the batch file -- the "-d" option (14 unless you changed it -- zap2it provides a maximum of 14 days).

Select "false" for all of the remaining options.

=== Windows ===

Open a command window and go to the following (equivalent) location:

C:\Program Files\SageTV\SageTV\plugins\mc2xmlepg\

*NOTE:* You may need administrator access to perform these tasks depending on the version of Windows you're using. Also, make sure that this SageTV directory is your active SageTV directory. After my last windows update. Windows changed my active SageTV directory to the VirtualStore at "C:\Users\username\AppData\Local\VirtualStore\Program Files (x86)\SageTV\SageTV". All of the actively written files were being written to this directory. If this is the case for you, then you should be working in this directory -- "C:\Users\username\AppData\Local\VirtualStore\Program Files (x86)\SageTV\SageTV\plugins\mc2xmlepg". Do a file search for Wiz.bin or Sage.properties and sort by date. If you have multiples, find the directory of the most recent version of these files. That's where you want to be! Also, if windows did move SageTV to the VirtualStore, then you'll have to edit your batch file because sage will erroneously run it in its original directory. If this is the case for you then add this to your batch:

cd C:\Users\username\AppData\Local\VirtualStore\Program Files (x86)\SageTV\SageTV\plugins\mc2xmlepg\Comcast
set TZ=GMT
perl zap2xml.pl -u user@email.xx -p password -U -F -L -T -D -d 14 -N 7 -r 20 

Where "username" is your username.

Create a lineup directory, name it whatever you like (I suggest a short form of your lineup name, but anything will do).

Let's say you named it "sd_east"

Go inside the new directory and create a file called "lineup.properties" and put the following contents inside the file:

id=1000
name=Shaw Direct East (Classic)

The "name" value can be anything and is how the lineup will be presented to you within SageTV.

The "id" *must* be a positive integer and *must* be unique across all lineups you create. (These instructions are for a single lineup configuration. To have multiple lineups you would have to write a more sophisticated batch file. Originally mc2xml would run in each directory you created and read its settings from a file named mc2xml.dat. Mc2xml.dat would be different in each directory and contain settings to download a different lineup. Zap2xml doesn't do this, however, if you created a batch file that reads user/password from this file and inserts it on the command line, then you could achieve multiple lineups. I'm not offering instructions to do this.)

Now go back into the directory you created that contains your batch file. Move the cache directory and all the files that zap2xml created including the zap2xml.pl script into the lineup directory that you just created above -- "sd_east". Leave the batch file where it is. It should be the only file left in that directory. 

And lastly, as mentioned above mc2xml creates a file called "mc2xml.dat". Zap2xml does not, however the mc2xml plug-in checks for this file and it won't work without it. So we have to create a dummy file. Create a text file and name it "mc2xml.dat". Just as when you created your batch, file remember to select "all files" in notepad when you save this file so that it gets the correct ".dat" extension. Save it in your lineup directory along with the rest of the files.

== Restart SageTV ==

Restart your SageTV server.  Upon restart, you should be taken the video source configuration wizard.

== Reconfigure video sources ==

Reconfigure each of your video sources.  Now when you select your EPG lineup, you should be presented with the lineup you configured earlier.

*NOTE:* Be patient when configuring your lineup as a complete EPG download and update must be performed before your channels are presented. Depending on the number of channels, your internet speed, and your hardware, this can be _very_ slow - up to 20 minutes.  Be patient and if after 20 minutes the screen is stuck then check the "sagetv_0.txt" log file for errors or the "\SageTV\plugins\mc2xmlepg\logs\*.log" files for errors.

Once the EPG update is complete, you can select your channels, etc.  From this point forward, you complete your lineup configurations just like using the SageTV EPG service.

= Upgrading the Plugin =

Upgrading the plugin is rather straightforward, simply apply the plugin updates when you're alerted about them.  You do *not* need to reconfigure mc2xml after plugin updates.

Please apply updates when they're made available, especially during the v0.x betas.  Unlike most plugins, if you're using this one then it's providing a rather critical service to your SageTV system and running the latest version available will be critical to proper EPG data being inserted into your wiz.bin.

= Uninstalling Plugin =

== Before Uninstalling ==

If you decide to stop using the mc2xml plugin please be aware that when you switch back to the Sage EPG service that you might end up recording shows that you've already recorded.  This is because some shows use a zero padded show ID with mc2xml and those leading zeros are stripped by the Sage EPG service.  Since the show IDs aren't identical, Sage will not consider those airings recorded when you switch EPG services.  This is more inconvenient than anything, but it is something to be aware of.

Follow the steps below to uninstall this plugin.

== Remove video sources ==

First you must remove all your video sources and reconfigure them after completely removing the EPG plugin.

Go to *Setup > Video Sources*
Remove each video source.

== Uninstall SageTV plugin ==

Go to *Setup > SageTV Plugins > Installed Plugins*

Select and uninstall the mc2xml EPG plugin.

*NOTE:* If Sage asks you to restart SageTV then say *NO* and do it later.  You need to modify the "Sage.properties" file before restarting so don't bother doing a restart right now.

== Stop SageTV ==

Stop SageTV at this point.  Before restarting it, do the next step.

== Remove EPG plugin property ==

Edit your "Sage.properties" file and look for a line that starts with "epg/epg_import_plugin"

The line should actually read:

epg/epg_import_plugin=com.google.code.sagetvaddons.mc2xmlepg.EPGImportPluginMc2Xml

Change it so it reads:

epg/epg_import_plugin=

Making this edit is what actually removes the EPG plugin from your system.

== Restart SageTV ==

Now restart SageTV.  Your server will now switch back to the SageTV EPG service.

== Reconfigure video sources with Sage/alternate EPG service ==

When you connect to the server for the first time you should be taken back to the video source configuration wizard, which will allow you to reconfigure your video sources.  At this stage, you just reconfigure your video sources as normal.