Contents
The Portman™ 2.1 online help

What's new and improved

Overview

How to use The Portman's online help

Main dialog and operations

Setting preferences

Transferring files

Field mapping tips

From Portfolio™ to CSV

From CSV to Portfolio™


Overview

The Portman is a set of utilities that eases the process of exchanging data between the Atari Portfolio™ and a PC running Windows™ 3.1 or later.  As one would expect Portman converts data or exports data from one format to another.  It also provides a "Point and click" interface for two popular file transfer utilities used with the Portfolio.  The following is a complete list of The Portman 2.0 features:

Wrap text	This feature enables you to wrap text so it will fit the Portfolio's 40 column screen.  It is compatible with the Portfolio's editor and can be used for address book files that have data which do not need to fit a strict pattern of fields.
Unwrap text	This feature will unwrap text previously wrapped by the Portfolio's editor or by The Portman itself.  Gives a better view on the PC of files created on the Portfolio.
ANSI to OEM	Converts text created in Windows(tm) to the character set used by the Original Equipment Manufacturer of your hardware (DOS text).
OEM to ANSI	Converts text created in DOS to the ANSI character set used by Windows(tm).
CSV to Portfolio	Exports data stored in Comma Separated Value format (a.k.a. comma delimited data) to a form usable by the Portfolio's internal applications.
ADR to CSV	Exports data from the Address Book to a comma separated value format.
CRD to ADR	Exports data from Windows™ Cardfile .CRD files.  The file in question can only contain text.  .CRD files that contain other objects will be reported as not being a .CRD file
File transfer	Provides a "point and click" interface for either FT.COM or A&R-Link, two utilities used with the Portfolio to transfer files via the parrallel port.
See also: Main dialog and operations


CSV

