Socket.server.connect command changes

[jMarcS]

Under the auspices of Basic issues 1 and 62, I've changed one socket command and added three new ones (but not the one named in the issue title!).

Socket.server.connect (on page 74 in v01.72 manual) has changed.

The command now has an optional "wait" parameter: Socket.server.connect {<wait_nexp>}

The second sentence of the description is no longer complete: It says, "This command will not return until a connection is made with a Client." Now, if the optional numeric parameter evaluates to 0, the command completes immediately. If the parameter has any other value, or does not exist, the command waits until the connection is made. Effectively, the default value of the parameter is 1. Usually the default is a preferred value, but in this case it is chosen for backward compatibility and the preferred value is 0.

Suggested wording, with the format taken from BT.connect:

The optional "wait" parameter determines if the command waits until a connection is made with a Client. If no parameter is given, or if the parameter value is non-zero, the command waits for the connection. If the parameter evaluates to 0, the command completes immediately. Use Socket.server.status to determine when the connection is made.

I'd like to say somewhere that it is "better" to set the parameter to 0 and monitor status. "Better" here means safer, or more robust, since it can avoid a problem if the program exits with no connection made. Would something like that go here, or in the opening section on TCP/IP Sockets -- again, the precedent might be the Bluetooth section.

[mrleavitt]

Before I make any changes, could I query whether the parameter is better expressed as a logical or numeric expression? Whenever I see something that evaluates to either 0 or non-zero I think that maybe it's better thought of as a logical expression. If you agree, I'd add words something like this (yours, but with a few changes):

---

Socket.server.connect {< wait_lexp >}

The optional "wait" parameter determines if the command waits until a connection is made with a client. If the parameter is true (non-zero or missing), the command waits for the connection. If the parameter is false (0), the command completes immediately. Use socket.server.status to determine when the connection is made.

In general, it is better (safer, more robust) to set the parameter to false and explicitly monitor the connection's status, since it can avoid a problem if the program exits with no connection made.

---

Also, with regard to your last commend, I think I'd try to put the comment with the command (as above), as (it seems to me) that that's when someone is more likely to be thinking about it. If we put it in the introductory material, it might be forgotten by the time the coding starts.

What do you think?

[jMarcS]

You're right, the parameter really is a logical expression. Somehow I missed that we're using lexp in descriptions of parameters. That's much better.

To me, "true (non-zero or missing)" implies "missing" means "true" for logical expressions in general. I think more often "missing" means "false", just not for this command. Can you live with, "If the parameter is absent or true (non-zero)", or something similar?

Putting the advice about using the parameter where you have it works well. With yesterday's code change, there's an even more compelling reason to connect without the wait.

[mrleavitt]

Done.