Routines for ema_user.kb


DBGetStatsInfo

File Name

ema_user.kb

Syntax

DBGetStatsInfo( REF statsInfo:UserListRowRec );

Parameters

statsInfo (O) - returned list of attributes

Returns

1 = success

0 = failure

-n = failure, database error code

Side Effects

None

Description

This function gets the command statistics from the database. It is assumed that this routine is only called once.

Dialog Forms Called

None


DBSetStatsInfo

File Name

ema_user.kb

Syntax

DBSetStatsInfo( REF deltaInfo:UserListRowRec, VAL showError:BOOLEAN );

Parameters

deltaInfo(I/O) - changes in the counts since last refresh.

showError(I) - controls whether TSD Script SQL messages are allowed to appear on the screen

Returns

1 = success

0 = No-op, statistic needed no updating

-n = failure, database error code

Side Effects

None

Description

This function updates the statistical information stored in the database. The method used here would allow multiple servers to talk to the same TMG database as it attempts to "bump" the counts by the delta value recorded during this server session. Thus, other servers updating the values would not interfere.

Dialog Forms Called

None


ExportUserActivityData

File Name

ema_user.kb

Syntax

ExportUserActivityData( VAL wHdlParent: WINDOW );

Parameters

wHdlParent(I) - the parent window

Returns

1 = success

0 = user aborted

-n = file i/o error

Side Effects

None

Description

This routine exports the user activity data to a tab delimited text file for reporting purposes. The resulting file may be used as a data source for the supplied Crystal report "ema_user.rpt" or for any other desired report writer.

Dialog Forms Called

None


ModuleTestEventHandler

File Name

ema_user.kb

Syntax

ModuleTestEventHandler( REF moduleTestData: ModuleTestRec );

Parameters

ModuleTestData (I/O) - instance data for this dialog box type

Returns

1 = success

0 = failure

Side Effects

None

Description

This routine provides event handling for the Module Test dialog box.

Dialog Forms Called

None


RefreshListBoxFromData

File Name

ema_user.kb

Syntax

RefreshListBoxFromData( REF userLBData:UserDialogRec );

Parameters

userLBData (I/O) - data record handle

Returns

1 = success

0 = failure

-n = failure code from database action

Side Effects

None

Description

This function transfers the information stored in the data structure rows into the list box. The box is cleared before insertion.

Dialog Forms Called

None


TransferRowToGUIFields

File Name

ema_user.kb

Syntax

TransferRowToGUIFields( REF userLBData:UserDialogRec );

Parameters

userLBData (I/O) - data record handle

Returns

1 = success

0 = failure

-n = failure code from database action

Side Effects

None

Description

This function transfers the information stored in the current row into the various matching GUI fields. If there is no current row, it clears the fields.

Dialog Forms Called

None


UpdateSingleStatistic

File Name

ema_user.kb

Syntax

UpdateSingleStatistic( VAL statisticName:STRING, REF deltaStatisticValue:INTEGER );

Parameters

statisticName(I) - name of stat in DB

deltaStatisticValue (I/0) - value to add to the currently stored value

Returns

1 = success

0 = No-op, statistic needed no updating

-17342 = failure, passive concurrency error

-n = failure, database error code

Side Effects

None

Description

This function updates a single entry (column) in the database statistics table. NOTE: If successful, this routine sets the

Dialog Forms Called

None


UserActCreateDialog

File Name

ema_user.kb

Syntax

UserActCreateDialog( VAL parentWindow:WINDOW );

Parameters

parentWindow (I) - window handle of parent for new dialog box

Returns

2 = already up

1 = success

0 = failure

Side Effects

None

Description

This function creates a dialog bpx of type user. Before calling this function, you should always call UserActInitData. If you fail to do so, this routine detects it and calls it for you. If you need to alter the values that appear in the dialog, call GetData, set the values in the data structure, call SetData, then call this routine. Your program should call InitData on startup.

Dialog Forms Called

None


UserActDBLoadTable

File Name

ema_user.kb

