B4504590 - Pricing Datamap Function and Cache and Workfile

Purpose of Document

The purpose of this document is to explain internal API SetPricingHistoryCacheFlag during Sales Order Entry or Sales Order Processing. However modifying any standard code is discouraged at any cost.

History:
This routine is implemented through enhancement <Bug 10875622>: PRICEHISTORY DATAMAP - SAR: 7500235, which was SOE performance project needs to modify the exisitng data decimal datamap and create new pricing history data map and other related functions in B4504590

Changes:

BSFN B4504590 is comprised of,

Source Module	Function Name	Description	Template Name	Usage
B4504590	CreatePricingCatCodesDatamap	Create Pricing Cat Codes Datamap	D4504590J	This function is to create Pricing Category Codes datamap PRICING_CATCODES_DATA_MAP in shared memory DATAMAPCDIST
B4504590	PricingCatCodesDatamapExist	Pricing Cat Codes Datamap Exist	D4504590I	to check whether there is existing datamap for Pricing Category Codes
B4504590	CreatePricingDatamapWrapper	Create Pricing Datamap Wrapper	D4504590F	to check the existence of PricingDecimal, PricingHistory and Pricing Category Codes Datamaps. If these datamaps exist, do not create them again but if datamap does not exist then create it again
B4504590	DestroyPricingDatamapWrapper	Destroy Pricing Datamap Wrapper	D4504590F	to destroy all the datamap created by CreatePricingDatamapWrapper by calling DestroyPricingDecimalDatamap, DestroyPricingHistoryDatamap and DestroyPricingCatCodesDatamap
B4504590	CreatePricingDecimalDatamap	Create Pricing Decimal Datamap	D4504590E	validates input mnJobNumber and create Pricing Decimal at shared memory (or data map) PRICING_DECIMAL_DATA_MAP
B4504590	DestroyPricingDecimalDatamap	Destroy Pricing Decimal Datamap	D4504590E	to destory any data map created through CreatePricingDecimalDatamap above
B4504590	SetPricingHistoryCacheFlag	Set Pricing History Cache Flag	D4504590B	to indicate whether to write cache or workfile. For this example, Cache stands for data structure of F40UI74 whereas workfile stands for a physical table F40UI74. Through this function cache PRICING_HISTORY_DATA_MAP is to be written at shared memory area DATAMAPCDIST
B4504590	PricingHistoryDatamapExist	Pricing History Datamap Exist	D4504590G	to check whether Pricing History Datamap does exit from DATAMAPCDIST for the name PRICING_HISTORY_DATA_MAP however this function does not return whether cPriceHistoryCacheFlag '1' or '2'
B4504590	CreatePricingHistoryDatamap	Create Pricing History Datamap	D4504590D	to create Datamap for Pricing History LPDSF40UI74DAO
B4504590	DestroyPricingHistoryDatamap	Destroy Pricing History Datamap	D4504590D	to destroy datamap PRICING_HISTORY_DATA_MAP created by CreatePricingHistoryDatamap above
B4504590	CreatePricingSharedDatamap	Create Pricing Shared Datamap	D4504590A	Obsolete: replaced by CreatePricingDatamapWrapper
B4504590	DestroyPricingSharedDatamap	Destroy Pricing Shared Datamap	D4504590A	Obsolete: replaced by DestroyPricingDatamapWrapper
	GetPricingDecimalDataMapHandle			This API has to be called in CreatePricingDatamapWrapper. In order to call this function correctly, calling function needs to call this function first to get handle of the datamap (DATAMAPCDIST). If the handle exists, then call get decimal to get the decimals for data dictionary item or currency
	GetDecimalFromDataMapDirect			to call this functoin correctly, calling function needs to call GetSharedDataMapHandleDirect first to get handle of the datamap if users like to use datamap logic to improve performance. If the handle is null, this function will call the external function to retrieve decimal as before
	GetPricingHistoryCacheFlag			to get Datamap for PRICE_HISTORY_CACHE_FLAG in DATAMAPCDIST which is written through API PutDataMapValueCDIST in SetPricingHistoryCacheFlag

Note: To understand relationship eash the sequence has changed

* Important Note:
* For users to use this performance functionality, the calling function must call
* either CreatePricingDatamapWrapper to create the Decimal, Price History and Category Codes datamap
* or call CreatePricingDecimalDatamap, CreatePricingHistoryDatamap or CreatePricingCatCodesDatamap individually.
*
* After the transaction is done, it is the calling function's responsibility
* to call DestroyPricingDatamapWrapper to terminate the data decimal, price history and category codes datamaps
* or call the DestoryPricingDecimaldatamap, DestroyPricingHistoryDatamap and DestroyPricingCatCodesDatamap individually.

