Socket and Xic Client/Server Interface

(string) ReadData(size, skt_handle)
This function will read exactly size bytes from a socket, and return string-type data containing the bytes read. The skt_handle must be a socket handle returned from Sopen. The function will fail (halt the script) only if the size argument is not an integer. On error, a null string is returned, and a message is available from GetError.

Note that the string can contain binary data, and if reading an ASCII string be sure to include the null termination byte. With binary data, the standard string manipulations may not work, and in fact can easily cause a program crash.

(string) ReadReply(retcode, skt_handle)
This function will read a response message from the Xic server. It expects the Xic server protocol and can not be used for other purposes.

The first argument is an array of size 3 or larger. Upon return, retcode[0] will contain the server return code, which is an integer 0-9, or possibly -1 on error. The value in retcode[1] will be the size of the message returned, which will be 0 or larger. The value in retcode[2] will be 0 on success, 1 on error. If an error occurred, an error message is available from GetError.

The return code in retcode[0] can have the following response types:

0	ok
1	in block, waiting for ``end''
2	error
3	scalar data
4	string data
5	array data
6	zlist data
7	lexpr data
8	handle data
9	geometry data
-1	error reading data from server

The return value is of string-type, and may be null or binary. With binary data, the standard string manipulations may not work, and in fact can easily cause a program crash. It is not likely that the return will have any use other than as an argument to ConvertReply.

This function will fail (halt the script) only if the retcode argument is bad.

(variable) ConvertReply(message, retcode)
This function will parse and analyze a return message from the Xic server, which has been received with ReadReply. The first argument is the message returned from ReadReply. The second argument is an array of size 3 or larger, and can be the same array passed to ReadReply. The retcode[0] entry must be set to the message return code, and retcode[1] must be set to the size of the returned buffer. These are the same values as set in ReadReply.

Upon return, retcode[2] will contain a ``data_ok'' flag, which will be nonzero if the message contained data and the data were read properly. The function will fail (by halting the script) if the retcode argument is bad, i.e., not an array of size 3 or larger, or the message argument is not string-type.

The response codes 0-2 contain no data and are status responses from the server. The data responses will set the type and data of the function return, if successful. The retcode[2] value will be nonzero on success in these cases, and will always be false if ``longmode'' is not enabled.

Note that the type returned can be anything, and if assigned to a variable that already has a different type, an error will occur. The delete operator can be applied to the assigned-to variable to clear its state, before the function call.

The response type 9 is returned from the geom server function. This function will return a handle to a geometry stream, which can be passed to GsReadObject.

(int) WriteMsg(string, skt_handle)
This function will write a message to a socket, adding the proper network line termination. The first argument is a string containing the characters to write. The second argument is a socket handle obtained from Sopen. Any trailing line termination will be stripped from the string, and the network termination `` \ r \ n'' will be added.

This function never fails (halts the script). The return value is the number of bytes written, or 0 on error. On error, a message is available from GetError.