(v13) Error reporting functions

This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core

The following types of error reporting function are provided in the PFI:

Allocating, deallocating and clearing the error state structure

The following functions have been defined for managing memory for error state structures:

Allocate an error state structure

This function allocates memory for an error state structure and returns a pointer to it. It is supplied pre‐initialized:

PlgFwErrorState * PlgFwErrorStateAlloc(void);

Deallocate an error state structure

This function releases an allocated error state structure back to the heap. It is not necessary to call

PlgFwErrorStateClear before calling this function.

void PlgFwErrorStateFree(PlgFwErrorState *pErrState);

Clear an error state of a pending error

This function clears the error state structure passed to it of any errors pending:

void PlgFwErrorStateClear(PlgFwErrorState *pErrState);

Error checking functions

Check whether the last operation succeeded

This function is a simple check to see whether or not the last operation succeeded. If it returns TRUE , the operation was a success; if it returns FALSE , more error testing is needed.

uint32 PlgFwErrorIsSuccess(PlgFwErrorState *pErrState);

Retrieve the error's ordinal code

This function returns the corresponding ordinal from the error state given:

uint32 PlgFwErrorOrdinalFromState(PlgFwErrorState *pErrState);

Check with the RIP to see if it recognizes an ordinal code

If the error's ordinal code is known to the RIPʹs PFI compatibility layer, this function returns TRUE , otherwise FALSE .

int32 PlgFwErrorOrdinalIsKnown(uint32 nErrorOrdinal);

Check to see if the current error state is a descendent of another ordinal code

This function checks whether or not the current error state given is a descendant of the error represented by nErrorOrdinal . The function will return TRUE if the error state is a descendant, FALSE if it is not. If nErrorOrdinal is unknown by the RIP's PFI compatibility layer, the function will return FALSE .

Note: Testing any error to see if it is a descendant of itself will return TRUE . All codes representing actual error conditions are descendants of plgFwErrorRoot ; plgFwErrorSuccess is a descendant of itself only.

TEXT

    int32 PlgFwErrorIsDescendant(
                            PlgFwErrorState *pErrState, uint32 nErrorOrdinal);

Generate an error string from the error state

Returns the number of bytes appended to the record.

TEXT

    uint32 PlgFwErrorPrintf(
                        PlgFwStrRecord *pRecord, PlgFwErrorState *pErrState);

Retrieve an error code from a failed call to the operating system

When an error occurs in an operation passed to the underlying operating system, there is usually a platform‐specific error code value associated with the error. This function places in *p32x2 a 64‐bit signed number which is either zero, or contains the platform‐specific error code value. The return

value is TRUE on success, or FALSE , in which case the value to which p32x2 points has not been changed.

TEXT

    int32 PlgFwErrorPlatformErrorFromState(
                        PlgFwStrRecord *pRecord, Hq32x2 *p32x2);