Note that API-level functions below is not covered by this document,

B4205110 - SourceForSOESharedDataCacheAPIs (Source File, SOESharedData Cache APIs)
B4504500 - DataMapImplementationForCDIST (Data Map Implemenation for CDIST)
B4504580 - CacheAddressSpecificPrice (Cache Address Specific Price)

handles how to maintain datamap however this note does not cover routine for this. Above routines write shared memory DATAMAPCDIST directly where basic information for Pricing Category Code, Pricing History and Pricing Decimals and more.

And this function has be understood in the context of Master Business Function and Sales Order Workfiles, refer to

Document 1265902.1 - E1: BSFN: Master Business Function in EnterpriseOne
<Internal_Only>Document 1051653.1 - E1: 42: Work Files (F42UI*) in Sales Order Entry (P4210/P42101)</Internal_Only>

Before starts global cache and datamap can be understood as below,

DATAMAPCDIST: Shared memory name
PRICING_DECIMAL_DATA_MAP "PricingDecimals": Datamap name for Pricing Display Decimal (DD and/or Currency)
PRICING_HISTORY_DATA_MAP "PricingHistory": Datamap name for Pricing History
PRICE_HISTORY_CACHE_FLAG "PH": Datamap name whether to write Cache or Workfile
PRICING_CATCODES_DATA_MAP "PricingCatCodes": Datamap name for Pricing Category Codes
F40UI74DAO: Datamap for F40UI74

Business Functions which affects Sales Order Entry validation/defaulting through F4211FSBeginDoc and F4211FSEditLine routine:

1. B4504590 - CreatePricingCatCodesDatamap (Create Pricing Cat Codes Datamap)

Purpose: This function is to create Pricing Category Codes datamap PRICING_CATCODES_DATA_MAP in shared memory DATAMAPCDIST
Parameters:

Data Structure: D4504590J : Category Codes Datamap

Structure Member	Data Type	Req	I/O	Alias	Usage
mnJobnumber	MATH_NUMERIC	Y	I	JOBS	This parameter has to be determined by calling routine to store job specific data map and cache

Detail Routine:

1. Write log "Entering I4504590_CreatePricingCatCodesDatamap"
2. Check input mnJobnumber. If the value is zero, then set ER_ERROR with message "I4504590_CreatePricingCatCodesDatamap:Job Number missing."
3. mnJobnumber is not zero then create datamap with name PRICING_CATCODES_DATA_MAP through API CreateDataMapCDIST
4. If CreateDataMapCDIST failed set ER_ERROR with log message "I4504590_CreatePricingCatCodesDatamap Failed"

Error Code: N/A

2. B4504590 - PricingCatCodesDatamapExist (Pricing Cat Codes Datamap Exist)

Purpose: This function is to check whether there is existing datamap for Pricing Category Codes
Parameters:

Data Structure: D4504590I : Get Pricing Cat Codes Datamap Handle

Structure Member	Data Type	Req	I/O	Alias	Usage
mnJobNumber	MATH_NUMERIC	Y	I	JOBS	mnJobnumber assigned by calling routine this is unique key value to determine existence of datamap for Pricing Category Codes
cPricingCatCodesDatamapExist	JCHAR		O	EV01	0 - Does not exist 1 - Pricing Category Code Datamap Exist

Detail Routine:

1. Record start of routine with "Entering PricingCatCodesDatamapExist"
2. Call API GetPricingCatCodesDataMapHandle to determine whether datamap does exist
3. If GetPricingCatCodesDataMapHandle succeed then set 1 for cPricingCatCodesDatamapExist

Error Code: N/A

3. B4504590 - CreatePricingDatamapWrapper (Create Pricing Datamap Wrapper)

Purpose: This function is to check the existence of PricingDecimal, PricingHistory and Pricing Category Codes Datamaps. If these datamaps exist, do not create them again but if datamap does not exist then create it again.
Parameters:

Data Structure: D4504590F : Create Pricing Decimal Datamap Wrapper

Structure Member	Data Type	Req	I/O	Alias	Usage
mnJobnumber	MATH_NUMERIC	Y	I	JOBS	The mnJobnumber has to be specified from calling routine.

Detail Routine:

1. Check for the existence of PricingDecimal through API GetPricingDecimalDataMapHandle.

2. If these datamaps exist, do not create them again by calling BSFN CreatePricingDecimalDatamap

