An instruction can be either:

	*	a frame with a slot toolSymbol, whose value is a symbol which identifies the instruction

	*	an array of instructions, which indicates a sequence of instructions

	*	nil, which is a no-operation instruction

	*	one of the following symbols: 'ok, 'warning, 'error, 'cancelled

		'ok			Indicates that the script has not encountered any problem (yet), so its execution can continue (same as nil).

		'warning	Indicates that a minor error has occured. the currently executing instruction sequence is aborted and the execution resumes at the first enclosing "Try" instruction with a "warning" option (see the "Try" instruction).

		'error	Indicates that a critical error has occured. the currently executing instruction sequence is aborted and the execution resumes at the first enclosing "Try" instruction with an "error" option (see the "Try" instruction).

		'cancelled	Indicates that the script execution has been cancelled. the currently executing instruction sequence is aborted and the execution resumes at the first enclosing "Try" instruction with an "cancelled" option (see the "Try" instruction).

	*	a function with no argument which returns an instruction





When an instruction frame executes, all the slots contained in the frame are used as parameters for the instruction. Each of the slot defined in the frame of global variables is also used as a parameter (unless a slot with the same name is already defined in the instruction frame).

When the instruction frame execution ends, all the slots defined in the frame of global variables are set to their new value.



An instruction frame can optionaly contain a special slot named "globalSymbols". This slot must be a frame of slots whose values are symbols. Each of these slots corresponds to a parameter for the instruction. The name of the parameter is the slot name; the value of the parameter is the global variable whose name is the slot value.

If the slot "globalSymbols" is defined, only the global variables whose name are in the "globalSymbols" frame are used as parameters for the instruction. The other global variables are not used as parameters. So, if an instruction contains a "globalSymbols" slot, it must contains all the global variables used by that instruction.

For an example of using global variables, consider the following script:

	globals: {

			connectionTool: nil,	// Set by the ConnectSerial instruction

			endpoint: nil,			// Set by the ConnectSerial instruction

			transport: nil,			// Set by EETransfer at the script startup

		},

	instruction: [

			{

				toolSymbol: 'ConnectSerial,

				bps: k9600bps,

				globalSymbols: {

						endpoint: 'endpoint,

						machine: 'connectionTool,

						transport: 'transport,

					},

			},

			...

			{

				toolSymbol: 'Resume,

				globalSymbols: {

						machine: 'connectionTool,

					},

			},

		]

The first instruction frame tells the transport defined in the global variable "transport" (ie EETransfer) to launch a serial connection at 9600 bps. When the Newton is connected, the instruction pauses, and the value of the "machine" slot (which contains the state of the instruction) is copied into the global variable "connectionTool". In the same way, the value of the "endpoint" slot (which contains the endpoint created for the connection) is copied into the global variable "endpoint".

The last instruction frame executes the "Resume" instruction with a single parameter. This parameter is named "machine" and its value is the value of the global variable "connectionTool". So this instruction resumes the previously paused "ConnectSerial" instruction, which has the effect of closing the serial connection.

Note: When a script execution ends, all the paused instructions are automatically resumed. So the following example is better way to do the same thing as the previous script.

	globals: {

			endpoint: nil,			// Set by the ConnectSerial instruction

			transport: nil,			// Set by EETransfer at the script startup

		},

	instruction: [

			{

				toolSymbol: 'ConnectSerial,

				bps: k9600bps,

			},

			...

		]





*********************************************************************************

ConnectAppleTalk

*********************************************************************************





Launch an AppleTalk connection, then pause as soon as the Newton is connected. When its execution is resumed, it disconnects.



For more information about the following options, read the Newton AppleTalk documentation.





* attentionBufferSize



type: integer

default value: 0





* endpoint



type: Newton endpoint



This slot is returned by the instruction. Its initial value is ignored





* listen



type: boolean

default value: nil





* listenTimeout



type: integer

default value: kNoTimeout (0)



An integer specifying the time, in milliseconds, that the system should allow for the Newton to listen. If you use this slot, specify an integer greater than 30.





* nbpAddress



type: string or nil

default value: nil





* nbpName



type: string or nil

default value: nil





* nbpType



type: string or nil

default value: nil





* nbpZone