Syntax

UserActDBLoadTable( REF userLBData:UserListDataRec );

Parameters

userLBData (I/O) - data record handle

Returns

1 = success

0 = failure

-n = failure code from database action

Side Effects

None

Description

This function loads the data structure list from the database table.

Dialog Forms Called

None


UserActDestroyDialog

File Name

ema_user.kb

Syntax

UserActDestroyDialog;

Parameters

None

Returns

1 = success

0 = failure

Side Effects

None

Description

This function destroys the dialog box (if it is currently visible). Generally, you should avoid calling this function as it can be perceived as rude to tear down a box the user might be viewing. It would be appropriate if the application was dying.

Dialog Forms Called

None


UserActDlgRestoreData

File Name

ema_user.kb

Syntax

UserActDlgRestoreData( REF userData:UserDataRec );

Parameters

userData (O) - data return value

Returns

1 = success

0 = failure

Side Effects

None

Description

This function restores the dialog box data associated with this module from a file or database.

Dialog Forms Called

None


UserActDlgSaveData

File Name

ema_user.kb

Syntax

UserActDlgSaveData( REF userData:UserDataRec );

Parameters

userData (O) - data return value

Returns

1 = success

0 = failure

Side Effects

None

Description

This function saves the dialog box data associated with this module into some persistent form (such as a database or file.) Note that this does not include the list box data, which is assumed to be saved immediately with interactive controls.

Dialog Forms Called

None


UserActEnableControls

File Name

ema_user.kb

Syntax

UserActEnableControls( VAL enableControls:BOOLEAN, VAL msgString:STRING );

Parameters

enableControls(I) - TRUE (enable) or FALSE (disable)

msgString(I) - string to write to the message line in the dialog box (if there is one).

Nothing is written if this is $Unknown.

Returns

1 = success

0 = failure

Side Effects

None

Description

This function enables or disables the user controls and outputs a string to the message line (if there is one).

Dialog Forms Called

None


UserActEventHandler

File Name

ema_user.kb

Syntax

UserActEventHandler( REF userDlgData: UserDialogRec );

Parameters

userDlgData (I/O) - instance data for this dialog box type

Returns

1 = success

0 = failure

Side Effects

None

Description

This routine provides event handling for the user dialog box.

Dialog Forms Called

None


UserActGetData

File Name

ema_user.kb

Syntax

UserActGetData( REF userData:UserDataRec );

Parameters

userdata - data return value

Returns

1 = success

n = return values for UserActInitData

Side Effects

None

Description

This function gets the dialog box data associated with this module.

Dialog Forms Called

None


UserActInitData

File Name

ema_user.kb

Syntax

UserActInitData;

Parameters

None

Returns

1 = success

0 = failure

Side Effects

None

Description

This function initializes the module data structure with information that is static.

Dialog Forms Called

None


UserActLBEnter2ndaryFieldAction

File Name

ema_user.kb

Syntax

UserActLBEnter2ndaryFieldAction( REF userLBData:UserDialogRec, VAL fieldName:STRING );

Parameters

userLBData (I/O) - list box handle

updateDB (I) - indicates whether to save operation

Returns

1 = success

2 = list was empty

0 = failure return codes from DlgSetEnabled

-n = failure return codes from DlgSetEnabled

Side Effects

None

Description

This function enables the modify button for entry into non-key fields in the GUI. (Add will be done for entry into key fields.) More explanation in EnterKeyFieldAction.

Dialog Forms Called

None


UserActLBModifyAction

File Name

ema_user.kb

Syntax

UserActLBModifyAction( REF userLBData:UserDialogRec, VAL updateDB:BOOLEAN);

Parameters

userLBData (I/O) - list box handle

updateDB (I) - indicates whether to save operation

Returns

1 = success

0 = list is empty, there is no selection, no field has been modified, or the user refused to modify

-1 = failed to update internal selection after DB/GUI operation

-n = failed to update DB row (no GUI update) (See DB codes)

Side Effects

None

Description