3. If Pricing Decimal Datamap is created then continue to create Pricing History Datamap by calling BSFN PricingHistoryDatamapExist (note: this gets called by CALLBFRET - Call Object Lite)

4. If PricingHistoryDatamapExist did not return success, then create Pricing History Datamap by calling CreatePricingHistoryDatamap
5. If PricingHistoryDatamapExist fails then set ER_WARNING to indicate the price history data map exists and SetPricingHistoryCacheFlag can be called to enable cache or workfile

6. Call PricingCatCodesDatamapExist to check whether there is existing Pricing Category Codes

7. If datamap exists, then set ER_WARNING to indicate the category codes data map exists
8. If datamap does not exist, then call CreatePricingCatCodesDatamap to create Pricing Category Codes Datamap

Error Code: N/A
Others: This routine repeats CreatePricingDecimalDatamap, CreatePricingHistoryDatamap and CreatePricingCatCodesDatamap

4. B4504590 - DestroyPricingDatamapWrapper (Destroy Pricing Datamap Wrapper)

Purpose: This function is to destroy all the datamap created by CreatePricingDatamapWrapper by calling DestroyPricingDecimalDatamap, DestroyPricingHistoryDatamap and DestroyPricingCatCodesDatamap
Parameters:

Data Structure: D4504590F : Create Pricing Decimal Datamap Wrapper (Same with Data Structure for B4504590 - CreatePricingDatamapWrapper)

Detail Routine:

1. Call DestroyPricingDecimalDatamap
2. Call DestroyPricingHistoryDatamap
3. Call DestroyPricingCatCodesDatamap
4. If any of above 3 functions fails then set ER_ERROR

Error Code: N/A
Others: Refer DestroyPricingDecimalDatamap, DestroyPricingHistoryDatamap and DestroyPricingCatCodesDatamap

5. B4504590 - CreatePricingDecimalDatamap (Create Pricing Decimal Datamap)

Purpose: This function validates input mnJobNumber and create Pricing Decimal at shared memory (or data map) PRICING_DECIMAL_DATA_MAP
Parameters:

Data Structure: D4504590E : Data Decimal Datamap

Structure Member	Data Type	Req	I/O	Alias	Usage
mnJobNumber	MATH_NUMERIC	Y	I	JOBS	To store/retrieve Pricing Decimal Datamp (one for Data Dictionary and the other for Currency Decimal)

Detail Routine:

1. Check input mnJobnumber. If the value is zero set ERROR with message "I4504590_CreatePricingDecimalDatamap:Job Number missing."
2. If mnJobnumber is not zero then call API CreateDataMapCDIST to create Data Map
3. If 2 fails then set ERROR with message "I4504590_CreatePricingDecimalDatamap Failed"

Error Code: N/A. Direct writing to jdedebug.log
Others: This routine has to be understood in the context of whole sales order entry and capture jdedebug (callobject kernel) log for further debugging

6. B4504590 - DestroyPricingDecimalDatamap (Destroy Pricing Decimal Datamap)

Purpose: This function is to destory any data map created through CreatePricingDecimalDatamap above.
Parameters:

Data Structure: D4504590E : Data Decimal Datamap (Same with Data Structure for B4504590 - CreatePricingDecimalDatamap)

Detail Routine:

1. Write log "Entering I4504590_DestroyPricingDecimalDatamap"
2. Check whether input mnJobnumber is zero, then set ER_ERROR with message "I4504590_DestroyPricingDecimalDatamap:Job Number missing."
3. If mnJobNumber is not zero, get Datamap from PRICING_DECIMAL_DATA_MAP through API GetDataMapHandleCDIST
4. If it fails to get data map the set ER_ERROR with message "I4504590_DestroyPricingDecimalDatamap Get handle Failed"
5. If GetDataMapHandleCDIST succeed,

6. then Removes all key/value pairs from the DataMap via API ClearDataMapCDIST
7. Destroy the input DataMap. All key/value pairs are removed from the DataMap via the ClearDataMapCDIST before the DataMap is destroyed via API DestroyDataMapCDIST
8. Call external bsfn B4504580 - CacheAddressSpecificPrice which terminated Address Specific Price cache

Error Code: N/A. Either set ER_ERROR and return or write direct message in log

7. B4504590 - SetPricingHistoryCacheFlag (Set Pricing History Cache Flag)

Purpose: This function is to indicate whether to write cache or workfile. For this example, Cache stands for data structure of F40UI74 whereas workfile stands for a physical table F40UI74. Through this function cache PRICING_HISTORY_DATA_MAP is to be written at shared memory area DATAMAPCDIST
Parameters:

Data Structure: D4504590B : Set Pricing History Cache Flag