type: string or nil

default value: "*"



Note: nil is the same as "*".





* receiveBufferSize



type: integer

default value: 511,





* sendBufferSize



type: integer

default value: 511,





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

ConnectIrDA

*********************************************************************************





Launch an IrDA connection, then pause as soon as the Newton is connected. When its execution is resumed, it disconnects.



For more information about the following options, read the Newton IrDA documentation.





* bps



type: integer

default value: k115200bps (115200)





* disconnectTimeout



type: integer

possible values: 3, 8, 12, 16, 20, 25, 30 and 40

default value: 40





* endpoint



type: Newton endpoint



This slot is returned by the instruction. Its initial value is ignored





* listen



type: boolean

default value: nil





* listenTimeout



type: integer

default value: kNoTimeout (0)



An integer specifying the time, in milliseconds, that the system should allow for the Newton to listen. If you use this slot, specify an integer greater than 30.





* myLSAPId



type: integer

possible values: between 0 and 31 (included)

default value: 0





* myName



type: string

default value: "X"





* peerLSAPId



type: integer

possible values: between 0 and 31 (included)

default value: 0,





* peerName



type: string

default value: "X"





* receiveBuffersCount



type: integer

possible values: between 1 and 7 (included)

default value: 1,





* receiveBufferSize



type: integer

possible values: 64, 128, 256, 512, 1024 and 2048

default value: 512,





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

ConnectModem

*********************************************************************************





Launch a modem connection, then pause as soon as the Newton is connected. When its execution is resumed, it disconnects.





* endpoint



type: Newton endpoint



This slot is returned by the instruction. Its initial value is ignored





* errorControl



type: integer

default value: kModemECProtocolNone + kModemECProtocolExternal



The possible values for the slot are listed below. Note that these values can be combined together to specify multiple error control types.



Constant					Value		Description	

kModemECProtocolNone		0x00000001	No error control.	

kModemECProtocolMNP			0x00000002	Use internal MNP class 4.	

kModemECProtocolExternal	0x00000008	Use modemUs built-in error control.	

kModemECInternalOnly		0x00000010	Connect with internal error control only; overrides other settings.



What happens when a reliable connection cannot be established depends on which error control types you specify. If you include kModemECProtocolNone in your specification, then the modem tool Rfalls backS to a connection with no error control. If you do not include kModemECProtocolNone in your specification and a reliable connection cannot be established, the connection fails.

If you specify kModemECInternalOnly, the NewtonUs internal error control is used. This setting takes precedence over the other error control types. 





* listen



type: boolean

default value: nil





* listenTimeout



type: integer

default value: kNoTimeout (0)



An integer specifying the time, in milliseconds, that the system should allow for the Newton to listen. If you use this slot, specify an integer greater than 30.





* phoneNumber



type: string or nil

default value: nil





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

ConnectSerial

*********************************************************************************





Launch a serial connection, then pause as soon as the Newton is connected. When its execution is resumed, it disconnects.





* bps



type: integer

default value: k9600bps (9600)



You can use the following constants to specify the connection speed:

Constant		Value	

kExternalClock	1	

k300bps			300	

k600bps			600	

k1200bps		1200	

k2400bps		2400	

k4800bps		4800	

k7200bps		7200	

k9600bps		9600

k12000bps		12000	

k14400bps		14400	

k19200bps		19200	

k38400bps		38400	

k57600bps		57600	

k115200bps		115200	

k230400bps		230400





* dataBits



type: integer

default value: k8DataBits (8)



You can use the following constants:

Constant	Value (number of data bits)	

k5DataBits	5	

k6DataBits	6	

k7DataBits	7	

k8DataBits	8





* endpoint



type: Newton endpoint



This slot is returned by the instruction. Its initial value is ignored





* flowControl



type: symbol or nil

default value: nil



You can use the following values:

Value	Description

nil		no flow control

'hard	Hardware Handshake (DTR & CTS)

'soft	Software Handshake (XON/XOFF)





* listen



type: boolean

default value: nil





* listenTimeout



type: integer

default value: kNoTimeout (0)



An integer specifying the time, in milliseconds, that the system should allow for the Newton to listen. If you use this slot, specify an integer greater than 30.





* parity



type: integer

