CDIL Archive Lab

Lab Overview
Initializing and Disposing
Connecting and Disconnecting
Reading and Writing
Status
Other Things To Try...
Where To Go From Here...
Notes

Lab Overview
This lab involves adding the code to implement an archiving program which allows strings to be uploaded from the Newton to the desktop machine for later retrieval. The code supporting the user interface and file I/O for the application is already in place and you will write the CDIL code to initialize and connect a CDIL pipe, read and write to the Newton using an established protocol and then disconnect and dispose of the pipe once the transfer of data is done. In addition a status dialog

Prerequisites
To do this lab you must have the following:
If you look in the CDIL Archive Code you will find a reference to both a Windows and a Macintosh versions of the code. Each of these versions have the source code files and either a make file (for the Windows and Macintosh MPW code) or a Metrowerks project file (for the Macintosh Code Warrior version) which will allow you to compile and run the lab.

Files Needed
You must have the following files available to you:

On a Macintosh:
Metrowerks:
1. Metrowerks project
2. CDIL library CDIL.CW6.lib (for Metrowerks 6 or later) or
the PPC version CDILPPC.CW6.lib
3. Universal header file for the CDIL (DILCPIPE.H)
4. Source code files PROTOCOL.C and DILArchive.c
5. The resource file DILArchive.rsrc
6. The following libraries:
a. MacOS.lib - for interface code
b. ANSI (2i) C.68K.lib (or PPC version) - for file I/O code
c. CPlusPlus.lib - for CDIL which was written in C++
d. MathLib68K (2i).lib (or PPC version) - for converting numbers to strings
e. SIOUX.68K.lib (or PPC version) - for I/O input formatting

MPW:
1. MPW makefile CDILArchiveMPW.make
2. CDIL library CDIL.MPW.Lib
3. Universal header file for CDIL (DILCPIPE.H)
4. Source code files PROTOCOL.C and DILArchive.c
5. The resource file DILArchive.rsrc
6. A fairly recent version of MPW with the following libraries:
a. CPlusLib.o
b. StdClib.o
c. Runtime.o
d. Interface.o