This function performs a modify function for the currently selected item in the list. Note: This function assumes that the appropriate lists (GUI list box, KML list, DB list) are already positioned at the current item.

Dialog Forms Called

None


UserActLBMsgSelectHandler

File Name

ema_user.kb

Syntax

UserActLBMsgSelectHandler( REF userLBData:UserDialogRec, VAL fieldName:STRING, VAL updateDB:BOOLEAN );

Parameters

userLBData (I/O) - list box handle

updateDB (I) - indicates whether to save operation

Returns

1 = success

2 = Not one of the recognized controls, keep processing

-n = failure code returned by one of the Action routines

Side Effects

None

Description

This function should be called from an event handler for the $MsgSelect event on buttons and the list box. It checks the field name for one of the known control names, and dispatches to the correct Action routine if found. Note that caller is still responsible for handling the Select on any other field in the dialog.

Dialog Forms Called

None


UserActLBSelectAction

File Name

ema_user.kb

Syntax

UserActLBSelectAction( REF userLBData:UserDialogRec );

Parameters

userLBData (I/O) - list box handle

Returns

1 = success

0 = failure

Side Effects

None

Description

This function is called when a new item is selected in a list box.

Dialog Forms Called

None


UserActNewMessage

File Name

ema_user.kb

Syntax

UserActNewMessage( REF userName:STRING, VAL userAddr:STRING, VAL serverAccount:STRING, VAL cmdCode:INTEGER, VAL errorThreshold:INTEGER, VAL accessStatus:INTEGER );

Parameters

userName(I) - user e-mail account name

userAddr(I) - user e-mail address name

cmdCode(I) - parsed code number for user command

errorThreshold(I) - maximum consecutive errors before cut off

accessStatus(I) - stored access state for this user

serverAccount(I) - name of server e-mail account

Returns

1 = success

2 = failure, record updated, but user exceeded max error count

or the mail was sent in from the server account. Send no reply.

3 = failure, record updated, but user is denied by the administrator

4 = failure, message was received from a postmaster account. Send no reply.

0 = error in the set of input arguments

-n = some other kind of failure

Side Effects

None

Description

This function makes an entry for a new message coming through the system. If we have not received a message previously from this user, a new entry is made in the User Activity list. If it is not a new user, the user's current entry is modified to reflect the user's latest command. The system returns a 1 success code if all is well. It returns a 3 failure code if the user has been denied access by the administrator. A failure code of 2 indicates failure, and that no reply should be sent (for example, the user has exceeded the error threshold, or the mail came from the server account. Notes: This routine does not care about current row in the list box. If this is being called, then the server is running, and the user's old selection is irrelevant. (Selection is "off" while the server is "on".) In fact, current item tracking lists are ignored by this routine, as they will always be forced to new values by necessity.

Dialog Forms Called

None


UserActSaveData

File Name

ema_user.kb

Syntax

UserActSaveData;

Parameters

None

Returns

1 = success

0 = failure

Side Effects

None

Description

This function saves the dialog box data associated with this module into a file or database.

Dialog Forms Called

None


UserActSetData

File Name

ema_user.kb

Syntax

UserActSetData( REF userData:UserDataRec );

Parameters

userdata - data return value

Returns

1 = success

n = return values for UserActInitData

Side Effects

None

Description

This function sets the dialog box data associated with this module.

Dialog Forms Called

None


UserActShutDown

File Name

ema_user.kb

Syntax

UserActShutDown( VAL callerStatus:INTEGER );

Parameters

callerStatus (I) - caller's shutdown status. If caller is closing down due to

internal problems, then this module should probably abort.

Returns

1 = success

0 = failure

Side Effects

None

Description

This function performs the final operations for this module in expectation that the calling application is shutting down. It is a final safety valve.

Dialog Forms Called

None


UserActTestThisModule

File Name

ema_user.kb

Syntax

UserActTestThisModule;

Parameters

None

Returns

Nothing

Side Effects

None

Description

None

Dialog Forms Called

None