As a result of additional feedback and looking to future needs, beginning with version 108, the input reply message format has been changed. All messages sent to the server from the client program will be a single line of ASCII text. The first character of the line will contain a single character that will indicate the type of message that is being sent.
The first character type codes are:
0 - illegal
1 - error
2 - data
3 - event
Because of the behavior of ON xxx GOTO, "0" was not a good choice for any message type because both "0" and anything out of range would fall through. Thus "0" had to be explicitly tested for (vs. "A", which AlphaBASIC automatically converts (casts) as the number zero if a number is expected. Anything that falls through should be treated as an unknown error (as opposed as to an error message (type 1) with a known format).
Messages will only be sent to the server when requested by the server application. Events and errors will be queued up in the client application until requested. There are two basic message request command types:
- Data requests are sent to request specific information. See Data Request Commands.
- Event requests are sent to request the next queued event. See Events.
Either of these two requests may return an error message so the return response message will need to be checked.
Data requests will return the requested information (type code 2) or an error (type code 1) if the specific data request generated an error.
Two separate message queues are maintained. All events will be placed into the event queue as they occur. All errors not generated by a data request command (as defined above) will be placed into the error queue as they occur.
Event requests will return the next event or an error that may have occurred any time prior to the request.
The following rules define what occurs when the server
1. If any errors are waiting in the error queue, the first error in the queue will be returned.
2. If no errors are queued, the first event in the event queue will be returned.
3. If both queues are empty, the client will wait for the next event to occur.
Reading the input response line into a mapped variable will facilitate processing of the message.
Here is one example of a generalized reply subroutine:
Map1 TgReply$,S ! read the response into this string variable
Map2 TgTypeCode$,S,1 ! this string gets the reply type code
Map2 TgText$,S ! this string gets the actual reply text
Map3 TgErrorCode$,S,3 ! if error, the error code goes here
Map3 TgComma$,S,1 ! if error, this is a comma
Map3 TgErrorMessage$,S,200 ! if error, this gets the error message
! Here is one method to wait for any user input
Tg'Get'Reply:
PRINT "{NextEvent?}"
INPUT LINE TgReply$
ON TgTypeCode$ GOTO &
Tg'Error'Handler & ! for known error reply
Tg'Data'Handler & ! for data reply
Tg'Event'Handler & ! for event reply
Tg'Unknown'Error'Handler:
! If here, an unexpected system error occurred
! This should be logged and/or displayed to the user.
! The program status is unknown, but may well be OK to continue.
! Perhaps:
PRINT #log'channel, "?Unknown TrueGUI Error: " + TgText$
RETURN
Tg'Error'Handler:
! TgErrorCode$ and TgErrorMessage$ are already set, so PERHAPS:
PRINT #log'channel, "?TrueGUI Error: " + TgErrorCode$ + ": " + TgErrorMessage$
RETURN
Tg'Event'Handler:
X = INSTR(2, TgText$, ",") ! find the comma
Event$ = TgText$[1, X-1] ! get the event type
Control$ = TgText$[X+1, -1] ! and the control
! Handle the event based on Event$ and Control$
RETURN
Tg'Data'Handler:
! The requested data is in TgText$
RETURN