Structure Member Name	Data Type	Req	I/O	Alias	Usage
mnJobNumber	MATH_NUMERIC	Y	I	JOBS	mnJobnumber is determined by calling routine or return value from existence checking
cPriceHistoryCacheFlag	JCHAR			EV01	This flag is to determine whether to write cache of F40UI74 or work file 1 - Write Workfile F40UI74 2 - Cache

Detail Routine:

1. Record the start of routine "Entering SetPricingHistoryCacheFlag"
2. Check input mnJobnumber. If the value is zero set ER_ERROR and write log "SetPricingHistoryCacheFlag:Job Number missing."
3. If mnJobnumber is not zero get datamap from DATAMAPCDIST through API GetDataMapHandleCDIST with name PRICING_HISTORY_DATA_MAP
4. If GetDataMapHandleCDIST fails then record it "SetPricingHistoryCacheFlag: Get handle Failed" and set ER_ERROR
5. If GetDataMapHandleCDIST succeed then call API PutDataMapValueCDIST to instruct whether to write workfile or cache with parameter cPriceHistoryCacheFlag
6. If it fails to update then set ER_ERROR with message "B4504590: Put value to PricingHistoryDatamap failed."

Error Code: N/A
Others: This flag is inherited by Sales Order Master Business function B4200310/B4200311 (parameter name cCMWriteToWFFlag). In general, when sales order master business function is called by Interactive application (e.g., P4210/P42101 - Sales Order Entry) the flag is to be '2 - Write Cache' whereas same function gets called by batch job (e.g., R47011 - Inbound Purchase Order Processing) then the value is to be '1'. This can affect the performance of application significantly so do not modify it and Oracle does not bear any responsibility on result you may get owing to change you are to make.

8. B4504590 - PricingHistoryDatamapExist (Pricing History Datamap Exist)

Purpose: This function is to check whether Pricing History Datamap does exit from DATAMAPCDIST for the name PRICING_HISTORY_DATA_MAP however this function does not return whether cPriceHistoryCacheFlag '1' or '2'.
Parameters:

Data Structure: D4504590G : Get Pricing History Datamap Handle

Structure Member Name	Data Type	Req	I/O	Alias	Usage
mnJobNumber	MATH_NUMERIC	Y	I	JOBS	This parameter is determined by calling routine in a transaction
cPriceHistoryDatamapExist	JCHAR			EV01	0 - Not exist 1 - Datamap exists

Detail Routine:

1. Record the start of routine "Entering PricingHistoryDatamapExist"
2. If input mnJobnumber is zero set ER_ERROR and record it "PricingHistoryDataMapExist:Job Number missing."
3. If mnJobnumber is not zero then get PRICING_HISTORY_DATA_MAP from DATAMAPCDIST through API GetDataMapHandleCDIST
4. GetDataMapHandleCDIST success then set '1' for parameter cPriceHistoryDatamapExist (else, '0')

Error Code: N/A

9. B4504590 - CreatePricingHistoryDatamap (Create Pricing History Datamap)

Purpose: This function is to create Datamap for Pricing History LPDSF40UI74DAO
Parameters:

Data Structure: D4504590D : Price History Datamap

Structure Member	Data Type	Req	I/O	Alias	Usage
mnJobnumber	MATH_NUMERIC	Y	I	JOBS	Based on Job Number from calling routine to create Price History datamap

Detail Routine:

1. Write Trace log "I4504590_CreatePricingHistoryDatamap"
2. Check input mnJobnumber. If this vlaue is zero then set ER_ERROR with message "I4504590_CreatePricingHistoryDatamap:Job Number missing."
3. If mnJobnumber is not zero then create datamap PRICING_HISTORY_DATA_MAP through API CreateDataMapCDIST
4. If CreateDataMapCDIST fails to create datamap then set ER_ERROR with message "I4504590_CreatePricingHistoryDatamap Failed"

Error Code: N/A

10. B4504590 - DestroyPricingHistoryDatamap (Destroy Pricing History Datamap)

Purpose: This function is to destroy datamap PRICING_HISTORY_DATA_MAP created by CreatePricingHistoryDatamap above
Parameters:

Data Structure: D4504590D : Price History Datamap (Same with data structure for BSFN B4504590 - CreatePricingHistoryDatamap)

Detail Routine:

