Source Format Exit

When you write a Source Format Exit routine for Optim, you specify the exit function, PSTColMapAgeSrcExit (PSTColMapAgeSrcWExit), and the following parameters:

single-byte
PSTColMapAgeSrcExit
   (PST_STRUCT_CM_AGE_SRCFMT_PARM * pInputParms,
   PST_STRUCT_CM_EXIT_COL_LIST * pSrcColList,
   PST_STRUCT_CM_EXIT_COL_LIST * pDstColList)
UTF-16
PSTColMapAgeSrcWExit
   (PST_STRUCT_CM_AGE_SRCFMT_WPARM * 
pInputParms,
   PST_STRUCT_CM_WEXIT_COL_LIST * pSrcColList,
   PST_STRUCT_CM_WEXIT_COL_LIST * pDstColList)

Parameters

When an Optim process calls a source format exit routine, the process passes the following parameters:

pInputParms
Pointer to PST_STRUCT_CM_AGE_SRCFMT_PARM (PST_STRUCT_CM_AGE_SRCFMT_WPARM). This structure contains information about the source and destination tables, the nature of the current call, and pointers to a call-back function and work areas.

The first field in this structure is the FuncCode field identified by either PST_CM_SRCFMT_TRANSFORM (PST_CMW_SRCFMT_TRANSFORM) or PST_CM_SRCFMT_TERMINATE (PST_CMW_SRCFMT_TERMINATE).

pSrcColList
Pointer to PST_STRUCT_CM_EXIT_COL_LIST (PST_STRUCT_CM_WEXIT_COL_LIST). This structure describes the source columns.
pDstColList
Pointer to PST_STRUCT_CM_EXIT_COL_LIST (PST_STRUCT_CM_WEXIT_COL_LIST). This structure describes the destination columns.

Call-Back Function

Each time an Optim process calls a source format exit routine, the process passes the address of the following call-back function:

pPSTGetColValue( )
Retrieves data for all source columns and most destination columns in the current data row. In general, the exit routine does not need to call this function because the data for the source column is provided in the first parameter. However, the exit routine can call this function to retrieve the data for different columns.

Processing

Typical processing for the Source Format Exit routine is summarized in the following steps:

  1. On every call from Optim, the exit routine checks for a first time call. On the first call, the exit performs any initialization tasks and normal processing (step 2). On subsequent calls only normal processing is performed (step 2).
  2. The exit receives the value of the source column as specified in the Age Function defined in the Column Map. Optim does not apply the Age Function before calling the exit routine and stores the raw value in one of the InputValue union fields as indicated by the ValueType field in the header file.
  3. If the exit needs to examine other columns to calculate the value for the destination column, the exit must call the pPSTGetColValue( ) call-back function to obtain the value for those columns.
  4. After the destination value is generated, the exit routine must format the value and place it either in the OutputTimeStamp field or OutputSybDateTime field. Optim validates this value and applies the Age Function. The exit must pass an appropriate return code indicating the field where the data is saved or instructing the process to skip the data row or abort.
  5. After the last data row is processed, Optim passes a termination call to the exit routine, identified by a value of PST_CM_SRCFMT_TERMINATE (PST_CMW_SRCFMT_TERMINATE) in the FuncCode field. This call prompts the exit routine to free any dynamically allocated storage. When final tasks are complete, the exit routine passes a return code to Optim.

Abort Modes

There are several ways that the Source Format Exit routine can abort processing:

The exit routine passes a return code indicating which date format or which abort mode to use.

During a process, the exit routine may interrogate any columns from the input row and some of the columns from the destination row. However, the exit routine cannot interrogate a destination column that includes an exit routine and is defined in the Column Map after the current destination column. All other destination columns are available.

Return Codes

The following return codes apply to source format exits:

PST_CM_SRCFMT_USE_TIMESTAMP
(PST_CMW_SRCFMT_USE_TIMESTAMP)

Destination column is assigned a value in the OutputTimeStamp field of the first parameter passed to the exit.

PST_CM_SRCFMT_USE_SYB_DATETIME
(PST_CMW_SRCFMT_USE_SYB_DATETIME)

Destination column is assigned a value in the OutputSybDateTime field of the first parameter passed to the exit.

PST_CM_SRCFMT_SKIP
(PST_CMW_SRCFMT_SKIP)

Aging is not applied. If you do not select the option to Process rows with skipped dates, the row is rejected. Otherwise, the data is copied to the source, as long as the source and destination are compatible. If not compatible, the row is rejected.

PST_CM_SRCFMT_COL_INVALID
(PST_CMW_SRCFMT_COL_INVALID)

Aging is not applied. If you do not select the option to Process rows with invalid dates, the row is rejected. Otherwise, the data is copied to the source, as long as the source and destination are compatible. If not compatible, the row is rejected.

PST_CM_SRCFMT_REJECT_ROW
(PST_CMW_SRCFMT_REJECT_ROW)

Source column cannot be assigned a value. Reject (discard) the row.

PST_CM_SRCFMT_ABORT_PROCESS
(PST_CMW_SRCFMT_ABORT_PROCESS)

Fatal error. Terminate. To return an error message, place the message in the work area and set the unused space to blanks or NULL.