Routines for ema_main.kb


ChangeState

File Name

ema_main.kb

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


ContinueMessageProcessing

File Name

ema_main.kb

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


DisconnectFromEA

File Name

ema_main.kb

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


DisconnectFromEMail

File Name

ema_main.kb

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


EMAInitialize

File Name

ema_main.kb

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


EMAMainEvent

File Name

ema_main.kb

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


EMAStartup

File Name

ema_main.kb

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


HandleEMailError

File Name

ema_main.kb

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


HandleEmailPollingEvent

File Name

ema_main.kb

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


HandleMenuSelection

File Name

ema_main.kb

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


HandleRIFailure

File Name

ema_main.kb

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


InitializeState

File Name

ema_main.kb

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


MungeEMailStatus

File Name

ema_main.kb

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


PerformSelectAction

File Name

ema_main.kb

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


PlaceholderEvent

File Name

ema_main.kb

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


ProcessAMessage

File Name

ema_main.kb

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


ReconnectToEA

File Name

ema_main.kb

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


ReconnectToEMail

File Name

ema_main.kb

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


SendReplyAsAttachment

File Name

ema_main.kb

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


SendUserReply

File Name

ema_main.kb

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


ShutDownAndCloseWindow

File Name

ema_main.kb

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


StartEmailTimer

File Name

ema_main.kb

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


StartIntraMessageTimer

File Name

ema_main.kb

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


StartMessageProcessing

File Name

ema_main.kb

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


StopEmailTimer

File Name

ema_main.kb

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


StopIntraMessageTimer

File Name

ema_main.kb

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


TransferAttribsToModuleRec

File Name

ema_main.kb

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


TransferModuleRecToAttribs

File Name

ema_main.kb

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


UpdateCurrentProcessGUI

File Name

ema_main.kb

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


UpdateMainGUI

File Name

ema_main.kb

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


UpdateMainGUIState

File Name

ema_main.kb

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


UpdateServerStateGUI

File Name

ema_main.kb

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


UpdateSummaryGUI

File Name

ema_main.kb

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