1. Write message "Entering I4504590_DestroyPricingHistoryDatamap"
2. Check input mnJobnumber. If the value is zero set ER_ERROR with message "I4504590_DestroyPricingHistoryDatamap:Job Number missing."
3. mnJobnumber is valid then Terminate / Close the Price Hitory Cache / Work-file prior to destroying the related datamap
4. Call F40UI74_Init against &lpdsF40UI74DAO
5. Call F40UI74_Terminate to terminate it
6. Call API GetDataMapHandleCDIST to check datamap PRICING_HISTORY_DATA_MAP

7. If GetDataMapHandleCDIST fails then set ER_ERROR with message "I4504590_DestroyPricingHistoryDatamap: Get handle Failed"
8. If GetDataMapHandleCDIST succeed then call ClearDataMapCDIST to Removes all key/value pairs from the DataMap
9. If GetDataMapHandleCDIST succeed then call DestroyDataMapCDIST to Destroy the input DataMap. All key/value pairs are removed from the DataMap via the ClearDataMapCDIST before the DataMap is destroyed.

Error Code: N/A

Below is to describe 3 important internal functions (or APIs) which is to be called in B4504590,

11. GetPricingDecimalDataMapHandle

Purpose: This API has to be called in CreatePricingDatamapWrapper. In order to call this function correctly, calling function needs to call this function first to get handle of the datamap (DATAMAPCDIST). If the handle exists, then call get decimal to get the decimals for data dictionary item or currency.
Parameters:

Data Structure: N/A

Detail Routine:

1. Record starts of API "Entering GetPricingDecimalDataMapHandle"
2. If the mnJobnumber from pointer *lphPricingDecimalDataMap is zero then set ER_ERROR with message "GetSharedDataMapHandleDirect:Job Number missing."
3. If mnJobnumber is not zero from DATAMAPCDIST, then call API GetDataMapHandleCDIST using cache name PRICING_DECIMAL_DATA_MAP
4. If GetDataMapHandleCDIST fails then record "B4504590: GetPricingDecimalDataMapHandle failed."

Error Code: N/A
Others: In order to call this function correctly, calling function needs to call this function first to get handle of the datamap. If it exists. Then, it can call the get decimal to get the decimals for data dictionary item or currency

12. GetDecimalFromDataMapDirect

Purpose: In order to call this function correctly, calling function needs to call GetSharedDataMapHandleDirect first to get handle of the datamap if users like to use datamap logic to improve performance. If the handle is null, this function will call the external function to retrieve decimal as before
Parameters:

Data Structure: N/A

Detail Routine:

1. Record the start point of this API "Entering GetDecimalFromDataMapDirect"
2. Check hPricingDataMap from shared memory DATAMAPCDIST and if the value is not NULL then call API GetDataMapValueCDIST to have DisplayDecimals. If there is existing records then which skips to call external business function to get Display Decimal Point from Data Dictionary Item and Currency specific display decimal. So this routine is to improve performance to minimize external BSFN calling
3. If GetDataMapValueCDIST fails to get cache then call B9800420 - GetDataDictionaryDefinition to get display decimal (GET_DD_ITEM_DECIMAL)
4. In case the request is on Currency then call B0000129 - RetrieveCurrencyDecimals to get Currency Decimal (GET_CURRENCY_DECIMAL)
5. If the value is returned either through 3 or 4 then call API PutDataMapValueCDIST to record DD_ITEM_DECIMAL and/or CURRENCY_DECIMAL
6. If PutDataMapValueCDIST fails then set ER_ERROR and record "B4504590: Put value to PricingSharedDatamap failed."
7. If 3 or 4 fails then set ER_ERROR and record it "CallObject to get DD or currency decimal failed."

Error Code: N/A

13. GetPricingHistoryCacheFlag

Purpose: This API is to get Datamap for PRICE_HISTORY_CACHE_FLAG in DATAMAPCDIST which is written through API PutDataMapValueCDIST in SetPricingHistoryCacheFlag
Parameters:

Data Structure: N/A

Detail Routine:

1. Record calling of this API "Entering GetPricingHistoryCacheFlag"
2. Check mnJobnumber in datamap and the value is zero then set ER_ERROR "GetPricingHistoryCacheFlag:Job Number missing."
3. If mnJobnumber is not zero then read PRICING_HISTORY_DATA_MAP through API GetDataMapHandleCDIST
4. If GetDataMapHandleCDIST fails then set ER_ERROR with message "GetPricingHistoryCacheFlag Get handle Failed"
5. If GetDataMapHandleCDIST succeeds then get datamap for PRICE_HISTORY_CACHE_FLAG through API GetDataMapValueCDIST, which returns cPriceHistoryCacheFlag (1- write workfile F40UI74, 2 - write cache)

Error Code: N/A

Note: this document is created based on EnterpriseOne 9.0 release.