Serial/Modem Scripting Addition


ICONThe Serial/Modem scripting addition was designed to compliment Black Night (a highly scriptable communications application by Raine Storm Softworks), but it can also be used in its own right or in conjunction with other communications products. It offers the following commands:

These commands present a sensible and practical solution to some common scripting problems. I've also put together a number of sample scripts:

Please feel free to use these scripts as you wish. Also, I plan to extend this suite so feel free to drop me a line with your suggestions for additional commands.

sm_list

The sm_list command returns a list of registered serial ports as returned by the Communication Resource Manager. It doesn't require any parameters.

sm_list
Result:  list  --list of registered serial ports

You can use the sm_list command to check that the serial port you're using actually exists on the computer running the script, and it can also be used to establish an array if you want to perform the same operation on all the available serial ports.

sm_choose

The sm_choose command presents a dialog to the user which allows them to select a serial port. It has two optional parameters that allow you to specify the port that should be selected when the dialog is initially presented, and to specify the user prompt. If these parameters are not specified then default values are used.

sm_choose
   [default string]  --initial selection
   [message string]  -- message to display
Result:  string  --selected serial port

You can use the sm_choose command to allow the user to set his or her preference, or to reselect a serial port if the preselected on is not available.

Screen Shot

If you do not specify a default serial port ("default", then the first port will be selected and if you do not specify a message, then the message "Please select a serial port ..." will be displayed

sm_status

The sm_status command returns the current status (e.g. available) of the nominated serial port. It requires a single parameter which is the name serial port to obtain the status of. It returns an enumerated result which is the status of the port.

sm_status
   port string  --the name of the serial port
Result:  available/
         busy/
         appletalk/
         missing/
         broken  --the status of the serial port

The following table explains the possible results:

available

The serial port is not in use by any application or process and is free to be used.

busy

The serial port is registered as 'in use' by an application or process. It may or may not be legitimately in use and it may or may not be able to be force closed.

appletalk

The serial port is in use by the AppleTalk driver and may not be closed or overridden.

missing

There is no such serial port on this computer.

broken

The serial port exists, but there is a problem with it - usually as a result of being used by MIDI software and not being reset properly. You'll probably need to reset your PRAM to regain the use of this port.

You can use the sm_status command to check that the serial port you're about to use is actually available for use. It can also give you a clue as to why the port cannot be used.

sm_force

The sm_force command attempts to 'force close' the nominated serial port. It requires a single parameter which is the name of the serial port to be closed. There is no result so you should check the status of the serial port to see if it actually closed.

sm_force
   port string  --the serial port to close

You can use the sm_force command to close a serial port that may have been errantly left open. Also, a lot of errored communication applications do not know how to override background facsimile software and this command can be used to 'clear' a port prior to use by one of these applications.

Check Serial Port

---
--- present a list of ports and pick one
---
set localPort to sm_choose message "Check which serial port..."
---
--- get the status of the chosen port
---
set localStatus to sm_status port localPort
---
--- now, either the port is available ...
---
if localStatus is equal to available then
	display dialog "The " & localPort & " is available and can be used." buttons {"OK"} default button "OK"
	---
	--- or its busy ...
	---
else if localStatus is equal to busy then
	display dialog "The " & localPort & " is busy and cannot be used." buttons {"OK", "Force Close"} default button "OK"
	---
	--- in which case we can try to close it ...
	---
	if button returned of result = "Force Close" then
		sm_force port localPort
	end if
	---
	--- or its in use by appletalk in which case we shouldn't try and close it !
	---
else if localStatus is equal to appletalk then
	display dialog "The " & localPort & " is in use by AppleTalk and cannot be used." buttons {"OK"} default button "OK"
	---
	--- or there's no such port ...
	---
else if localStatus is equal to missing then
	display dialog "The " & localPort & " doesn't exist and cannot be used." buttons {"OK"} default button "OK"
	---
	--- or the port is really stuffed, probably a PRAM problem after using MIDI software :-(
	---
else if localStatus is equal to broken then
	display dialog "The " & localPort & " is broken and cannot be used." buttons {"OK"} default button "OK"
end if
return

Guaranteed Serial Port

---
--- on startup we'll take the first serial port going
---
property defaultport : ""
 
on run {}
	---
	--- now, get a list of valid ports
	---
	set availports to sm_list
	---
	--- if our one isn't in there then pick one, otherwise skip
	---
	if availports does not contain defaultport then
		set defaultport to sm_choose default defaultport message "Please select a serial port..."
	end if
	---
	--- unless its busy in which case bad luck !
	---
	if (sm_status port defaultport) is not equal to available then
		display dialog "The " & defaultport & " is already in use, please try again later." buttons {"Cancel"}
	end if
end run