Routines for ema_log.kb


CloseLogFile

File Name

ema_log.kb

Syntax

CloseLogFile( REF LogData:LogDataRec );

Parameters

LogData - logging dialog box data structure

Returns

1 = success

-1 = see FOpen, operating system error code

Side Effects

None

Description

This routine closes the log window.

Dialog Forms Called

None


CommonWrite

File Name

ema_log.kb

Syntax

CommonWrite( VAL str:STRING, VAL strColor:INTEGER, REF LogData:LogDataRec, VAL newLine:BOOLEAN);

Parameters

str - string to write to log(s)

strColor - for the screen output, string color

LogData - module structure handle

newLine - write a newline at end of str

Returns

-1 = unable to write to file

-2 = unable to write to window

-3 = unable to write to either window or file

1 = success

Side Effects

May write to file or window

Description

This function writes the supplied string to the log file or the log window or both. If the newLine flag is true, the function writes a 'newline' character at the end of str. This function is used by both LogWrite and LogWriteLn. Implementation Notes: This general routine attempts to write to a window, a file, both, or neither. The determination of the ability to write to a file or a window is a combination of variables controlled by the administrator and the current state of the operating environment. If the administrator has requested writing to a file, then there is a file size limit (set by the admin) to be acknowledged. Thus, to write to file, the administrator must have requested the file writing, the file must already be open, and the new line must not exceed the requested limit. Similar conditions must be checked before writing to a window. The window writing has the additional wrinkle of setting the line color.

Dialog Forms Called

None


CreateLogFile

File Name

ema_log.kb

Syntax

CreateLogFile( REF LogData:LogDataRec, VAL promptUserOnError:BOOLEAN, VAL closeCurrent:BOOLEAN, VAL fromStartup:BOOLEAN );

Parameters

LogData - logging dialog box data structure

promptUserOnError - flag: display a message box for errors

closeCurrent - flag: if a file is open, close it

fromStartup - do any special "startup" activity

Returns

1 = success

0 = failure

-3 = target file is full

-2 = bad file name

-1 = see FOpen, operating system error code

Side Effects

None

Description

This routine creates the log window.

Dialog Forms Called

None


CreateLogWindow

File Name

ema_log.kb

Syntax

CreateLogWindow( REF LogData:LogDataRec, VAL startMinimized:BOOLEAN );

Parameters

LogData - logging dialog box data structure

startMinimized - flag to indicate window state at creation

Returns

1 = success

2 = success (already created)

0 = failure

Side Effects

None

Description

This routine creates the log window.

Dialog Forms Called

None


LogCreateDialog

File Name

ema_log.kb

Syntax

LogCreateDialog( VAL parentWindow:WINDOW );

Parameters

parentWindow - 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 box of type log. Before calling this function, you should always call LogGetData on your first argument, and override any necessary values. Failure to call GetData results in the normal defaults not being applied.

Dialog Forms Called

None


LogDestroyDialog

File Name

ema_log.kb

Syntax

LogDestroyDialog;

Parameters

None

Returns

1 = success

0 = failure

Side Effects

None

Description

This function destroys both the dialog box for this KB and the private module data structure. In other words, it reinitializes.

Dialog Forms Called

None


LogDlgRestoreData

File Name

ema_log.kb

Syntax

LogDlgRestoreData( REF errLogData:ErrLogDataRec );

Parameters

LogData - 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


LogEventHandler

File Name

ema_log.kb

Syntax

LogEventHandler( REF LogDlgData:LogDlgDataRec);

Parameters

LogDlgData - instance data for this dialog box type

Returns

1 = success

0 = failure

Side Effects

None

Description

This routine provides event handling for the log dialog box. Note: The last statement of this event handler transfers the instance record information to the module-wide static data, so be sure to avoid using EXIT unless you wish to prevent the record update.

Dialog Forms Called

None


LogGetData

File Name

ema_log.kb

Syntax

LogGetData( REF logData:LogDataRec );

Parameters

logData - data return value

Returns

1 = success

0 = failure

Side Effects

None

Description

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

Dialog Forms Called

None


LogHideDialog

File Name

ema_log.kb

Syntax

LogHideDialog;

Parameters

None

Returns

1 = success

0 = failure

Side Effects

None

Description

This function hides the dialog box for this KB file. It destroys the GUI, but leaves the data structure intact.

Dialog Forms Called

None


LogInitData

File Name

ema_log.kb

Syntax

LogInitData;

Parameters

None

Returns

1 = success

0 = failure

Side Effects

None

Description

This function initializes the module data structure with information in the external data store.

Dialog Forms Called

None


LogSetData

File Name

ema_log.kb

Syntax

LogSetData( REF logData:LogDataRec );

Parameters

logData - data return value

Returns

1 = success

0 = failure

Side Effects

None

Description

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

Dialog Forms Called

None


LogShutDown

File Name

ema_log.kb

Syntax

LogShutDown( VAL callerstatus:INTEGER );

Parameters

callerStatus - caller's shutdown status

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. (If caller is closing down due to internal problems, then this module should probably abort.)

Dialog Forms Called

None


LogTestDialog

File Name

ema_log.kb

Syntax