CSV or Comma Separated Value format, often called Comma Delimited Data (.CD), is a widely used format to exchange data between applications such as between databases and word processors.  It is a text base format in which fields of a record are placed between quotation marks and separated by a comma ("field 1","field 2","field 3","...).


What's new...
What's new and Improved in version 2.1

New utility, new approach

The Portman™ version 2.1 now offers conversion from Windows™ Cardfile to Portfolio address book on top of the previously available utilities (see Overview).

The Portman™ also takes a new and simpler approach to data synchronization.  Version 2.0 boasted a system that remembered the structure of the original . CSV file to help reverse data exporting between Comma Delimited format and Address Book format.  Awkward and badly implemented this feature was almost totally unusable.

In version 2.1, The Portmans CSV to ADR provides field mapping with insertion of infield separators, for mapping more than one CSV field to the same ADR line, and marks address book lines that originate from a mutilined field.

These features are used by the ADR to CSV utility to restore the original field struture.  Although the fields may end up in different places in the resulting record the data is restored to their respective fields (i.e.  What came from two fields and mapped to one line is exported back to two fields.  What was one field with several lines is exported back as one field).  The importing software usually provides field mapping so you can place these fields back in their original position.

NOTE:  The multilined field processing has only been tested with CSV data coming from Lotus Organizer™ which ends lines within a field with the single CR (0DH) ASCII control code.

Bugs killed

The Remember original structure feature of the CSV to ADR utility would scramble records under certain conditions.  This feature has been replaced by infield separators and Multilined field marking.


Using Portman's online help
Using The Portman's online help

To access the online help:

From The Portman's main dialog box click the Help menu then select Help Index

From anywhere in The Portman press F1.

Using Hypergraphics

When in The Portman's online help you will often find a picture of a dialog box or of one of its parts.  To display help about one of the elements in the picture simply move the mouse cursor over the desired element, if the cursor changes to a finger pointing hand help is available by clicking the left mouse button once.  If there is no pointing hand there is no information available for the pointed to element.  Note that some pictures are there only to illustrate a topic while others will serve as links to other topics.  Generally, pictures that illustrate a topic only show one element while hypergraphics display many.


Main dialog box...
Main dialog box and operations

Click an element of the dialog box to get help.


Export Cardfile data to the Portfolio
Exporting Cardfile data to the Portfolio

To export data from the Windows™ Cardfile to the Portfolios address book select a Cardfile file in the File to work on box of the Main dialog box, select Conversions then click the CRD to ADR button [image].  You will then be prompted to keep or discard the Cardfile record indexes:

 Clicking Yes will make each Cardfile record index as the first line of the address book record.  Clicking No simply discards the Cardfile indexes.


File menu

File transfer...	This selection brings up the file transfer dialog box.
Preferences	Click this item to access the Preferences dialog box.
Exit	Clicking this selection ends The Portman's session.


Help Menu

Help Index	Choosing this item will display the contents of The Portman's on-line help.
About The Portman...	This selection will display The Portman's version number and copyright notice.


Full path:

Displays the current path.  If a file has been selected in the File to work on: combo box then the selected file name is added to the path.


File to work on:

Click the drop control to select a file in the current directory on which you wish to perform an operation.


Directory:

Click the drop control to select a new directory.


Drive:

Click the drop control to select a new drive.


Open file

Click this button to open the file selected in File to work on: using its associated application.


Delete file

Click this button to delete the file selected in File to work on:.


Execute

Click this button to execute the chosen operation(s) you wish to perform on the file selected in File to work on:.


Operations & Conversions

Selecting the Operations button displays the following operations: Wrap text, Unwrap text, ANSI to OEM and OEM to ANSI.  It is possible to combine different types of operations.

Selecting the Conversions button displays the three exporting methods: CSV to Portfolio, ADR to CSV and CRD to ADR.


Wrap Text

Check this box to wrap a text file to the width specified in the edit box on the right.  The default width is 37 columns.  You can change the wrap width by typing a new value in the edit box.  You can also set a different default value via the preferences dialog box. See: Setting preferences Can be combined with ANSI to OEM or OEM to ANSI.


Unwrap text

Check this box to unwrap a text file that had previously been wrapped by the Portfolio editor's wrap feature or by The Portman.  Can be combined with ANSI to OEM or OEM to ANSI.


ANSI to OEM

Check this box to convert text written using the ANSI character set to text written using the ASCII character set.  Can be combined with Wrap text or Unwrap text.


OEM to ANSI

Check this box to convert text that was written using the ASCII character set to text written using the ANSI character set.  Can be combined with Wrap text or Unwrap text.


Setting preferences

Click an element of the dialog box to get help.


Setting file transfer preferences

This section of the preferences dialog box lets you specify which transfer utility The Portman should provide with a point and click interface.

First check the box corresponding to the utility you use (either FT.COM or A&R-Link), then type the full path and filename of the corresponding utility (Example: c:\pofo\ft.com) in the edit box provided.  If you have elected to use A&R-Link you must also check the box corresponding to the parallel port you use to transfer files: either LPT1 or LPT2.

For more information about these file transfer utilities consult their respective documentation.


Set CSV to Port preferences
Setting CSV to Portfolio exporting preferences

This section lets you set the default behavior of the CSV to Portfolio exporting feature.

You first set the default target type by checking either the .adr (Address Book file format) or the .dry (Diary file format) box.

The Portman offers the possibility of automatically deleting the source file after an exporting operation.  Check Delete source to make this the default behavior when exporting data to Portfolio formats.

When targeting Portfolio file formats from Windows you often need to convert the text from the ANSI character set to the ASCII character set.  The Portman can do this conversion during an exporting operation.  Check ANSI to OEM to make this the default behavior.

See also: Overview., From CSV to Portfolio™


Set ADR to CSV exporting preferences
Setting ADR to CSV exporting preferences

This section lets you set the default behavior of The Portman's Address Book to Comma Separated Value format exporting feature.

Strip phone, Standard, Merge fields and Two fields are modes that affect how The Portman exports Address Book data to CSV format.  Check the mode(s) you want to set as the default mode(s).  See From Portfolio™ to CSV for information on using different exporting modes.

The Portman offers the possibility of automatically deleting the source file after an exporting operation.  Check Delete source to make this the default behavior when exporting data to CSV format.

When targeting CSV format from the Portfolio you often need to convert the text from the ASCII character set to the ANSI character set.  The Portman can do this conversion during an exporting operation.  Check OEM to ANSI to make this the default behavior.

See also: Overview., From Portfolio™ to CSV


Wrap at:

In the Wrap at: edit box type in the width, in columns, to which you want to wrap a text file.  To wrap a text  to fit in the Portfolio's screen set the default at 37.


OK

Click this button to exit the preferences dialog box and save the default settings.


Cancel

Click this button to exit the preferences dialog box without saving any changes you make to the default settings.


Help

Click this button to get help about the preferences dialog box.


Using Portman to transfer files
Using The Portman to transfer files

If you already use the Portfolio's parallel interface to transfer files to and from your PC using Atari's FT.COM or Klaus Rieke's A&R-Link, The Portman is about to make this task an easy affair by providing a "Point and Click" interface for these popular transfer utilities.  You must have one of these utilities: The Portman does not transfer files on its own.

To setup FT.COM or A&R-Link to work with The Portman see Setting preferences

Depending upon which transfer utility you set The Portman to use, the file transfer dialog box will display different control names as shown below.  Click elements in this picture to find out how they work.


Current directory

This box displays the current drive and directory.  To change it you use the Drive: and Directory: combo boxes.


List box

This list box displays the files in the current directory.  Select a file or files in this box to transfer to the Portfolio.  To select a single file simply click it.  To select multiple files: use the Shift key plus the left mouse button to mark a range of files or the Ctrl key and left mouse button to select files one at a time.


Select All

Click this button to select all the files displayed in the list box


FT Send

Click this button to send the files selected in the list box to the Portfolio.


FT Server

Click this button to put FT.COM in server mode for transferring files from the Portfolio.


FT menu

Click this button to use FT.COM directly in its menu driven mode.


Done

Click this button to return to The Portman's main dialog box.


A&R-Link Send

Click this button to send the files selected in the list box to the Portfolio.


A&R-Link Receive

Click this button to receive files sent from the Portfolio.


A&R-Link Restore

Click this button to send all the files contained in the current directory and sub directories to the Portfolio.


Export Address book to CSV dialog box

Click the picture's elements to get help.


Export CSV to Portfolio dialog box

Click the picture's elements to get help.


Source file statistics

This area displays information on the source file and includes the file name and path, the size of the file in bytes and the number of records it contains.


Edit Source

This button opens the source file using the Windows™ Notepad.


Export

Click his button to start the exporting process which first displays the Output records dialog box.


Cancel

Click this button to exit without exporting any data.


ANSI to OEM
OEM to ANSI

Check this box for automatic conversion from the OEM's character set to the ANSI character set.


Delete source

Check this box to have the source file deleted upon completion of the exporting process.


Target file

This area displays the name and path of the file that will receive the exported data, as well as controls to modify the exporting process.  Among the controls two drop down combo-boxes let you specify the destination drive and directory.


Strip phone

Check this box if your address book records have phone numbers on the first line and you wish to put them in their own field.  This feature only checks the first line for phone numbers and simply parses it on the first digit, "[" or "(" it encounters.


Merge fields

Check this box to have The Portman merge lines that originated from a single multi - lined field originally exported to the Portfolio™ from Lotus Organizer™.  Note that this feature will merge an address book line that ends with a space character ( ) with the following line and place them in one single CSV field.


Standard

This check box specifies the standard exporting method that places each address book line in a field of its own.  It can be combined with the Strip phone mode.  This box must be checked to enable infield parsing in the Output records dialog box that is accessed through the Export button.


Two fields

Check this box to put the first line in the first field and all subsequent lines in the second field or third field if the Strip phone mode is checked.  Lines put in this field are separated by the "|" character.


Target directory:

This drop down combo-box lets you select a new directory for the target file.


Target drive
Target drive:

This drop down combo-box lets you select a new drive for the target file.


File type:

If you are targeting address book files check the .adr box.  If you are targeting diary files check the .dry box.


Export

Click his button to start the exporting process which first displays the Map fields dialog box.


ANSI to OEM

Check this box for automatic conversion during the exporting process from the ANSI character set to the OEM's character set.


Field mapping tips

This section provides insight on the different ways The Portman exports data between the Portfolio and Comma delimited data format.

From CSV to Portfolio™

More often then not, PIMs use many more fields to organize data than normally used by the Portfolio's address book or diary to organize the same data.  The main reason for this is that the address book displays its lines or fields one below the other and cannot combine them for display purposes.  Users of the Address book will typically put the first and last name on the same line when, for example, each has its own separate field in Lotus® Organizer™.  Simply mapping one Organizer™ field to one address book line will generally produce an awkward record to both use and read.  For the diary, the Portfolio™ is even more restrictive: it allows only two fields the first containing the date in dd/mm/yy format and all other information in the second field starting with the time in hh:mm format.  Copying alarm information is PIM specific and is not supported by The Portman.  Figure 1 shows a typical PIM field structure and the Address book structure side by side.

Mapping fields as shown in figure 1 solves the problem of displaying in the Address book (or diary) records originating from other software.  However this poses the problem of re-exporting the data from the new address book format to the original format.  The Portman provides automatic insertion of infield separators that it can later use to split the address book line into the original number of fields.  The Map fields dialog box provides an edit box to specify an infield separator composed of up to three characters.  The default separator is made up of three white space characters ("   ").  Field position is entirely another matter.  The Portfolio's address book further complicates things by refusing to display records whose first line is empty (or only contains white spaces) and by making two records out of one if it contains two successive empty fields after the first one.

Referring to figure one, if one record of your Organizer's address section only contains a company name and its address, if mapped as in Figure 1 the resulting address book record would start with two empty lines and the Portfolio™ would not display it.  To solve this problem, and that of in-record empty fields, The Portman provides a special formatting feature that eliminates the first field if it's empty and formats in-record empty fields so the Portfolio's™ address book will recognize them.  This is handy if you simply export data one way to your Portfolio™, but beware, this may make your records' data structure inconsistent and prevent reverse processing (Going back to the original format).

See also: Export CSV to Portfolio dialog box.

From Portfolio to CSV

The Portman does not support exporting Diary data to the CSV format.  This feature will only be added in a future version if demand justifies it.  See Reaching the author to find out how to contact and let him know if you would use such a feature.

If the Address book data you are exporting to the CSV format was entirely created on the Portfolio™, you need to assert that all records are consistent, meaning they all display information in exactly the same way, otherwise the target software may not be able to properly process the data.

The Portman exports address book data to the CSV format one of five different ways.  The "Standard" mode will put each address book line in its own field.  The "Two fields" mode will put the first address book line in one field and all subsequent lines in a second field, producing a record with two fields.  These first two modes can be combined with the "Strip phone" mode for two additional ways of exporting the data.  These are handy if you use the Portfolio's™ dialing feature and have put phone numbers on the first line of your address book records.  The "Strip phone" mode will strip a phone number off the first line of an address book record and put it in its own field.  The final way The Portman exports Address book data to the CSV format is by using information stored when the data was first exported from the CSV format to the address book.  This feature will completely reverse the process, including field position, in as much as any records added to the file respect the data structure defined when the data was first exported from the CSV format to the Address book format, including using the same infield separators.  These modes are set in the Export Address book to CSV dialog box.


Reaching the author

Hello!

My name is Jean-François Davignon and I have written The Portman as a learning project.  I use it every week to transfer data between my PC and my Portfolio™.  It is very useful to me and has extended my Portfolio's™ usefulness.  I have elected to make it available as FREEWARE with all rights reserved and without a warranty of any kind, either expressed or implied.  You are allowed to freely use and distribute The Portman for non-profit purposes only.

I have tested its CSV to Portfolio (and vice versa) features exclusively with data coming from Lotus© Organizer™.  It should work with any CSV format data in as much as multi-lined fields use a single carriage-return character (CR -- 0DH) to mark new lines.

Bug reports, suggestions and comments would be greatly appreciated.  Bugs will be killed and suggestions seriously considered.  Please send them by one of the following routes:

Mail:

Jean-François Davigon

2210, de la Paix

Québec (Québec) Canada

G1L 3S7

Phone:

(418)524-1294

E_Mail:

CompuServe: 71514,3244

Internet: jfdav@ibm.net

Fax:

(418) 649-0579


Map fields

Click an element in the dialog box to get help.


Address book lines:

This list box displays the line numbers of an address book record as if they were fields as well as the fields you have mapped to the lines.

To copy a field or fields from the CSV fields: list box select the target address book line by clicking it once then double-click the CSV field you wish to copy.  You can also copy a CSV field by selecting it and then clicking the Map field button.

Double clicking on any address book line will un-map all lines.


CSV fields:

This list box displays the first record extracted from the CSV file.  Some applications that export to this format will let you place field names in the first record.  This is good practice and eases the field mapping process.

To map a CSV field to an Address book line start by selecting a target line and then double-click the CSV field you wish to map to the target line.  You can also click the Map field button after selecting the CSV field.

You can map several CSV fields to a single Address book line but you can only map a CSV field once.


Map field

Click this button after selecting the source and destination fields to map them together.


Map All

Click this button to map all CSV fields to their corresponding Address book field number.

This button's caption changes to Unmap All as soon as at least one field is mapped.  It is not possible to un-map only one selection.


OK

Click this button to execute the exporting process.  At least one field must be mapped for the process to work.  If no field is mapped this button will do nothing.


Cancel

Click this button to exit the Map fields dialog box without launching the exporting process.


1st source record has field names

Check this box if the CSV fields: list box contains field names instead of an actual record and you do not wish to copy the field names to the Address book file.


Infield separator

This edit control lets you specify an "Infield Separator" that will separate CSV fields that are mapped to the same address book field.  These separators can be used to reverse the process when Exporting Address book data to comma delimited format .  The default delimiter is three spaces("   ").


Output Records

Click an element in the dialog box to get help.


Split fields on separator

Check this box if some fields (lines) in your address book records contain infield separators and you wish to create separate destination fields for data delimited by these separators.  The default separator is three spaces ("   ") or you can specify a different one in the edit box provided.


First record has field names

Check this box to enable the Set field names section of this dialog box.


Set field names

This section lets you add a record that contains field names to use for field mapping by other software.  Simply type the name of the field in the edit box then press the Alt+A keys or click the Add name button to copy the field name to the field name list.  The Reset list button erases all the field names in the list.

Remember to enter field names in the order the fields appear in the address book record.

See Field mapping tips for additional information on using this feature.


OK

Click this button to accept the settings and launch the exporting process.


Cancel

Click this button to exit the Output records dialog box without launching the exporting process.


ERROR: Extra fields

When this message box appears it means that The Portman encountered a record or records that contain more fields than the first record had.  The extra fields were not exported.

The Portman uses the first record's data structure to guide its exporting process.  This record will often contain field names for the purpose of field mapping.

To overcome this situation you can:

1.	Make sure all records present the same number of fields;
or
2.	Make sure the first record has the most fields;
or
3.	Use Window's™ Notepad to add a record of field names and making sure this record has the most fields.  Place this record first.


ERROR: Not a CSV file

The file selected does not have a .CSV or .CD extension.  Make sure the file contains  CSV data then rename it with either the .CSV or .CD extension (Example: myfile.csv or myfile.cd).


ERROR: Not an ADR file

The file selected does not have an .ADR extension.  Make sure the file contains address book data then rename it with the .ADR extension (Example: myfile.adr).


ERROR: No Association

This message box appears when you try to open a file which is not associated with any application in Window's™ registration database or with file manager.

To create an association, open file manager, display the directory in which the file you wish to associate is and select the file.  Now, from file manager's file menu select "Associate...", then in the list box select the application that opens the file.  If it is not listed in the list box use the "Browse..." feature to find and select it.  For more information refer to file manager's on-line help.


ERROR: No transfer utility

This message box appears when you try to use The Portman's file transfer dialog box without having selected a file transfer utility to use.  See Using The Portman to transfer files


No File selected
ERROR: You Must select a file...

This message box appears when you pressed one of the Conversions button with no file selected in the File to work on: drop list.  Select the file from which you wish to export data then press the corresponding Conversions button.

See also: Main dialog box


No file to execute
ERROR: You Must select a file And operation...

This message box appears when you pressed the Execute button with no file selected in the File to work on: drop list.  Select the file from which you wish to process then press the Execute button.

See also: Main dialog box


Unable to delete
ERROR: Unable to delete

This message box appears when The Portman is not able to delete the file you specified.  This can be caused by several factors, the most common are the file is being used by another process or the file has the read only attribute.  Try using Windows™ File Manager to delete the file.


Change file name dialog box

When exporting data The Portman creates a default name for the target file.  This name is created using the name of the source file and changing the extension to either .adr, .dry or .csv to reflect the target data type.

If the default name already exists you are prompted with a question asking you if you wish to overwrite the existing file.  You may respond by yes to overwrite the file, by cancel to cancel the whole process, or by no in which case this dialog box appears so you can change the name.  The file extension will always be forced to appropriately correspond to the current target type (i.e. .CSV or .ADR or .DRY depending on the exporting process).