default value: kNoParity (0)



You can use the following constants:

Constant	Value	Description	

kNoParity	0		no parity

kOddParity	1		odd parity	

kEvenParity	2		even parity	





* receiveBufferSize



type: integer

default value: 1040 (a little more than 1 KB)



This slot lets you increase the size of the input buffer used by the serial tool. Buffers larger than 4KB are not supported; an error results if you specify too large a buffer. Also note you can get an out-of-memory error at connect time if the serial tool cannot allocate the buffer.

This option is often useful because appropriate buffer size can increase performance and decrease overrun errors. For communications that use packet-oriented protocols, a good buffer size is one that is a few bytes larger than the typical packet size.

The input buffer can be increased, especially for data rates above 9600 bps. If no flow control is operating, input buffer size may be the only way to control overruns.

The total size of the input buffer is limited to 4 KB, which includes about 8 bytes per marker. Typical input buffer size is 256 to 1024 bytes.

Note that the usable size of a buffer is usually between one and four bytes less than the buffer size, because of DMA boundary constraints and other considerations.





* serialPort



type: string

default value: kHWLocExternalSerial ("extr")



The possible values for the slot are listed below. Note that these locations are hardware platform dependent.

Constant				Value	Description	

kHWLocExternalSerial	"extr"	Use the external serial port.

kHWLocBuiltInIR			"infr"	Use the built-in infrared port.

kHWLocBuiltInModem		"mdem"	Use the built-in modem.

kHWLocPCMCIASlot1		"slt1"	Use the application card in slot 1.

kHWLocPCMCIASlot2		"slt2"	Use the application card in slot 2.

kHWLocPCMCIAAnySlot		"slot"	Use the application card in any slot.





* stopBits



type: integer

default value: k1StopBits (0)



You can use the following constants:

Constant		Value	Number of stop bits	

k1StopBits		0		1 stop bit

k1pt5StopBits	1		1.5 stop bits

k2StopBits		2		2 stop bits





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

For

*********************************************************************************





Execute the "Init" function, then while the "Test" function returns true, execute both the "instruction" instruction and the "Next" function.

Using the C syntax, it could be written:

	for (Init(); Test(); Next()) {

		instruction;

	}





* Init



type: function

default value: empty function





* instruction



type: instruction

default value: nil





* Next



type: function

default value: empty function





* Test



type: boolean function

default value: func() true





*********************************************************************************

ForEachItemRequest

*********************************************************************************





For each item selected in the OutBox, execute the "instruction" instruction .





* clientAppSymbol



type: symbol

default value: nil



Use clientAppSymbol if you want to ignore all the OutBox items whose appSymbol slot is set to a value different form clientAppSymbol.

It's useful when you want that your script ignore all the files not generated by your application (for example, those generated by EESnapshot).





* instruction



type: instruction

default value: nil





* ioBoxItem



type: ioBox item

default value: nil



ioBoxItem is set by the ForEachItemRequest tool each time it executes the instruction.

Note: if you want to use its value, you must declare ioBoxItem as a global variable.





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

ForEachReadyItem

*********************************************************************************





For each item which is ready to send in the OutBox, execute the "instruction" instruction.





* clientAppSymbol



type: symbol

default value: nil



Use clientAppSymbol if you want to ignore all the OutBox items whose appSymbol slot is set to a value different form clientAppSymbol.

It's useful when you want that your script ignore all the files not generated by your application (for example, those generated by EESnapshot).





* instruction



type: instruction

default value: nil





* ioBoxItem



type: ioBox item

default value: nil



ioBoxItem is set by the ForEachItemRequest tool each time it executes the instruction. 

Note: if you want to use its value, you must declare ioBoxItem as a global variable.





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

ForEachRemoteItem

*********************************************************************************





For each item which is remote (ie not completely received) in the InBox, execute the "instruction" instruction.





* clientAppSymbol



type: symbol

default value: nil



Use clientAppSymbol if you want to ignore all the OutBox items whose appSymbol slot is set to a value different form clientAppSymbol.

It's useful when you want that your script ignore all the files not generated by your application (for example, those generated by EESnapshot).





* instruction



type: instruction

default value: nil





* ioBoxItem



type: ioBox item

