Standard Exit Routine

When you write a Standard Exit, you specify the exit function, PSTColMapExit (PSTColMapWExit), and the following parameters:

single-byte
PSTColMapExit 
   (PST_STRUCT_CM_EXIT_PARM * pInputParms, 
    PST_STRUCT_CM_EXIT_COL_LIST * pSrcColList, 
     PST_STRUCT_CM_EXIT_COL_LIST * pDstColList)
UTF-16
PSTColMapWExit 
   (PST_STRUCT_CM_WEXIT_PARM * pInputParms,
    PST_STRUCT_CM_WEXIT_COL_LIST * pSrcColList,
     PST_STRUCT_CM_WEXIT_COL_LIST * pDstColList)

Parameters

When a process calls a standard exit routine, the process passes the following parameters on every call:

pInputParms
Pointer to PST_STRUCT_CM_EXIT_PARM (PST_STRUCT_CM_WEXIT_PARM). This structure contains information about the source and destination tables, the nature of the current call, number of optional parameters specified with the exit, and pointers to the call‑back functions, work areas, and optional parameters.

The first field in this structure is the FuncCode field identified by either PST_CM_FUNC_TRANSFORM (PST_CMW_FUNC_TRANSFORM) or PST_CM_FUNC_TERMINATE (PST_CMW_FUNC_TERMINATE).

The field NumParms contains the number of optional parameters specified with the Column Map exit (0 to 8).

The field pParm contains an array of pointers to each optional parameter specified with the Column Map exit.

pScrColList
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 Functions

Each time an Optim process calls a standard exit routine, the process passes the addresses of the following call-back functions:

pPSTGetColValue( )
Retrieves data for all source columns and most destination columns in the current data row. In general, the exit routine calls this function only once to retrieve the data for a source column. However, the exit routine can call this function several times to retrieve the data for different columns.
pPSTPutColValue( )
Specifies data for the destination column in the current data row. The exit routine determines the value for the destination column and returns the value to Optim. This function must be called unless the row is rejected or the process is aborted.

Processing

Typical processing for the Standard 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. Optim does not pass column data to the standard exit routine; however, the exit routine can make calls to the pPSTGetColValue() call-back function to obtain data for the source columns. These values are needed to determine the value of the destination column.
  3. After the exit routine generates the destination value, the exit either calls the pPSTPutColValue( ) call-back function to store the value in the destination column or passes an appropriate return code instructing the process to skip the data row or abort.
  4. After the last data row is processed, the Optim passes a termination call to the exit routine, identified by a value of PST_CM_FUNC_TERMINATE (PST_CMW_FUNC_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.

Return Codes

The following return codes apply to standard exit routines:

PST_CM_EXIT_SUCCESS
(PST_CMW_EXIT_SUCCESS)

Destination column is assigned a value or is successfully transformed.

PST_CM_EXIT_REJECT_ROW
(PST_CMW_EXIT_REJECT_ROW)

Destination column cannot be assigned a value or transformed. Discard the row.

PST_CM_EXIT_ABORT_PROCESS
(PST_CMW_EXIT_ABORT_PROCESS)

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