LogTestDialog;

Parameters

None

Returns

1 = success

0 = failure

Side Effects

None

Description

This procedure is called if this module executes directly. Its function is to bring up the dialog box for interaction and to make calls into the public interface to this module.

Dialog Forms Called

None


LogWinWrite

File Name

ema_log.kb

Syntax

LogWinWrite( VAL str:STRING, VAL strColor:INTEGER, REF LogData:LogDataRec, VAL newLine:BOOLEAN);

Parameters

str - string to write to log(s)

strColor - for the screen output, string color

LogData - module structure handle

newLine - write a newline at end of str

Returns

1 = success

Side Effects

Writes to window

Description

This is a low-level function, which writes the supplied string to the log window.

Dialog Forms Called

None


LogWrite

File Name

ema_log.kb

Syntax

LogWrite( VAL str:STRING, VAL strColor:INTEGER);

Parameters

str - string to write to log(s)

strColor - for the screen output, string color

Returns

-1 = unable to write to file

-2 = unable to write to window

-3 = unable to write to either window or file

1 = success

Side Effects

May write to file or window

Description

This function writes the supplied string to the log file, the log window, or both. This function does not add a newline character at the end of str.

Dialog Forms Called

None


LogWriteIncoming

File Name

ema_log.kb

Syntax

LogWriteIncoming( VAL cmdCode:INTEGER, VAL msgFrom:STRING, VAL msgSubject:STRING, VAL msgBody:STRING, VAL parseStatus:INTEGER );

Parameters

Returns

-1 = unable to write to file

-2 = unable to write to window

-3 = unable to write to either window or file

0 = write not enabled

1 = success

Side Effects

May write to file or window

Description

This function writes the supplied information to the log as requested by the administrator. If the incoming flag has not been set to true, this routine does nothing.

Dialog Forms Called

None


LogWriteLn

File Name

ema_log.kb

Syntax

LogWriteLn( VAL str:STRING, VAL strColor:INTEGER);

Parameters

str - string to write to log(s)

strColor - for the screen output, string color

Returns

-1 = unable to write to file

-2 = unable to write to window

-3 = unable to write to either window or file

1 = success

Side Effects

May write to file or window

Description

This function writes the supplied string to the log file, the log window, or both. This version of this function writes a newline character at the end of str.

Dialog Forms Called

None


LogWriteOutgoing

File Name

ema_log.kb

Syntax

LogWriteOutgoing( VAL cmdCode:INTEGER, VAL msgFrom:STRING, VAL msgSubject:STRING, VAL msgBody:STRING, VAL parseStatus:INTEGER );

Parameters

Returns

-1 = unable to write to file

-2 = unable to write to window

-3 = unable to write to either window or file

0 = write not enabled

1 = success

Side Effects

May write to file or window

Description

This function writes the supplied information to the log as requested by the administrator. If the outgoing flag has not been set to true, this routine does nothing.

Dialog Forms Called

None


PerformAction

File Name

ema_log.kb

Syntax

PerformAction( REF logDlgData:LogDlgDataRec, VAL dlgHandle:WINDOW, VAL controlName:STRING, VAL controlID:INTEGER );

Parameters

LogDlgData - 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

$EventParm(3,T) - old value of the object

$EventParm(4,T) - new value of the object

Returns

1 = success

0 = failure

Side Effects

None

Description

This routine performs actions for controls in the Logging Configuration dialog box. It enables dialog box controls based on the check box (Boolean) screen objects and transfers values to m_errLogData. Note that this routine is nested inside ErrLogEventHandler due to the need to access the various built-in $EventXxx variables. These cannot be passed as arguments without knowing their TSD Script type.

Dialog Forms Called

None


PlaceholderEvent

File Name

ema_log.kb

Syntax

PlaceholderEvent;

Parameters

None

Returns

None

Side Effects

None

Description

This routine provides basic event handling for the scrolling log window.

Dialog Forms Called

None


TransferAttribsToModuleRec

File Name

ema_log.kb

Syntax

TransferAttribsToModuleRec(VAL logAttribList:LIST OF DBDialogAttribRec);

Parameters

logAttribList - structure containing data

Returns

1 = success

0 = failure

Side Effects

None

Description

This function transfers the "DB attributes" list to the module data structure.

Dialog Forms Called

None


TransferModuleRecToAttribs

File Name

ema_log.kb

Syntax

TransferModuleRecToAttribs(VAL logAttribList:LIST OF DBDialogAttribRec);

Parameters

logAttribList - 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


UpdateDialogFromData

File Name

ema_log.kb

Syntax

UpdateDialogFromData(REF logDlgData:LogDlgDataRec, VAL dlgHandle:WINDOW );

Parameters

logDlgData - the instance dialog box data

dlgHandle - window handle of dialog box

Returns

1 = success

0 = failure

Side Effects

None

Description

This routine forces the GUI dialog box object state to conform to the values stored in the data fields. Normally, this is handled by the event handler and its PerformSelectActions routine. This routine provides a mechanism for setting proper GUI state when re-instantiating a dialog box. The enabling of dialog box controls is based on the check box (Boolean) screen objects.

Dialog Forms Called

None