On a Windows machine:
1. Make file DILARCHI.MAK (for Visual C++)
2. Source code files DILARCHI.C, PROTOCOL.C
3. Application Header files DILARCHI.H, PROTOCOL.H
4. CDIL header file DILCPIPE.H
5. CDIL DLL file CDIL_DLL.DLL (16-bit version) or
CDIL32.DLL (32 bit version)
6. CDIL DLL library file CDIL_DLL.LIB (16-bit version) or
CDIL32.LIB (32 bit version)
7. Support files DILARCHI.ICO, DILARCHI.DEF and DILARCHI.RC for the minimized icon information, the module definition information and the application resources.
8. Windows SDK (Software Developer's Kit) for usual window libraries, etc.


Code Overview
The protocol used in the Archive application is shown below:

Sending:
<connect>
Newton->desktop "Sending"
Newton->desktop <data format - "STR " or "FRAM">
desktop->Newton "READY"
Newton->desktop <length> (of string)
Newton->desktop <data>
desktop->Newton "CONFIRMED" or "ABORT"
Newton->desktop "End " or "More" or "Abrt"
<disconnect>

Receiving:
<connect>
Newton->desktop "Receive"
desktop->Newton "READY FOR <data format- "STR " or "FRAM">"
Newton->desktop "Ready"
desktop->Newton <specially terminated string>
Newton->desktop "Conf" or "Abrt"
desktop->Newton "END ARCHIVE" or "MORE" or "ABORT"
Newton->desktop "End "
<disconnect>

This protocol describes the dialog between the two machines. Essentially the Newton controls the dialog as it starts and ends communications. The format of the data being sent (STR or FRAM) is used to distinguish between Newton strings and frames. In this lab we will only be transferring strings but in the FDIL lab, we will add the ability to send and receive Newton frames. The control messages from the Newton to the desktop machine are sent as 4 character strings. The messages from the desktop to the Newton are sent as variable length strings terminated with the EOT (0x04) character. The length of the data being transferred from the Newton to the desktop is sent as a short integer followed by the actual string data. From the desktop to the Newton the data is sent as a string with an EOT character added to the end.

Note that this difference in format is because the CDIL needs to know how much data to read or write through a pipe while the Newton can simply look for a specific character as a terminator.

As with most communications protocols, there is a certain amount of redundant "talk and response" where one side sends a message and the other acknowledges that the message has been received. This helps to keep the two sides in step with one another. We have built the code in this lab to use serial data transfer using the MNP (Microcom Networking Protocol) compression and error correcting protocol as it guarantees error-free delivery of data; either it all arrives intact or an error is returned to the sender. For clarity all messages from the desktop machine to the Newton are capitalized, while all messages in the other direction begin with a capital letter and are lower case after that.

The starting version of the code has the CDIL calls removed but all of the protocol and interface code intact. It is recommended you become familiar with the code by downloading the relevant version, making sure you can compile it, and look through the source. The places where you will be filling in code are marked with a comment which begins with three stars ('***'). Of course if you don't want to try writing CDIL code yourself you may still want to look through the Archive Lab Solution code for Macintosh or Windows.

Trying the Solution

Before doing this lab you may want to run the solution code so you get an idea of what the CDILArchive application should look like when you are done with the lab.

Before Starting...
Make sure you have the right kind of cable and know where to plug it into your desktop machine. On a Macintosh to Newton connection you want a "null modem" cable which has circular-8 (mini-DIN 8) connectors on both ends and you may use either the modem or the printer port (make sure the printer port is not being used for AppleTalk). On DOS machines you will want a modem cable again but it may either be a DB-9 connector on the PC side or it may be a DB-25 connector depending on your manufacturer and the vintage of your machine and plugs into a serial port. The Newton side needs to be a circular-8 connector to plug. In both cases the key is that the transmit pin on one side plugs into the receive pin on the other and vice versa (null modem).

On the Desktop Machine
With the Newton connected to your desktop machine, start the compiled CDILArchive program (CWDILArchive or CDILArchiveMPW on the Macintosh, DILARCHI.EXE on Windows).

Windows OS Note - the DLL files must be accessible

If everything is working, the application should start with no errors and the TestScripts and Port menus should appear in your menubar. Make sure the correct port is selected (i.e., the one you've got the cable plugged into) in the Port menu and, if you are running on the Macintosh, that you have selected Modem tool from the list of possible connection types.

To Create an Archive
Start the Newton and install the program CustomRoute (ADD URL) and the transport ArchiveTransport (ADD URL) using Newton Installer (ADD URL) or whatever other program you use for downloading Newton software.

Once they are installed, start the program CustomRoute and enter any text you want (or leave the text that's there) as long as it is 255 characters or less. Next, tapping the action (envelope) icon, select ArchiveTransport from the pop-up list and then wait for the routing envelope to appear. Now, return to the desktop machine and select Archive from the TestScripts menu. Now return to the Newton, tap on the Archive button below the envelope and select Now from the pop-up.

This should cause a status slip to appear on the Newton and, if everything is working, it should cycle quickly from Connecting to Connected, waiting for response at which point a dialog should appear on the desktop machine asking for a name for the about-to-be-created archive. Once you supply a name and directory the Newton should send the data and the status dialog should cycle to Archiving followed by Confirming and finally Disconnecting before the archiving completes and the status slip disappears.

You should now have a text file on the desktop machine which will have in it a "label" string of "ARKS" followed by a length string (which tells how long the data string is) followed by the data string which was sent from the Newton.

To Dearchive the Data
Assuming you are still running the archive program on the desktop machine and that the ArchiveTransport has been installed on the Newton, close Custom Route (if it is still open) and open the In Box from the Extras drawer. Tap the Receive button at the bottom of the In Box and select ArchiveTransport from the pop-up list which appears.

The same status slip should appear on the Newton with the message Connecting in it. Now go to the desktop machine and select Archive from the TestScripts menu. This should complete the connection and cause the Newton status slip to go through the same cycle described in the section on Creating an archive, pausing (save that the message Archiving is replaced by Dearchiving) only for you to select the archive on the desktop machine you wish to download.

After the archive has been sent to the Newton, you will get a new entry (or entries if your archive had more than one string in it) in the In Box which you may open and look at if you so choose.

Archiving Multiple Items
To archive multiple strings, go through the same steps as you did in creating an archive except that in Custom Route instead of selecting Now from the Archive-button pop-up, select Later. This causes the data to be put into an entry in the Out Box. Repeat this for as many strings as you wish to send.

Once you have created several messages to be sent, close CustomRoute, open the In Box and select the items you wish to send by tapping the checkbox to the left of the desired messaged. Next tap on the Send button and select ArchiveTransport from the pop-up list which appears. From here on the steps are the same as described above when you tapped Now from the Archive button.

Dearchiving multiple strings is the same as a single string except that you will have multiple items in the In Box, one for each string archived.

Initializing and Disposing

Before the CDIL call can be used, the CDIL must be initialized, and a CDIL pipe object created and initialized. The code to open the CDIL and to create a CDIL pipe should go in the main routine in the file DILArchive.c. This is marked with the following comments:

// *** YOUR CODE TO OPEN THE CDIL LIBRARY GOES HERE

and:

// *** YOUR CODE TO CREATE THE CDIL OBJECT GOES HERE

The code to initialize the CDIL pipe goes in the routine InitializePipe in the same file. Note that in most cases error checking code follows immediately after the code you write.

Windows OS Note - additional call

The location of your code in InitializePipe is marked with the following comment:

// ***YOUR CODE TO INIT DEVICE GOES HERE

The code for initializing the pipe will be different depending on the desktop platform you are using. On the Macintosh the Communications Toolbox (REFERENCE TO ONLINE DOCS?) is used as the underlying interface to the hardware so there will be a different call with different arguments based on the four kinds of tool supported by the CDIL. For example, the ADSP tool is used when connecting via AppleTalk and so a name must be provided as an argument in order to bind the node. On the other hand for Windows programmers the code to initialize the pipe will include specifics for the driver used. This driver-specific information can be found in DOS documentation (REFERENCE???).

If you are lost as to what routines to use and how to call them, you may want to review part or all of the article CDIL Detailed.

Windows OS Note - serial MNP only

Once you have created and opened a pipe the next natural step would be to add code to connect to the Newton and then go on to reading and writing. However, we suggest adding the code to dispose of the pipe and close the CDIL next as you may then test the code you have written without leaving the CDIL pipe, or the hardware associated with it, in a "half-open" state when you quit the lab application.

To do this scroll further on down into the main routine and you will find the following marker:

// *** YOUR CODE TO DISPOSE OF THE CDIL OBJECT AND CLOSE CDIL LIBRARY GOES HERE

Add code to dispose of the CDIL pipe and close the library. Again, if you are lost, refer to the CDIL Detailed article.

Now you may reasonably test what you have written (though not a lot will happen). Compile and run the lab application. Since we don't actually make a connection at this point, whether you are cabled in to anything or not doesn't matter. Once it is running, if you received not error reports you have opened the CDIL and created the pipe successfully. Next select the Test Connect item from the TestScripts menu. This initializes the pipe testing that code. If you don't get an error message, it has worked successfully and by quitting you will test the code which disposes of the pipe and closes the CDIL.

Connecting and Disconnecting

Once the pipe is successfully initialized a connection must be established between the Newton and the desktop machine. The code to do this is embodied in two calls: CDPipeListen and CDPipeAccept. This code should be placed in the routine DoConnectPipe in the file Protocol.c at the location marked with the following comment:

// ***YOUR CONNECT CODE GOES HERE!

 Windows OS Note - need cookbook code

Once you have added the code to connect the desktop machine, we will balance it with code to disconnect the pipe as well. Since this code is only a single call which appears only in a few places, we have not encapsulated it in a separate subroutine. The two places you need to add it are in the DILArchive.c file to handle the simple test case of connect/disconnect in the Test menu. On the Macintosh the code belongs in the routine DoMenuItem and in the Windows code it belongs in the WndProc routine. In both cases it is marked with the following comment:

// ***YOUR CODE TO DISCONNECT GOES HERE

In addition, it is necessary to disconnect after archiving or de-archiving data so a call must be added as the last line in both the DoArchive and DoDearchive calls in the file Protocol.c. These locations are marked with the same comment.

Note for both platforms on error checking and disconnecting.

To test your code, connect the desktop machine to the Newton, start the CDIL application and select the correct port and (if necessary) the connection tool from the Port menu. On the Newton you may simply use the archive transport to test the connection by using CustomRoute to send something, or you may download the package ConnectTest. Using the archive transport has the disadvantage that, since your code does not implement the archive protocol, an error entry will appear in the Out Box when the attempt to send text fails. In either case, select the Test Connect item from the Test Scripts menu on the desktop machine and either send a message using Custom Route or launch TestConnect on the Newton. If no error dialogs appear on the desktop machine you will have connected successfully. To test your disconnect code, select the Test Disconnect item from the TestScripts menu. Again, if there are no errors reported, the code works.

Note for both platforms on what connecting means for serial connections.

For further details or a review of specifics you may want to look again at the article CDIL Detailed.



Reading and Writing

As with initializing and connecting the pipe, reading and writing have been encapsulated into separate subroutine calls: ReadFromPipe and WriteToPipe respectively. In both cases a string is passed in and you must make the appropriate CDIL call to read or write the data from/to the pipe to/from the string.

These subroutines have the following prototypes:

CommErr ReadFromPipe ( char *response, long *length,
long swapping );
CommErr WriteToPipe ( char *message, long *length,
long swapping );

In both cases the first argument is a string. In the case of reading it is where incoming data should be placed. In the case of writing it is the outgoing message which is always a null-terminated C string (careful readers will remember that outgoing strings will have an EOT character at the end of it, this will have been added before WriteToPipe is called). The second argument is the length of the string received (for ReadFromPipe) or the length of the string being written (for WriteToPipe). In the case of ReadFromPipe this is necessary to make sure we know how long the string which was read in is since it will not necessarily be null terminated. (Note that both of these strings have a maximum data length of 255 characters.)

The last argument describes whether the data should be swapped (if appropriate). This is necessary because our protocol sends a short integer "length" value from the Newton to the desktop machine before sending the data and because of the "big endian versus little endian" problem of byte order for different processors, we need to know whether the particular call needs to take this into account.

Note on solution version of ReadFromPipe

You may want to review the section on reading and writing in the CDIL Detailed article before trying this code.

To test the code, you should now be able to make a complete run of the archiving program as described in the overview section where you ran the solution. At the end of this you should then have uploaded a message from the Newton to the desktop machine and then restored it back to the Newton.

Status

The routine UpdateStatus is used to periodically update the status of the CDIL pipe as well as where we are within the archiving protocol. In UpdateStatus there are two places where you should add code to get or check the status for updating in the status dialog.

The first has the following comment:

// ***YOUR CODE TO UPDATE STATUS GOES HERE

You should replace this line with the code to get the current status of the CDIL pipe and assign it to the local variable cur_state.

The next line looks like this:

/* if ( ***YOUR CODE TO TEST IF PIPE IS DISCONNECTED )

This line begins a block of code which is commented out. Replace the line with a test to see whether the pipe is connected and remove the comment so that the block is once again part of the code.

Note on ourPipe value.

To test your code, run through the process of archiving and dearchiving and watch for the change of state in the status dialog.

As usual, if you are unsure about how to manage these calls, refer to the article CDIL Detailed.

Other Things To Try...

This lab by no means exhausts the capabilities of the CDIL. In particular you may want to try some of the following:

1. Change the status dialog to show additional information about the pipe such as connection speed, parity, etc. for serial connections or NBP name for AppleTalk.

2. Rebuild CDILArchive to use asynchronous calls. In fact, the entire thing could be rewritten as a state machine whose state is periodically updated when various messages are received or sent by use of asynchronous calls. This approach to building an asynchronous state machine is described in the section on Connecting in the CDIL Detailed article.

Remember to call CDIdle.

3. Add encryption and decryption to reading and writing data. Since you may not want to get too fancy about rewriting the Newton code, our recommendation is to do something simple like reverse the data strings (e.g., "foobar" gets archived as "raboof") and then re-reversed before sending it back to the Newton when it is dearchived. Note that in this case encrypting and decrypting would be used in a "backward" fashion (i.e., you would use the decrypting hooks to reverse incoming data and the encryption hooks to re-reverse outgoing data). Note also that encrypting and decrypting would have to be turned on and off depending on whether you were sending data or command strings. More information about encrypting and decrypting data may be found in the Options section of the CDIL Detailed article.

Where To Go From Here...

This lab lies at the end of the section on CDILs within the section of DILs in the online course: Newton Programming: 2.0 Communications. See the course road map to navigate among the different topics pictured.

More directly:
If you wish more general information about the DILs, see the article DIL Overview.

If you want more details on CDILs, see the article CDIL Detailed.

If you want to get the solution code for this lab, go to CDIL Archive Code.

If you want to look at FDIL details, see the article FDIL Detailed and if you want to look at the follow-on lab which implements the transfer of Newton frames, see the lab FDIL Archive Lab.

Finally, if you would like an overview of this class, see the NPG: 2.0 Communications Overview Module.


Notes

Windows users must make sure that the CDIL_DLL files are installed where the DILARCHI.EXE program can find them. The likeliest places for them are either in the Windows system directory or in the same directory you have copied DILARCHI.EXE into.



Windows programmers may recall that they have an added call which must be made to coordinates the application with the driver timers, CDSetApplication. Details of this call may be found in the section on initializing in the article CDIL Detailed.



Currently the only kind of connection supported on the Windows OS using the CDIL is a serial MNP connection. Of course this may change in the future



Windows programmers should remember that they have more work to do on connecting than Macintosh programmers do as they must wait for the listen call to transition from kCDIL_Listening to kCDIL_ConnectPending before accepting the connection. However, the "cookbook code" available in the CDIL Detailed article in the section on connecting should make it fairly easy.



We have hidden a call to CDPipeDisconnect in the macro CHECKDILERROR which is in the header file Protocol.h. This macro is designed to check DIL calls for error returns whenever called and, if there is an error, return it from the currently executing routine (usually DoArchive or DoDearchive) after first making sure the pipe is disconnected.



Note that with serial or serial MNP connections, a device is considered connected as soon as the hardware senses that there is appropriate hardware on the other side to connect to. There is no need to actually exchange data to establish a connection. Do not be fooled into thinking that because such hardware was detected that all is well and data can be exchanged! There may be more problems lurking when we begin to send and receive data.



In the solution code ReadFromPipe has a very short timeout value and then loops looking for input. This allows it to keep updating status information and, if desired to keep responding to user input. Otherwise there is a very real tendency for the application to appear to "freeze" during reads while waiting for incoming data.



Note that the global ourPipe is set to 0 when it is not connected (and reset to 0 on disconnect (see above note on CHECKDILERROR)) so that we can use it to protect against trying to get the status of a disconnected pipe.



You must periodically call the routine CDIdle if you are going to make asynchronous CDIL calls as this routine checks the status of ongoing asynchronous calls. For example Macintosh programmers would tend to call it in the main event loop.

Navigation graphic, see text links

Developer Services | Technical Information | Tools | Sample Code

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help

Copyright Apple Computer, Inc.
Maintained online by commscourse@newton.apple.com
Updated 26-Sep-96 by dcd