default value: nil



ioBoxItem is set by the ForEachRemoteItem tool each time it executes the instruction. 

Note: if you want to use its value, you must declare ioBoxItem as a global variable.





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

ReceiveRaw

*********************************************************************************





Receive a file using no protocol.





* blockSize



type: integer

default value: 1024



Do not modify this option unless your typical file size is less than "blockSize". See the "stopTimeout" for more information.





* charset



type: symbol

possible values: defined in the file "EERecodeConstants.f"

default value: kMacOSCharset ('mac)



Defines which characters set is used for the file.

This information is used to convert or show the file.





* clientAppSymbol



type: symbol

default value: nil



AppSymbol of the application which intends to use this file.

If clientAppSymbol equals nil, the appSymbol of the application currently running the script will be used, so you will seldom have to override clientAppSymbol default value.

Note: if a file conversion occurs (see the "fileName" option), the clientAppSymbol slot may be ignored by EETransfer.





* convertTextFiles



type: boolean

default value: nil



If the file name ends with ".txt", and "convertTextFiles" is set to true, the file is considered as a text file and is converted into a Newton text object.

Otherwise, the file is not converted.





* fileName



type: string or nil

default value: nil



If the file name ends with ".pkg", the file is considered as a package.

If the file name ends with ".pct", the file is considered as Macintosh PICT file and is converted into a Newton picture.

If the file name ends with ".nso", the file is considered as a NewtonScript Object file and is converted into a Newton object.

Otherwise, the file is considered as a text file and is not converted.





* startTimeout



type: integer

default value: 60000



An integer specifying the time, in milliseconds, that the Newton will wait for the first block of data before aborting the reception.





* stopTimeout



type: integer

default value: 5000



An integer specifying the delay, in milliseconds, that the Newton will use to consider that the file reception has ended: if not data have been received for stopTimeout milliseconds, the file will be considered as succesfully received.

Note: If the size of the file is less than the size of a block, "startTimeout" will be used instead "stopTimeout".





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

ReceiveXModem

*********************************************************************************





Receive one or several files using the XModem/YModem protocol.



If the file name of the received file ends with ".pkg", the file is considered as a package.

If the file name ends with ".pct", the file is considered as Macintosh PICT file and is converted into a Newton picture.

If the file name ends with ".nso", the file is considered as a NewtonScript Object file and is converted into a Newton object.

Otherwise, the file is considered as a text file and is not converted.





* charset



type: symbol

possible values: defined in the file "EERecodeConstants.f"

default value: kMacOSCharset ('mac)



Defines which characters set is used for the file and the file name.

This information is used to convert or show the file.





* clientAppSymbol



type: symbol

default value: nil



AppSymbol of the application which intends to use this file.

If clientAppSymbol equals nil, the appSymbol of the application currently running the script will be used, so you will seldom have to override clientAppSymbol default value.

Note: if a file conversion occurs, the clientAppSymbol slot may be ignored by EETransfer.





* convertTextFiles



type: boolean

default value: nil



If the file name ends with ".txt", and "convertTextFiles" is set to true, the file is considered as a text file and is converted into a Newton text object.

Otherwise, the file is not converted.





* noAck



type: boolean

default value: nil



Don't acknowledge received blocks.

This option corresponds to the YMODEM-g protocol.

If an error is detected in a YMODEM-g transfer, the transfer aborts.

Note: The ZMODEM protocol should be used in applications that require both streaming throughput and error recovery.





* useCrc16



type: boolean

default value: nil



Use a Cyclic Redundancy Check coded on 16 bits instead of a checksum to verify if a block has been modified during transfer.

A CRC16 is safest than a checksum.

This option corresponds to the XMODEM/CRC protocol.





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

ReceiveZModem

*********************************************************************************





Receive one or several files using the ZModem protocol.



If the file name of the received file ends with ".pkg", the file is considered as a package.

If the file name ends with ".pct", the file is considered as Macintosh PICT file and is converted into a Newton picture.

If the file name ends with ".nso", the file is considered as a NewtonScript Object file and is converted into a Newton object.

Otherwise, the file is considered as a text file and is not converted.





* allowCommands



type: boolean

default value: true



Allows the sender to send any NewtonScript commands which are executed immediately.

This option is a security hole, so it may be disabled.





* charset



type: symbol

possible values: defined in the file "EERecodeConstants.f"

default value: kMacOSCharset ('mac)



Defines which characters set is used for the file and the file name.

This information is used to convert or show the file.





* clientAppSymbol



type: symbol

default value: nil



AppSymbol of the application which intends to use this file.

If clientAppSymbol equals nil, the appSymbol of the application currently running the script will be used, so you will seldom have to override clientAppSymbol default value.

Note: if a file conversion occurs, the clientAppSymbol slot may be ignored by EETransfer.





* convertTextFiles



type: boolean

default value: nil



If the file name ends with ".txt", and "convertTextFiles" is set to true, the file is considered as a text file and is converted into a Newton text object.

Otherwise, the file is not converted.





* encodeControlChars



type: boolean

default value: nil



Encode control characters used by the ZModem protocol to allow operation with some packet switched networks.





* szString



type: string or nil

default value: nil



Use this option if you want to send a command to the sender before starting to receive.

This option is useful if the Newton is connected to a Unix or DOS server or a BBS.

For example, if szString is set to "sz readme.txt\n", the Newton will command the Unix server to send the file "readme.txt".





* sendFirstZrinit



type: boolean

default value: true



This option is a patch which needs only to be used when receiving files from a UNIX server which uses the lsz command.

Sometimes these systems will trash (core dump) when they receive the first ZRINIT packet. If this occurs just set this option to nil.





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





* waitForOO



type: boolean

default value: true



Some versions of HyperTerminal, a Windows 95 program, seem to have a bug which prevents them to send correctly the "OO" (Over and Out) sequence when the "ReceiveZModem" has endend. So, if you are transfering from HyperTerminal, set this option to nil, otherwise the "ReceiveZModem" will wait a few seconds for the "OO" sequence and then generate a warning.





* wantToUseCrc32



type: boolean

default value: true



If this option is set, the sender will be asked to use a CRC32 instead of a CRC16.

A CRC32 is safest but takes a little more time to calculate.





*********************************************************************************

Resume

*********************************************************************************





Resume the execution of a paused instruction (typically, a ConnectXXX instruction).





* machine



type: not documented

default value: nil



"machine" is the state of the paused instruction to resume.

Note: Every instruction save its state in a slot "machine" when it stops or pauses.





*********************************************************************************

SendATEscape

*********************************************************************************





Send an AT escape sequence to the modem.

An AT escape is a +++ sequence preceded and followed by a delay.





* delay



type: integer

default value: 60 (1 second)



Delay (in ticks) preceding and following the +++ sequence.

Note: 1 tick = 1/60 second.





*********************************************************************************

SendRaw

*********************************************************************************





Send a file using no protocol.



Example of Script that sends all OutBox files that are ready:

	globals: {

			endpoint: nil,			// Set by the ConnectXXX instruction

			ioBoxItem: nil,			// Set by the ForEachReadyItem instruction

			transport: nil,			// Set by EETransfer at the script startup

			...

		},

	instruction: [

			...

			{

				toolSymbol: 'ForEachReadyItem,

				instruction: {

						toolSymbol: 'SendRaw,

					},

			},

			...

		]



Example of Script that sends all OutBox files that are selected:

	globals: {

			endpoint: nil,			// Set by the ConnectXXX instruction

			ioBoxItem: nil,			// Set by the ForEachItemRequest instruction

			transport: nil,			// Set by EETransfer at the script startup

			...

		},

	instruction: [

			...

			{

				toolSymbol: 'ForEachItemRequest,

				instruction: {

						toolSymbol: 'SendRaw,

					},

			},

			...

		]





* charset



type: symbol

possible values: defined in the file "EERecodeConstants.f"

default value: kMacOSCharset ('mac)



Defines which characters set is used for the file and the file name.

This information is used to convert the file.





* ioBoxItem



type: ioBox item

default value: nil



OutBox item to send.





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

SendString

*********************************************************************************





Send a string to the remote computer.





* charset



type: symbol

possible values: defined in the file "EERecodeConstants.f"

default value: kMacOSCharset ('mac)



Characters set used to convert the string.





* isSecret



type: boolean

default value: nil



If this option is set to true, the content of the string won't be shown to the user: each character will be replaced by a bullet character.

Useful for passwords.





* string



type: string

default value: nil



String to send.





*********************************************************************************

SendXModem

*********************************************************************************





Send one or several files using the XModem/YModem protocol.





* batch



type: boolean

default value: nil



If this option is set and "ioBoxItem" equals nil then the instruction will attempt to send all OutBox files that are selected.

This option corresponds to the YMODEM protocol.





* charset



type: symbol

possible values: defined in the file "EERecodeConstants.f"

default value: kMacOSCharset ('mac)



Defines which characters set is used for the file and the file name.

This information is used to convert the file.





* ioBoxItem



type: ioBox item or nil

default value: nil



OutBox item to send.

If "ioBoxItem" equals nil, "batch" must be set to true.





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





* use1KBlocks



type: boolean

default value: nil



Try to use blocks that have a size of 1K instead of 128 bytes.

This option corresponds to the XMODEM-1k protocol, which is much faster than the standard XMODEM protocol.





*********************************************************************************

SendZModem

*********************************************************************************





Send one or several files using the ZModem protocol.





* batch



type: boolean

default value: nil



If this option is set then the instruction will attempt to send all OutBox files that are selected.

This option should not be set if either "command" or "ioBoxItem" is not nil.



* charset



type: symbol

possible values: defined in the file "EERecodeConstants.f"

default value: kMacOSCharset ('mac)



Defines which characters set is used for the file and the file name.

This information is used to convert the file.





* command



type: string or nil

default value: nil



If this option is set to a string, the instruction will send this string and execute it on the remote computer.

The syntax of the command depends of the remote computer.

This option is mostly used when the remote computer is a Unix system.

Example of Unix command: "!ls".

This option should not be set if either "batch" or "ioBoxItem" is not nil.





* encodeControlChars



type: boolean

default value: nil



Encode control characters used by the ZModem protocol to allow operation with some packet switched networks.





* enableFullStreamingWithSamplingSend



type: boolean

default value: true





If this option is set to true, the Newton won't wait for an acknowledge after each block.

If you clear this option the file transfer is slower. So, you should clear it only when the connection is established without flow control and the remote computer is very slow.





* fileConversion



type: integer

possible values: defined in the file "EETransferConstants.f"

default value: kFileConversion_ZCRESUM (3)



kFileConversion_NONE (0)

	No file conversion.



kFileConversion_ZCBIN (1)

	"Binary" transfer - inhibit conversion unconditionally.



kFileConversion_ZCNL (2)

	Convert received end of line to local end of line convention. The supported end of line conventions are CR/LF (most ASCII based operating systems except Unix and Macintosh), and NL (Unix). Either of these two end of line conventions meet the permissible ASCII definitions for Carriage Return and Line Feed/New Line. Neither the ASCII code nor ZMODEM ZCNL encompass lines separated only by carriage returns. Other processing appropriate to ASCII text files and the local operating system may also be applied by the receiver (Filtering RUBOUT, NULL, Ctrl-Z, etc).



kFileConversion_ZCRECOV or kFileConversion_ZCRESUM (3)

	Recover/Resume interrupted file transfer. ZCREVOV is also useful for updating a remote copy of a file that grows without resending of old data. If the destination file exists and is no longer than the source, append to the destination file and start transfer at the offset corresponding to the receiver's end of file. This option does not apply if the source file is shorter. Files that have been converted (e.g., ZCNL) or subject to a single ended Transport Option cannot have their transfers recovered.





* fileManagement



type: integer

possible values: defined in the file "EETransferConstants.f"

default value: kFileManagement_NONE (0)



kFileManagement_NONE (0)

	No file management.



kFileManagement_ZMSKNOLOC (0x80);

	Instructs the receiver to bypass the current file if the receiver does not have a file with the same name. NB: this option can be ored with any of the following constants.



kFileManagement_ZMNEWL (1)

	Transfer file if destination file absent. Otherwise, transfer file overwriting destination if the source file is newer or longer.



kFileManagement_ZMCRC (2)

	Compare the source and destination files. Transfer if file lengths or file polynomials differ.



kFileManagement_ZMAPND (3)

	Append source file contents to the end of the existing destination file (if any).



kFileManagement_ZMCLOB (4)

	Replace existing destination file (if any).



kFileManagement_ZMNEW (5)

	Transfer file if destination file absent. Otherwise, transfer file overwriting destination if the source file is newer.



kFileManagement_ZMDIFF (6)

	Transfer file if destination file absent. Otherwise, transfer file overwriting destination if files have different lengths or dates.



kFileManagement_ZMPROT (7)

	Protect destination file by transferring file only if the destination file is absent.





* hyperTerminalPatch



type: boolean

default value: true



HyperTerminal, a Windows 95 program, has a bug which prevents it to automatically close its reception window when the file transfer has ended.

When this option is set to true, the Newton uses a workaround to circumvent this bug.

This patch adds an overhead of only 1 second, so it is set by default. 





* ioBoxItem



type: ioBox item or nil

default value: nil



OutBox item to send.

This option should not be set if either "batch" or "command" is not nil.





* rzString



type: string or nil

default value: "rz\n"



Use this option if you want to send a command to the sender before starting to send.

This option is useful if the Newton is connected to a Unix or DOS server or a BBS.





* transport



type: frame

default value: nil



The transport must always be EETransfer.

Note: Before the script executes itself, the global variable "transport" is automatically set to EETransfer. So if you don't use a slot "globalSymbols" you don't have to (and you should not) provide a slot "transport". Otherwise, the

"globalSymbols" slot must contain a slot:

	transport: 'transport,





*********************************************************************************

Try

*********************************************************************************





Try to execute the "instruction" instruction.



- If it returns 'ok then execute the "ok" instruction, or if there is no "ok" instruction skip to the next instruction after the "try" instruction.



- If it returns 'warning then execute the "warning" instruction, or if there is no "warning" instruction propagate the 'warning to the first enclosing "try" instruction.



- If it returns 'error then execute the "error" instruction, or if there is no "error" instruction propagate the 'error to the first enclosing "try" instruction.



- If it returns 'cancelled then execute the "cancelled" instruction, or if there is no "cancelled" instruction propagate the 'cancelled to the first enclosing "try" instruction.



Note: Since "try" is a reserved NewtonScript keyword, it should be enclosed between "|".



Example of script fragment that sends an AT escape sequence (+++) to a modem, waits one seconds for an OK answer, and continues execution even if it doesn't receive the OK:

	{

		toolSymbol: 'SendATEscape,

	},

	{

		toolSymbol: '|Try|,

		instruction: {

				toolSymbol: 'WaitForString,

				string: "OK" & unicodeCR & unicodeLF,

				timeout: 1000,

			},

		warning: 'ok,

	},

	// The following instructions will be executed even if a timeout has

	// occured, because the timeout generates a 'warning which is handled

	// by the "try" instruction and converted to a 'ok. 

	...





* cancelled



type: instruction

default value: nil





* error



type: instruction

default value: nil





* instruction



type: instruction

default value: nil





* warning



type: instruction

default value: nil





*********************************************************************************

WaitForLine

*********************************************************************************





Wait until the remote computer sends a line.





* charset



type: symbol

possible values: defined in the file "EERecodeConstants.f"

default value: kMacOSCharset ('mac)



Characters set used to convert the received line.





* line



type: string



If the wait for line succeeds this option will contain the received line.

Note: this line will include the lineSeparator.





* lineSeparator



type: string

default value: "\n" (CR)



String that will be used by the instruction to find the end of the line.

The most common end of line are CR, LF or CR+LF.





* timeout



type: integer or nil

default value: nil (no timeout)



Time, in milliseconds, to wait for the line before aborting and returning a 'warning.

A value of 0 or nil, indicates no timeout.





*********************************************************************************

WaitForString

*********************************************************************************





Wait until a string is received from the remote computer.





* charset



type: symbol

possible values: defined in the file "EERecodeConstants.f"

default value: kMacOSCharset ('mac)



Characters set used to convert the string.





* string



type: string

default value: nil



String to wait for.





* timeout



type: integer or nil

default value: nil (no timeout)



Time, in milliseconds, to wait for the string before aborting and returning a 'warning.

A value of 0 or nil, indicates no timeout.