Omitted parameters
In the Synopsis section for each function, when an argument is colored red, then this means that the argument is optional. (ie, You can omit passing it to the function). RexxSock will then usually substitute some default value for that argument, or perform some default action. When an argument is colored blue, then you must pass that argument.
REXX variable names as arguments
For some RexxSock functions, they need to be passed the name of a REXX variable to operate upon.
In the Args section for each function, when part of a REXX variable name is in italics, then this means that the actual passed argument is substituted. For example, let's assume that there is an RexxSock function named SockSomething() that is passed the name of a REXX stem variable. Its Synopsis is shown as so:
SockSomething('stem.')
Also, under the Args section of SockSomething is the following text:
SockSomething sets the variable stem.FAMILY to 1.
Now assume that the REXX script calls SockSomething as so:
SockSomething('myvar.')Then for the expression stem.FAMILY, SockSomething would substitute what was actually passed and it would therefore set the REXX variable MYVAR.FAMILY to 1.
Note that normal REXX tail name substitution is performed by RexxSock. For example, assume that the REXX script has the following statements:
FAMILY = 'this' SockSomething('myvar.')Then the REXX variable that RexxSock sets to 1 would actually be MYVAR.THIS. (ie, "FAMILY" gets substituted with its value). If you wish to avoid this behavior, one technique is to pass a stem name with an exclamation point appended to it, and use exclamation points only with your variable names passed to RexxSock, as so:
SockSomething('myvar.!')This helps circumvent the problem with tail name substitution. Since you probably don't normally use exclamation points in variables used in other places in your script, it's unlikely that you will be using the variable "!FAMILY" elsewhere in your script, and therefore do not have to worry about it having some preceding value. So the REXX variable that RexxSock sets to 1 would be MYVAR.!FAMILY. (ie, The exclamation point is included in the variable name).
In lieu of an exclamation point, you may prefer other characters, including "_", "0", and "1". (The digits 0 and 1 are allowed to prefix tail names and are very useful for preventing an unwanted tail name substitution by RexxSock).
Dotted IP address
A dotted IP address is an internet "address" containing 4 numbers separated by 3 decimal points. For example, the string "9.23.19.63" is a valid dotted IP address.
ErrNo and Error messages
For the majority of RexxSock functions, they set the value of the REXX variable named ErrNo (or SockErrNo if you enable that option via SockInit). If an RexxSock function succeeds, then ErrNo is set to 0. If an RexxSock function fails, then ErrNo is set to some "symbolic error name". For example, if SockSend() fails because the connection to the external peer was reset by that peer, then ErrNo is set to the (string) value "ECONNRESET".
To retrieve an informative error message about that failure, you can use the RexxSock function SockErrMsg().
So, here is an example of how a failure in some RexxSock function would be handled, and how to display an appropriate error message:
SockSomething('myvar.!') IF ErrNo \== 0 THEN SAY SockErrMsg(ErrNo) ELSE SAY "SockSomething() performed successfully!"Consult the chart Symbolic error names for ErrNo for a listing for symbolic error names, and what each means.
You can also have most of the RexxSock functions raise a USER condition when they fail. This means that you do not have to error check the returns of most functions. You can simply trap the USER condition and handle error checking there. This greatly streamlines your code and makes it run faster and is easier to read and modify. To set RexxSock to use a USER condition for errors, you must call SockInit() and pass it the desired USER condition number.