File Name
Syntax
ChangeState(REF stateData:EMAStateRec, VAL transition:INTEGER, REF mainData:EMAMainDataRec )
Parameters
stateData (I/O) - state description record
transition (I) - the requested transition for the machine
Returns
1 = success
0 = failure, state structure not initialized or corrupted
-1 = failure, illegal state transition, state not changed.
-2 = failure, state changed to a "failed state"
Side Effects
None
Description
This routine attempts to move the state machine to the next state, based on the current state and the state transition tables. NOTE: This routine does NOT perform any GUI operations. Caller is expected to call UpdateMainGUI if desired.
Dialog Forms Called
None
File Name
Syntax
ContinueMessageProcessing ( REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record (with dlgWindow)
Returns
1 = success
0 = failure
Side Effects
Mail and TPM login records may be modified.
Description
This routine is only called if the system is already processing messages and is ready to read/process the next message.
Dialog Forms Called
None
File Name
Syntax
DisconnectFromEA(REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record
Returns
1 = success
0 = Failure
Globals Changed: Sets TPM data and stateData in the mainData structure.
Side Effects
None
Description
This routine performs the steps necessary to disconnect from the TPM database. It sends out a TMG distress call to the current list of TMG administrators (via e-mail.)
Dialog Forms Called
None
File Name
Syntax
DisconnectFromEMail(REF mainData:EMAMainDataRec )
Parameters
mainData - the EMA context record
Returns
1 = success
0 = Failure
Side Effects
None
Description
This routine performs the steps necessary to disconnect from the e-mail system. It creates a new problem ticket in the database to alert the support center that TMG is down.
Dialog Forms Called
None
File Name
Syntax
EMAInitialize ( REF mainData:EMAMainDataRec )
Parameters
mainData (I/O) - the TMG context record (with dlgWindow)
Returns
1 = Success
0 = Failure
Side Effects
Mail and TPM login records may be modified.
Description
Perform the normal startup operations (after window has been created.)
Dialog Forms Called
None
File Name
Syntax
EMAMainEvent ( REF mainData: EMAMainDataRec )
Parameters
mainData - instance data for this window
Returns
1 = tells window system EMAMainEvent successful, continue
0 = tells window system to abort operation or problems
Side Effects
Various windows may appear and the instance data record will be modified
Description
This is the main window event handler routine for this module. Special Notes: The TSD Script timer system is dependent on the underlying operating system for setting, stopping and "ticking" of timers. Much of TMG is set up around timers. (The central timer is for periodic polling of the TMG e-mail server account. Another is set up to introduce an "event window" between the processing of each incoming mail message.) Due to the nuances of the SendMessaging of the StopTimer message, it is possible that a latent $MsgTimer event from a stopped timer can still be delivered. This can introduce some problems with the state machine if StopTimer messages can be sent in response to other events. The code could get very convoluted. In order to work around these timing problems, this code will stop a timer ONLY when it is receiving a $MsgTimer event from the timer to be stopped. Thus, a transition in the state machine to a state implying "timer stopped" will (in fact) only be completed when the active $MsgTimer has arrived for that timer.
Dialog Forms Called
None
File Name
Syntax
EMAStartup( VAL args:LIST OF STRING )
Parameters
MonitorData - contains one monitor record
Returns
1 = success
0 = failure
Side Effects
A main window appears.
Description
This is the main driver function for this KB file. It puts up the main window for the program and passes control to the event handler routine.
Dialog Forms Called
None
File Name
Syntax
HandleEMailError(REF status:INTEGER, REF mainData:EMAMainDataRec, VAL routineName:STRING, VAL noStateTransition:BOOLEAN ):INTEGER IS
Parameters
mainData - the TMG context record (with dlgWindow)
status - status returned by TMG EMailXxx routines
routineName - routine which yielded the error
noStateTransition - prevent state trans to email error
Returns
1 = success
0 = failure
Side Effects
Mail and TPM login records may be modified.
Description
This routine is designed to take the standard return status from TMG's EMailXxx routines and make a decision. If the status implies a fatal, non-continuable e-mail error, the routine moves to the e-mail error state (and do unless the noStateTransition argument is set.
Dialog Forms Called
None
File Name
Syntax
HandleEmailPollingEvent ( REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record (with dlgWindow)
Returns
1 = success
0 = failure
Side Effects
Mail and TPM login records may be modified.
Description
Performs the operations in response to a polling timer event. Essentially, this routine is a "process a new message IF one has arrived" routine. It is assumed that the main timer is "off", and that the routine must determine if it should transition to the Processing state. If no transition occurs, the timer must be restarted from this routine. For non-message-processing states, the goal is to keep the main GUI 'current unprocessed message count' field up to date (at the 'polling interval' rate.)
Dialog Forms Called
None
File Name
Syntax
HandleMenuSelection ( REF mainData: EMAMainDataRec, VAL dlgWindow: WINDOW, VAL menuID: INTEGER )
Parameters
mainData - the TMG context record (with dlgWindow)
Returns
1 = success
0 = failure
Side Effects
Boxes may appear, messages may be sent, and data may be modified.
Description
Performs the appropriate functions for the the various selections from the application menu bar.
Dialog Forms Called
None
File Name
Syntax
HandleRIFailure(REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record
Returns
1 = success
0 = Failure
Side Effects
None
Description
This routine performs the steps necessary to handle a referential integrity failure on an attempted insert into the TPM database. It sends out a TMG distress call to the current list of TMG administrators (via e-mail.)
Dialog Forms Called
None
File Name
Syntax
InitializeState(REF stateData:EMAStateRec )
Parameters
stateData (I/O) - state description record
Returns
1 = success
0 = failure, state not initialized
Side Effects
None
Description
This routine will initialize the state machine in preparation for subsequent calls to ChangeState.
Dialog Forms Called
None
File Name
Syntax
MungeEMailStatus ( REF status:INTEGER, REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record (with dlgWindow)
status - status variable of an EMailXxxx call
Returns
1 = Success
0 = Failure
Side Effects
None
Description
This routine is designed to falsely run a fatal e-mail error if the environment is set up to allow it. It modifies the status variable passed in to be a Fatal error.
Dialog Forms Called
None
File Name
Syntax
PerformSelectAction ( REF mainData: EMAMainDataRec, VAL dlgHandle: WINDOW, VAL controlName: STRING, VAL controlID: INTEGER )
Parameters
mainDlgData - the instance data for this window
dlgHandle - window handle of dialog box
controlName - name of the control selected
controlID - number id of the control selected
Returns
1 = success
0 = failure
Side Effects
TDT does not assure that a StopTimer message prevents any latent timer messages from being delivered. (Thus, the previous timer must die before starting a new one.) m_mainData module record may be touched.
Description
This routine performs actions for controls in the main window dialog box. It consists entirely of handling button events, because there are no other user-active controls in the main interface dialog box.
Dialog Forms Called
None
File Name
Syntax
PlaceholderEvent
Parameters
None
Returns
None
Side Effects
m_aboutData.aboutWindow field might be cleared.
Description
This routine provides basic event handling for the About Box window.
Dialog Forms Called
None
File Name
Syntax
ProcessAMessage( REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record (with dlgWindow)
Returns
1 = success
0 = failure
Side Effects
Log, User and statisticss boxes may be updated.
Description
This routine processes a single e-mail message. (It is assumed that the caller has Read a mail message.) This routine parses and executes the command. It validates the user, sends the reply to the user, and updates the main GUI.
Dialog Forms Called
None
File Name
Syntax
ReconnectToEA(REF mainData:EMAMainDataRec )
Parameters
mainData (I/O) - the TMG context record
Returns
1 = success
0 = Failure
Side Effects
None
Description
This routine performs the steps necessary to reconnect to the TPM database, and (if successful) make a transition out of the EA_CONNECT_ERROR state.
Dialog Forms Called
None
File Name
Syntax
ReconnectToEMail(REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs the steps necessary to reconnect to the e-mail system, and (if successful) make a transition out of the EMAIL_CONNECT_ERROR state.
Dialog Forms Called
None
File Name
Syntax
SendReplyAsAttachment( VAL outputBody: STRING )
Parameters
mainData (I/O) - the TMG context record (with dlgWindow)
Returns
TRUE
FALSE
Side Effects
None
Description
This function determines if the body of the outgoing message exceeds the maximum defined length, in which case it is sent as an attachment.
Dialog Forms Called
None
File Name
Syntax
SendUserReply ( REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record (with dlgWindow)
Returns
1 = success
0 = failure
Side Effects
Mail and TPM login records may be modified.
Description
This routine takes the contents of the command line data output sections and sends them as an e-mail reply to the user designated in the From field. The exception to this would be gross failures that require the attention of the administrator. Note: Unlike other e-mail routines in this module, this routine will NOT make a transition to the e-mail error state if the Send fails.
Dialog Forms Called
None
File Name
Syntax
ShutDownAndCloseWindow (REF mainData:EMAMainDataRec, VAL promptUser:BOOLEAN )
Parameters
mainData - the EMA context record (with dlgWindow)
promptUser - flag indicating whether to prompt on exit
Returns
1 = success
0 = failure, or user said no
Side Effects
Mail connections are shut down and files are closed.
Description
Shuts down the application and closes the window with the supplied handle.
Dialog Forms Called
None
File Name
Syntax
StartEmailTimer(REF mainData:EMAMainDataRec, VAL timerSpeed:INTEGER )
Parameters
mainData - the TMG context record (with dlgWindow)
Returns
1 = success
0 = failure, or timer was already on (based on mainData)
Side Effects
Sets state data timerOn; retrieves configData.
Description
This routine performs appropriate operations to get the TMG e-mail timer started.
Dialog Forms Called
None
File Name
Syntax
StartIntraMessageTimer(REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record (with dlgWindow)
Returns
1 = success
0 = failure, or timer was already on (based on mainData)
Side Effects
Sets state data timer2On.
Description
This routine performs appropriate operations to start up the intramessage timer.
Dialog Forms Called
None
File Name
Syntax
StartMessageProcessing( REF mainData:EMAMainDataRec )
Parameters
mainData - the TMG context record (with dlgWindow)
Returns
1 = success
0 = failure
Side Effects
Mail and TPM login records may be modified.
Description
This routine is called when a timer has gone off and the system needs to check to see if there are any new messages.
Dialog Forms Called
None
File Name
Syntax
StopEmailTimer(REF mainData:EMAMainDataRec, VAL shouldBeOn:BOOLEAN )
Parameters
mainData - the TMG context record (with dlgWindow)
shouldBeOn - flag indicating that the timer should be on
Returns
1 = success
0 = failure, or timer was already off (based on mainData)
Side Effects
Sets state data timerOn
Description
This routine performs appropriate operations to get the TMG e-mail timer stopped.
Dialog Forms Called
None
File Name
Syntax
StopIntraMessageTimer(REF mainData: EMAMainDataRec, VAL shouldBeOn: BOOLEAN )
Parameters
mainData - the TMG context record (with dlgWindow)
shouldBeOn - flag indicating that the timer should be on and running
Returns
1 = success
0 = failure, or timer was already off (based on mainData)
Side Effects
Sets state data timer2On
Description
This routine performs appropriate operations to destroy the intra-message timer. (The timer stops regardless of whether it is on or not.)
Dialog Forms Called
None
File Name
Syntax
TransferAttribsToModuleRec(VAL mainAttribList:LIST OF DBDialogAttribRec, REF mainData:EMAMainDataRec )
Parameters
mainAttribList (O) - data return value
Returns
1 = success
0 = failure
Side Effects
None
Description
This function transfers the "DB attributes" list to the module module data structure.
Dialog Forms Called
None
File Name
Syntax
TransferModuleRecToAttribs(REF mainAttribList:LIST OF DBDialogAttribRec, REF mainData:EMAMainDataRec )
Parameters
mainAttribList (O) - data return value
Returns
1 = success
0 = failure
Side Effects
None
Description
This function transfers the module data structure contents "DB attributes" list for transmission to the database.
Dialog Forms Called
None
File Name
Syntax
UpdateCurrentProcessGUI(VAL mainWindow:WINDOW, VAL mailData:EMailDataRec, VAL cliData:CLIDataRec )
Parameters
mainData (I/O) - main data record for app
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine will update the main interface based on the current state and the data in the system.
Dialog Forms Called
None
File Name
Syntax
UpdateMainGUI(VAL mainWindow: WINDOW, VAL mainData: EMAMainDataRec )
Parameters
mainData - main data record for application
Returns
1 = success
2 = GUI not updated, current state = previous state
Side Effects
None
Description
This routine updates the main interface based on the current state and the data in the system.
Dialog Forms Called
None
File Name
Syntax
UpdateMainGUIState(VAL mainWindow:WINDOW, VAL curState:INTEGER )
Parameters
mainData - main data record for application
curState - current application state index
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine updates the main interface user input controls based on the state of the application.
Dialog Forms Called
None
File Name
Syntax
UpdateServerStateGUI(VAL mainWindow:WINDOW, VAL curState:INTEGER )
Parameters
mainData - main data record for application
curState - current application state index
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine updates the main interface based on the current state and the data in the system.
Dialog Forms Called
None
File Name
Syntax
UpdateSummaryGUI(VAL mainWindow:WINDOW, VAL messageCount:INTEGER, VAL unreadableMessageCount:INTEGER )
Parameters
mainData - main data record for application
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine updates the main interface summary section.
Dialog Forms Called
None