+--------------------------------------------------+
| if you are reading this after launching OLBreak, |
| it means command-line parameters were mistyped. |
| |
| see details hereunder. |
+--------------------------------------------------+
OLBreak v2.3
~~~~~~~~~~~~~
by Or Ben Shabat
In This Document
~~~~~~~~~~~~~~~~~
! SCRIPT-BREAKING CHANGES !
Summary
Features
How To Use
Limitations
The Result
Exit Codes
Test Matrix
OLBreak and EVACopy
Open Source
Contact
Thanks
+-------------------------------------------------------------------------------+
| v1.x to v2.x : SCRIPT-BREAKING CHANGES ! |
+-------------------------------------------------------------------------------+
| |
| FILING FOLDER NAMING |
| |
| filing folder is now determined by profile name, no longer by email address. |
| if you are upgrading OLBreak, and using it as a differential backup tool, |
| then you need to manually rename the backup folder. |
| see the example in the "How To Use" section hereunder. |
| |
| COMMAND LINE PARAMETERS |
| |
| complete redefinition of all command line parameters. |
| details in section "How To Use" hereunder. |
| |
| MODE OF OPERATION |
| |
| until v2.0, OLBreak would delete from the filing folder any items that were |
| removed from Outlook. this default behaviour is now changed, and is now |
| controlled by the /mod parameter. |
| |
| EXIT CODES |
| |
| exit codes were redefined. details in section "Exit Codes" hereunder. |
+-------------------------------------------------------------------------------+
Summary
~~~~~~~~
OLBreak is a PST to MSG converter for Outlook.
it converts Outlook mail store to its elements as MSG files, maintaining folders structure.
Features
~~~~~~~~~
* Duplicates Filtering
* Accumulative or Differential Processing
* Invalid Characters Handling
* Automation-Ready by Command-Line Parameters and Exit Codes
* Detailed Logging
* Exchange Mailbox Support
* Automatically Acknowledge Outlook Security Warnings
* Portable, Open-Source, and Free for any use
How To Use
~~~~~~~~~~~
OLBreak accepts the following command-line parameters:
required:
/src: mail store(s)
/dst: filing folder
optional:
/mod: mode of operation. options: keep|hide|delete
/log: log file name
/msg: verbosity level. options: on|off
/src: source mail store names, as presented by Outlook. special characters can be used:
* indicates the default mail store (the "Mail Delivery Location")
; separates several mail stores
/dst: destination filing folder to store the files.
this is the "root" folder; within this folder, OLBreak creates tree structure by the profile name, mail store name, folders and subfolders.
/mod: mode of operation.
for all modes of operation, the following rules apply:
- new Outlook items are added to the filing folder.
- updated Outlook items overwrite existing items in the filing folder.
operation modes differ by the way they handle items that were removed from Outlook:
- keep: items removed from Outlook are left untouched in the filing folder. (default)
- hide: items removed from Outlook have their 'Hidden' attribute set.
- delete: items removed from Outlook are DELETED from the filing folder. *** IRREVERSIBLE !!! ***
note: in "hide" mode, empty folders are deleted.
/log: log file name.
if omitted, log file is placed in the root filing folder by the name "OLBreak.log".
if the filing folder is unavailable or inaccessible, the log file is placed in %temp%.
log entries are appended to existing log file.
/msg: this parameter sets if error messages will be displayed for the user.
on: error messages will be displayed. (default)
off: error messages will not be displayed.
all error messages have timeout, so never does OLBreak wait forever for user interaction.
Example:
assume your Outlook profile is "John Doe", you receive POP3 messages to "Personal Folders",
and you also have "Archive Folders". you want to extract it all to "F:\My Outlook Items".
use the following syntax:
OLBreak.exe /src:"*;Archive folders" /dst:"F:\My Outlook Items"
your Outlook items will be stored in the followng subfolders:
"F:\My Outlook Items\John Doe\Personal Folders"
"F:\My Outlook Items\John Doe\Archive Folders"
within these folders, your messages will be stored in the exact folder structure as in Outlook.
messages are named by the sender, recepient, time and subject;
other items are named by their title.
NOTE:
in case the current profile can not be determined:
- if an email account is set-up, the email address will be used.
- if an Exchange account is set-up, then Exchange CN (Common Name) is used.
- if no email account is set-up, then instead of the email address, the reserved word "Unknown" is used.
NOTE:
it is common to have several mail stores by the default name "Personal Folders".
avoid having several stores by the same name, as OLBreak will process only one of them!
NOTE:
to keep distinction between Windows users, for /dst use something like:
C:\backup\Outlook\%USERNAME%
Limitations
~~~~~~~~~~~~
- OLBreak will not process Outlook folders that have a backslash character ("\") in the folder name.
- OLBreak will not process non-mail items that have no title ('subject').
- avoid having several stores by the same name, as OLBreak will process only one of them.
- Outlook XP is NOT SUPPORTED! workaround: to extract items from Outlook XP, load the PST file to another pc with Outlook 2003 or later.
The Result
~~~~~~~~~~~
you can browse the filing folder with any file manager.
for best readability, use "Details" mode. In this mode, you can see the NAME of the file, and the TIME.
you are advised to sort the folder contents by NAME or by TIME.
for files that represent email messages:
the TIME of the file is the time of the message; so sorting by TIME in the filing folder is equivalent to the same sorting in Outlook.
the NAME format is:
[sender_email -to- recipient_name] subject [at YYYYMMDDhhmmss].MSG
so if you sort by NAME, you actually sort by the sender's email address.
for the "Sent Items" folder, the sender's email address is idenical (yours), so you actually sort by the recipient's name.
for other files (Contacts, Notes etc.):
the NAME is the title ('subject') of the item.
the TIME is the last modification time of the item.
Exit Codes
~~~~~~~~~~~
OLBreak returns the following exit codes:
(devided to categories for better understanding)
----- no error
0 program completed successfully
----- application error
1 invalid parameters
2 filing folder is unavailable or inaccessible
3 Outlook is not running
4 error connecting to Outlook
5 can not check Outlook version
6 Outlook version is not supported
7 error determining profile name, email address or user name
----- mail store error
8 error finding store root object
9 error finding store root name
10 error parsing folder tree
----- folder error
11 error creating folder
12 error getting Object and StoreID of a folder
13 error getting folder data
----- item error
14 error getting item data
15 error saving an item
application errors lower than 7 are critical and will terminate the program.
a mail store error will skip the impacted mailstore and proceed to the next.
a folder error will skip the impacted folder and proceed to the next.
an item error will skip the impacted item and proceed to the next.
Test Matrix
~~~~~~~~~~~~
OLBreak was successfully tested as per the following table:
(mail store type per Outlook version)
| 2003 | 2007 | 2010 | 2013 |
--------+-------+-------+-------+-------+
local | v | v | v | v |
--------+-------+-------+-------+-------+
POP3 | v | v | | |
--------+-------+-------+-------+-------+
IMAP | v | v | v | v |
--------+-------+-------+-------+-------+
Exchange| | | v | v* | *ActiveSync
--------+-------+-------+-------+-------+
OLBreak and EVACopy
~~~~~~~~~~~~~~~~~~~~
although usefull as a standalone application, OLBreak was initially designed as a PREP phase for EVACopy:
http://evacopy.sourceforge.net
Open Source
~~~~~~~~~~~~
OLBreak is an Autoit v3.3.8.1 program, using customized version of the OutlookEx UDF v0.9.0.0
the following files are the source code components:
OutlookExConstants.au3 - auxiliary data for the OutlookEx UDF
OutlookEx5.au3 - the customized OutlookEx UDF
OLWrnAck.au3 - auxiliary program used to acknowledge Outlook security warnings
OLWrnAck.ico - icon file for OLWrnAck
OLBreak_ReadMe.txt - this file, displayed when command-line parameters are omitted or mistyped
OLBreak.au3 - main program file
OLBreak.ico - icon file for OLBreak
To build OLBreak from the source, follow these steps:
1) download all of the above mentioned files into the same folder.
2) install AutoIt v3.3.8.1
3) build OLWrnAck.au3 into OLWrnAck.exe
4) build OLBreak.au3 into OLBreak.exe
Contact
~~~~~~~~
feature requests, bug reports, questions, and applause:
or.ben.shabat@gmail.com
Thanks
~~~~~~~
major thanks to all AutoIt developers and members of the AutoIt community!
special gratitude to water for his amazing UDF:
http://www.autoitscript.com/forum/topic/126357-outlookex-udf-help-support/
Enjoy!