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:
- 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).
- 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.
- 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.
- 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.