When you write a Destination Format Exit routine
for Optim,
you specify the exit function, PSTColMapAgeDstExit (PSTColMapAgeDstWExit),
and the following parameters:
- single-byte
PSTColMapAgeDstExit
(PST_STRUCT_CM_AGE_DSTFMT_PARM * pInputParms,
PST_STRUCT_CM_EXIT_COL_LIST * pSrcColList,
PST_STRUCT_CM_EXIT_COL_LIST * pDstColList)
- UTF-16
PSTColMapAgeDstWExit
(PST_STRUCT_CM_AGE_DSTFMT_WPARM * pInputParms,
PST_STRUCT_CM_WEXIT_COL_LIST * pSrcColList,
PST_STRUCT_CM_WEXIT_COL_LIST * pDstColList)
Parameters
When
an Optim process
calls a destination format exit routine, the process passes the following
parameters:
- pInputParms
- Pointer to PST_STRUCT_CM_AGE_DSTFMT_PARM (PST_STRUCT_CM_AGE_DSTFMT_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:
PST_CM_DSTFMT_TO_CHAR (PST_CMW_DSTFMT_TO_WCHAR),
PST_CM_DSTFMT_TO_INTEGER (PST_CMW_DSTFMT_TO_INTEGER),
PST_CM_DSTFMT_TO_TIMESTAMP (PST_CMW_DSTFMT_TO_TIMESTAMP),
PST_CM_DSTFMT_TO_SYB_DATETIME (PST_CMW_DSTFMT_TO_SYB_DATETIME), or
PST_CM_DSTFMT_TERMINATE (PST_CMW_DSTFMT_TERMINATE).
- pSrcColList
- Pointer to a PST_STRUCT_CM_EXIT_COL_LIST (PST_STRUCT_CM_WEXIT_COL_LIST).
This structure describes the source columns.
- pDstColList
- Pointer to a 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 destination 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 aged source
column is provided in the first parameter. However, the exit routine
can call this function to retrieve the data for different columns.
Formats
The
input date is in both a PST_C_TIMESTAMP and PST_C_SYB_DATETIME format.
The exit is directed to transform that date into one of the following
formats, based on the data type of the destination column.
- PST_C_CHAR_SZ
- CHAR and VARCHAR destination columns.
- PST_C_INTEGER_CHAR_SZ
- NUMERIC destination columns.
- PST_C_TIMESTAMP
- DB2® and Oracle
DATE/TIME columns.
- PST_C_SYB_DATETIME
- Sybase ASE DATETIME columns.
Processing
Typical
processing for the Destination Format 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).
- The exit receives the value of the source column
as specified in the Age Function defined in the Column Map. Optim applies
the Age Function before calling the Column Map exit and stores the
aged value in both the InputTimeStamp and InputSybaDateTime fields
in the header file.
- 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.
- After the destination value is generated, the exit
routine must format the value and place it in one of the fields in
the OutputValue union. The FuncCode field indicates
the field in the OutputValue union where the value must be
placed. The exit must return an appropriate code indicating the field
where the data is saved or instructing the process to skip the row
or abort.
- After the last data row is processed, Optim passes
a termination call to the exit routine, identified by a value of PST_CM_DSTFMT_TERMINATE
(PST_CMW_DSTFMT_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 Destination Format Exit routine can
abort processing:
- Process rows with skipped dates or invalid dates.
If you select either of these options in a process request, and the
source and destination columns have the same attributes, the source
column is copied unchanged to the destination column. If you do not
select either option, the row is rejected.
- Reject the row. Reject the row regardless of the
process options for skipped or invalid dates, based on specifications
in the exit routine.
- Abort the whole process, based on specifications
in the exit routine.
The exit routine passes a return code indicating
whether the conversion was successful 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 destination format exits:
PST_CM_DSTFMT_SUCCESS
(PST_CMW_DSTFMT_SUCCESS)
Destination column is assigned a value,
as specified in the FuncCode field of the first parameter passed
to the exit.
PST_CM_DSTFMT_SKIP
(PST_CMW_DSTFMT_SKIP)
If you do not select the option to Process
rows with skipped dates, the row is rejected. Otherwise,
the source data is copied to the target, as long as the source and
target are compatible. If not compatible, the row is rejected.
PST_CM_DSTFMT_COL_INVALID
(PST_CMW_DSTFMT_COL_INVALID)
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 target
are compatible. If not compatible, the row is rejected.
PST_CM_DSTFMT_REJECT_ROW
(PST_CMW_DSTFMT_REJECT_ROW)
Destination column cannot be assigned
a value. Reject (discard) the row.
PST_CM_DSTFMT_ABORT_PROCESS
(PST_CMW_DSTFMT_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.