Using Business Functions

This chapter provides an overview of business functions (BSFNs) and transaction master business functions, and discusses how to:

• Create transaction master business functions.

• Implement transaction master business functions.

• Work with master file business functions.

• Work with business functions.

• Work with Business Function Builder.

• Work with business function documentation.

Understanding Business Functions

You can use business functions to enhance JD Edwards EnterpriseOne applications by grouping related business logic. Journal Entry Transactions, Calculating Depreciation, and Sales Order Transactions are examples of business functions.

You can create business functions using one of these methods:

• Event rules scripting language.

  The business functions that you create using the event rules scripting language are referred to as Business Function Event Rules (also called Named Event Rules (NERs)). If possible, use NERs for the business functions. In some instances, C business functions might better suit your needs.

• C programming code.

  JD Edwards EnterpriseOne software creates a shell into which you insert logic using C. You use C business functions mainly for caching, but they can also be used for these objects:

  • Batch error level messaging.

  • Large functions.

    C business functions work better for large functions (as determined by the group). If you have a large function, you can break the code up into smaller individual functions and call them from the larger function.

  • Functions for which performance is critical.

  • Complex select statements.

After you create business functions, you can attach them to JD Edwards EnterpriseOne applications to provide additional power, flexibility, and control. You can attach tables and functions to a business function. You must add related tables and functions to the business function object to generate the code for the source and header files. Because the source code for NERs is generated into C, you use the same procedures for debugging both C and NERs.

This section discusses:

• The components of a business function.

• How distributed business functions work.

• C business functions.

• Business function event rules.

Components of a Business Function

The process of creating a business function produces several components. The Object Management Workbench (OMW) is the entry point for the tools that create the components. These components are created:

The DLLs are divided into categories. This distribution provides better separation between the major functional groups, such as tools, financials, manufacturing, distribution, and so on. Most business functions are organized into a consolidated DLL based on their system code. For example, a financials business function with system code 01 belongs in CFIN.DLL.

Follow these guidelines when you add or modify business functions:

• Create a custom parent DLL unless you are adding a JD Edwards EnterpriseOne business function.

  Assign a parent DLL to the business functions based on the system code defined in UDC table H92/PL. If no DLL is assigned for the system code in which the business function is created, use CCUSTOM, where CUSTOM is the 7-character version of the company name. You can change the DLL after the business function is created.

• When you write business function code, ensure that all calls to other business functions use the jdeCallObject protocol.

  Linker errors might occur if you do not use jdeCallObject and you attempt to call a business function in a different DLL. A linker error prevents the function call from working.

  Note. If you change the DLL for a business function, go to C:\B9\System\Bin32\BusBuild.exe, select the old DLL file where the business function was, and select Build from the Build menu to rebuild the file.

This table lists some of the DLLs for which Business Function Builder manages the builds:

Note. Do not use table triggers for regular business functions.

How Distributed Business Functions Work

OMW manages these three main components that make up NERs or business functions:

• Object Name

  The Object Name is the actual source file.

• Function Name

  The name of the business function or event rule.

  Note. Any business function, whether it uses C or NERs as its source language, must have a defined data structure to send or receive parameters to or from applications. You can create a DSTR data structure object, or select an existing object type to work with in OMW. You can also create data structures for text substitution messages. Additionally, you can attach notes, such as an explanation of use, to any data structure or data item within the structure.

• DLL Name

  The DLL is a dynamic link library.

When a business function is called, the Object Configuration Manager (OCM) determines where to run the business function. After the system maps a business function to a server, calls from that business function cannot be mapped back to the workstation.

This flowchart illustrates how distributed business functions work:

Distributed business function

C Business Functions

JD Edwards EnterpriseOne software contains two types of business functions: NERs and C business functions. C business functions are written in C programming language and are used to perform functions that are not available in NERs. C business functions include both a header file (.h) and a source file (.c).

Header File Sections

This table describes the major sections of a business function header file:

Example: Business Function Header File

Assume that Business Function Design created this header file. This file contains only the required components in a business function header file:

Header File Begin
/*****************************************************************************
* Header File: B99TEST.h
*
* Description: test Header File
*
* History:
*  Date Programmer SAR# - Description
*  ---------- ---------- ------------------------------------------
* Author 10/14/2003 DEMO Unknown - Created
*
*
* Copyright (c) 1994 Oracle 2003
*
* This unpublished material is proprietary to Oracle.
* All rights reserved. The methods and techniques described
* herein are considered trade secrets and/or confidential. Reproduction
* or distribution, in whole or in part, is forbidden except by express
* written permission of Oracle.
****************************************************************************/
#ifndef __B99TEST_H
#define __B99TEST_H
/*****************************************************************************
* Table Header Inclusions
****************************************************************************/
/*****************************************************************************
* External Business Function Header Inclusions
****************************************************************************/
/*****************************************************************************
* Global Definitions
****************************************************************************/
/*****************************************************************************
* Structure Definitions
****************************************************************************/
/*****************************************************************************
* DS Template Type Definitions
****************************************************************************/
/*****************************************
* TYPEDEF for Data Structure
* Template Name: Test Data Structure
* Template ID: D59TEST
* Generated: Tue Oct 14 16:53:08 2003
*
* DO NOT EDIT THE FOLLOWING TYPEDEF
* To make modifications, use the EnterpriseOne Data Structure
* Tool to Generate a revised version, and paste from
* the clipboard.
*
**************************************/
#ifndef DATASTRUCTURE_D59TEST
#define DATASTRUCTURE_D59TEST
typedef struct tagDSD59TEST
{
 JCHAR  cEverestEventPoint01;
 JCHAR  szNameAlpha[41];
 MATH_NUMERIC mnAmountField;
} DSD59TEST, *LPDSD59TEST;
#define IDERRcEverestEventPoint01_1  1L
#define IDERRszNameAlpha_2   2L
#define IDERRmnAmountField_3   3L
#endif
/*****************************************************************************
* Source Preprocessor Definitions
****************************************************************************/
#if defined (JDEBFRTN)
 #undef JDEBFRTN
#endif
#if defined (WIN32)
 #if defined (WIN32)
 #define JDEBFRTN(r) __declspec(dllexport) r
 #else
 #define JDEBFRTN(r) __declspec(dllimport) r
 #endif
#else
 #define JDEBFRTN(r) r
#endif
/*****************************************************************************
* Business Function Prototypes
****************************************************************************/
JDEBFRTN(ID) JDEBFWINAPI F0101Test  
 (LPBHVRCOM lpBhvrCom, LPVOID lpVoid, LPDSD0100018 lpDS);
/*****************************************************************************
* Internal Function Prototypes
****************************************************************************/
#endif /* __B99TEST_H */
Header File End

This table describes the contents of the various lines in the header file:

Source File Sections

OMW builds a template for the business function source file. The business function source file consists of several major sections, as described in this table:

Example: Business Function Source File

Assume that Business Function Design created this source file called Check for In Add Mode. It contains the minimum components required in a business function source file. The source code in the Main Processing section is entered manually, and varies from business function to business function. All other components are generated by Business Function Design.

#include <jde.h>

#define b98sa001_c

/*****************************************************************************
 * Source File: B98SA001.c
 *
 * Description: Check for In Add Mode Source File
 ****************************************************************************/
 **************************************************************************/

#include <b98sa001.h>

/**************************************************************************
 * Business Function: CheckForInAddMode
 *
 *  Description: Check for In Add Mode
 *
 *   Parameters:
 *   LPBHVRCOM   lpBhvrCom Business Function Communications
 *   LPVOID    lpVoid  Void Parameter - DO NOT USE!
 *   LPDSD98SA0011   lpDS   Parameter Data Structure Pointer 
 *
 *************************************************************************/

JDEBFRTN(ID) JDEBFWINAPI CheckForInAddMode (LPBHVRCOM lpBhvrCom, LPVOID lpVoid, LPDSD98SA0011 lpDS) 
{
 /************************************************************************
 * Variable declarations
 ************************************************************************/

 /************************************************************************
 * Declare structures
 ************************************************************************/

 /************************************************************************
 * Declare pointers
 ************************************************************************/

 /************************************************************************
 * Check for NULL pointers
 ************************************************************************/
 if ((lpBhvrCom == NULL) ||
  (lpVoid == NULL) ||
  (lpDS  == NULL))
 {
  jdeSetGBRError (lpBhvrCom, lpVoid, (ID) 0, _J("4363"));
  return CONTINUE_GBR;
 }

 /************************************************************************
 * Set pointers
 ************************************************************************/

 /************************************************************************
 * Main Processing
 ************************************************************************/

	if (lpBhvrCom->iBobMode == BOB_MODE_ADD)
	{
		 lpDS->cEverestEventPoint01 = _J('1');
	}
	else

	{
		 lpDS->cEverestEventPoint01 = _J('0');
	}
	
 return (BHVR_SUCCESS);
}

/* Internal function comment block */
/**************************************************************************
 * Function: Ixxxxxxx_a // Replace "xxxxxxx" with source file number
 *       // and "a" with the function name
 *  Notes:
 *
 * Returns:
 *
 * Parameters:
 **************************************************************************/

The lines that appear in the source file are described in this table:

Use the MATH_NUMERIC data type exclusively to represent all numeric values in JD Edwards EnterpriseOne software. The values of all numeric fields on a form or batch process are communicated to business functions in the form of pointers to MATH_NUMERIC data structures. MATH_NUMERIC is used as a data dictionary (DD) data type.

Business Function Event Rules

A NER is a business function object for which the source language is event rules instead of C. You create a NER using the event rules scripting language. This scripting language is platform-independent and is stored in a database as a JD Edwards EnterpriseOne software object. NERs are modular. That is, they can be reused in multiple places by multiple programs. This modularity reduces rework and enables you to reuse code.

Not all chunks of code should be packaged in a business function module. For example, when code is so specific that it applies only to a particular program, and it is not reused by any other programs, you should leave it in one place instead of packaging it in a business function. You can attach all the logic on a hidden control (Button Clicked event) and use a system function to process the logic as needed.

An example of a NER is N3201030. This business function creates generic text and Work Order detail records (for the F4802 table) for a configured work order. Based on the structure of the sales order in the F3296 table, the configured segments for the item on the passed work order and all lower level segments are included in the generic text.

This example illustrates the function as it appears in Event Rules Design:

Named Event Rule Begin
//
// Convert the related sales order number into a math numeric. If that fails
// exit the function
//
String, Convert String to Numeric
If VA evt_cErrorCode is equal to "1"
//
// Validate that the work order item is a configured item.
//
F4102 Get Item Manufacturing Information
If VA evt_cStockingType is not equal to "C"
 And BF cSsuppressErrorMessages is not equal to "1"
BF szErrorMessageID = "3743"
Else
BF szErrorMessageID = " "
//
// Delete all existing "A" records from F4802 for this work order.
//
VA evt_cWODetailRecordType = "A"
F4802.Delete
F4802.Close
//
// Get the segment delimiter from configurator constants.
//
F3293 Get Configurator Constant Row
If VA evt_cSegmentDelimiter is less than or equal to <Blank>
VA evt_cSegmentDelimiter - /
End If
//
F3296.Open
F3296.Select
If SV File_IO_Status     is equal to CO SUCCESS
F3296.FetchNext
//
// Retrieve the F3296 record of the work order item. and determine its key
// sequence by parsing ATSQ looking for the last occurrence of "1". The substring
// of ATSQ to this point becomes the key for finding the lower level configured
// strings
//
If VA evt_mnCurrentSOLine is equal to BF mnRelatedSalesOrderLineNumber
// Get the corresponding record from F32943. Process the results of that fetch
// through B3200600 to add the parent work order configuration to the work order
// generic text.
F32943.FetchSingle
If SV File_IO_Status   is equal to CO SUCCESS
VA evt_szConfiguredString = concat([VA evt_ConfiguredStringSegment01],
[VA evt_ConfiguredStringSegment02])
Confg String Format Segments Cache
End If
//
// Find the last level in ATSQ that is not "00". Note that the first three
// characters represent the SO Line Number to the left of the decimal.
Example:
// SO Line 13.001 will have the ATSQ characters "013". Each configured item can have
// 99 lower-level P-Rule items and a total of ten levels. Therefore every pair
// thereafter is tested.
//
VA evt_mnSequencePosition - 1
While VA evt_mnSequencePosition is less than "23"
And VA evt_szCharacterPair is not equal to "00"
VA evt_mnSequencePosition - [VA evt_mnSequencePosition] + 2
VA evt_szCharacterPair = substr([VA evt_szTempATSQ],[VA evt_mnSequencePostion],2)
End While
VA evt_szParentATSQ = substr([VA evt_szTempATSQ],0,[VA evt_mnSequencePosition])
//
// For each record in F3296 for the related sales order, find those with the same
// key substring of ATSQ. Retrieve the associated record from F32943 if
// available and pass the configured string to N3200600 for addition to the work
// order generic text.
//
F3296.FetchNext
Wile SV File_IO_Status  is equal to CO SUCCESS
VA evt_szChildATSQ = substr([VA evt_szTempATSQ],0,[VA evt_mnSequencePosition]}
If VA evt_szChildATSQ is equal to VA evt_szParentATSQ
F32943.FetchSingle
If SV File_IO_Status   is equal to CO SUCCESS
VA evt_szCongifuredString = concat([VA evt_ConfiguredStringSegment01],
[VA evt_ConfiguredStringSegment02])
Confg String Format Segments Cache
End If
End If
F3296.FetchNext
End Whil
F32943.Close
//
// Unload segments cache into the work order generic text. B3200600 Mode 6
Confg String Format Segments Cache
//
End If
End If
F3296.Close
//
End If
Else
// The related sales order number is invalid. Return an error.
If BF cSuppressErrorMessages is not equal to "1"
Set NER Error ("0002", BF SzRelatedSalesOrderNumber)
End If
End Ir
Named Event Rule End

Understanding Transaction Master Business Functions

Transaction master business functions provide a common set of functions that contain all of the necessary default values and editing for a transaction table in which records depend on each other. Transaction master business functions contain logic that ensures the integrity of the transaction being inserted, updated, or deleted from the database. Event flow breaks up logic. You use cache APIs to store records that are being processed. You should consider using a transaction master business function in these situations:

• You accept transaction file records from a non-JD Edwards EnterpriseOne source.

• Multiple applications update the same transaction file.

These transaction tables are examples of candidates for transaction master business functions:

• The F0911 table accepts updates across application suites, as well as external sources.

• The F06116 table accepts updates from batch, interactive, and external sources.

A master business function (MBF) can be called from several different applications. Rather than duplicating the processing options for the MBF on each application, you typically create a separate processing option template for these processing options. You can use interactive versions to set up different versions of the MBF processing options. Various calling programs then pass the version name to the version parameter of BeginDoc.

From within BeginDoc, the business function AllocatePOVersionData can be called to retrieve the processing options by version name. The processing options needed by other modules can be written to the header cache and accessed later, rather than calling AllocatePOVersionData multiple times.

The cache structure stores all lines of the transaction. Transaction lines are written to the cache after they have been edited. The EndDoc module then reads the cache to update the database.

This table describes the components of the header section:

This table explains the fields:

This table describes the components of the detail section:

This table explains the fields:

Building Transaction Master Business Functions

This section provides an overview of building transaction master business functions, and discusses the component used to build such a business function:

• Begin document

• Edit line

• Edit document

• End document

• Clear cache

• Cancel document

Understanding Building Transaction Master Business Functions

These flowcharts illustrate how transaction master business functions are built.

First, you create the individual business functions using several basic components:

Building transaction master business functions

Next, you combine the business functions into a DLL:

Combining business functions into a .DLL

You typically use these basic components to create a master business function as described by this table:

Begin Document

Begin Document has this format:

FxxxxxBeginDocument

The Begin Document component performs these tasks:

• Inserts default information and edits information in the header, including data dictionary defaults and UDC editing.

• Fetches information from the database, if necessary, to ensure that the selected document action can take place.

• Validates and processes information that is common to all records.

• Writes the record to header cache if no errors exist.

• Contains all header cache information that is common to all detail records. This improves performance by eliminating the need to use all the detail records to perform the same validations and table I/O.

• Updates the header cache with the new information when information in the header fields changes and Begin Document has previously been called.

Special Logic or Processing Required

On the initial call, the function assigns the job number. To retrieve the job number, this function calls X0010GetNextNumber with a system code of 00 and an index number of 04. If called again, Begin Document passes the job number that was previously assigned; therefore, it does not need to assign another job number.

Hook Up Tips

Keep these tips in mind when calling Begin Document:

• You must call a function at least once before calling Edit Line.

• If errors occur during validation of the header field when the function is called, call the function again to verify that errors have been cleared before calling Edit Line.

• If this function might be called multiple times from different events, include it on a hidden button on an application to reduce duplicate code and ensure consistency. This button might then be called from focus on grid because the user is then adding or deleting detail records, and is finished adding header information. In case of a Copy in which the user does not use the grid, this button might also be called on OK button.

• Calling a button from an asynchronous event breaks the asynchronous flow and forces the button to be processed in synchronous mode (inline).

Common Parameters

This table describes the common parameters for Begin Document:

Application-Specific Parameters

Application-specific parameters must perform these tasks:

• List the fields that are needed to process header-level information.

• List any work fields that are needed to perform edits.

• List all POs that are needed to process header-level information.

Edit Line

Edit Line has this format:

FxxxxxEditLine 

The Edit Line component performs these tasks:

• Validates all user input, performs calculations, and retrieves default information.

  Edit Line is normally called for every record that is fetched. It performs the edits for that one record in the file.

• Reads header cache records for default values.

• On an ADD, enters default information in blank columns, such as address book information.

  The default values might come from any of these objects:

  • Another column in the line.

  • A process performed on a column sent in the line.

  • A PO.

  • A saved value from the header record that was determined in the Begin Document module.

  • A DD default value.

• Edits columns for correct information.

  This includes interdependent editing between columns. Also performs UDC and DD edits.

• Writes record to the detail cache if no errors occurred.

  If the record already exists in the work file, the line in the work file will be retrieved and updated with the changes. If a record is deleted from the grid in direct mode, and the record does not exist in the database, the record will be removed from the detail cache. If the record exists in the database, the action code for the record will be changed to delete, and the record will be stored in the detail cache until file processing in End Doc.

Special Logic or Processing Required

Depending on the type of document being processed, different editing and inserting of default values takes place. An example would be vouchers and invoices processed through the journal entry MBF. The tax calculator is only called for vouchers. Depending on the event processing required, the process edit flag determines the editing that occurs. For example, in an interactive program, when the Grid Record is Fetched event runs, Partial Edits might be performed to retrieve descriptions, default values, and so on. When the Row is Exited and Changed event runs, Full Edits might be performed to validate all user input.

Typical Uses and Hookup

In interactive applications, Edit Line is typically called on Grid Record is Fetched or Row is Exited and Change (Asynch). In batch applications, Edit Line is typically called in the Do section of the group, columnar, or tabular section.

Common Parameters

This table describes the common parameters for Edit Line:

Edit Document

The Edit Document component performs these tasks:

• Reads cache records if multiple line editing is required.

• Reads header cache record if header information is needed.

• Performs cross-dependency edits involving multiple lines in a document. For example, Edit Document processes all records to ensure that percentages total 100 percent, and it ensures that the last record does not contain certain information.

Special Logic or Processing Required

Depending on the type of document that you are processing, different logic is executed. For example, vouchers and invoices are processed through the journal entry edit object, although the balancing is different for these document types.

Hook Up Tips

Edit Document is typically used in this fashion:

• Call the function at least once after calling Edit Line and before End Document.

• If errors occur during validation, call the function again to verify that errors have been cleared before calling End Document.

• Call this function on the OK Button Clicked event so that, if errors do occur, they are corrected before the user exits the application.

Common Parameters

This table describes the common parameters for Edit Document:

Application-Specific Parameters

Because all records have been added in Begin Document or Edit Line, and because any information needed to process the entire document is in cache, few parameters are needed in this function.

End Document

End Document has this format:

FxxxxxEndDocument

The End Document component performs these tasks:

• Assigns a next number to the document.

  For vouchers, you should do this before calling journal entry edit object, but not before the voucher has been balanced and is ready to be added to the database. By placing this module on the before add/delete/update events, the document passes all edits before running this event.

• Reads cache records.

• On an ADD, writes new rows to the table.

• On a CHG, retrieves and updates existing rows.

• On a DEL, deletes rows from the table.

• Adds information and updates associated tables.

  For example, it adds and updates these objects:

  • Manual checks associated with vouchers.

  • Address Book vouchered YTD columns in Address Book.

  • Address, phones, and who's who information for Address Book.

  • Batch header.

• Clears the cache for that document and any work fields after all updates are completed successfully.

• Summarizes documents, if designated in a processing option, as it writes to the database.

• Reads work file through an alternate means and writes the records at a control break.

• Performs currency conversion.

Hook-Up Tips

This function is typically called on OK button Post Button Clicked, and it is hooked up Asynch. In the C code, after the insert or update to the database is successful, call Clear Cache to clear the cache.

Common Parameters

This table describes the common parameters for End Document:

Application-Specific Parameters

Use application-specific parameters in End Document to perform these tasks:

• List the fields that are needed to process update or writes, such as Time and Date Stamp fields.

• List any work fields that are needed to perform updates or writes.

• List all POs that are needed to process updates or writes.

Clear Cache

Clear Cache has this format:

FxxxxxClearCache

The Clear Cache component removes the records from the header and detail cache.

Special Logic or Processing Required

If a unique cache name is selected as the naming convention for the cache (Dxxxxxxxx[Job Number]), then use the cache API jdeCacheTerminateAll to destroy the cache.

Common Parameters

This table describes the common parameters for Clear Cache:

Cancel Document

Cancel Document has this format:

FxxxxxxCancelDoc

The optional Cancel Document component is used primarily with the Cancel button to close files, clear the cache, and so on. Cancel Document is an application-specific function that provides basic function cleanup.

Special Logic or Processing Required

This function is application-specific.

Common Parameter

This table describes the common parameter for Cancel Document:

Implementing Transaction Master Business Functions

This section discusses using single-record processing and document processing to implement transaction master business functions.

Single-Record Processing

This section provides an interactive and a batch program flow example for single-record processing.

Interactive Program Flow Example

This is an example of an implementing transaction master business functions during single-record processing in an interactive application:

1. Post Dialog is Initialized (optional)

   Call Begin Document.

2. Set Focus on Grid

3. Row is Exited and Changed or Row is Exited and Changed ASYNC

   Call Edit Line.

4. Delete Grid Record Verify- After

   Call Edit Line to perform delete for one record.

   Call Edit Document to perform deletes on a group of records.

5. OK Button Clicked

   Call Begin Doc.

   Call Edit Document.

6. OK Post Button Clicked

   Call End Document.

Master Business Functions usually perform all table I/O for the given table. Therefore, these actions must be disabled:

• Add Grid Record to DB - before

  Suppress Add.

• Update Grid Record to DB - before

  Suppress Update.

• Delete Grid Record to DB - before

  Suppress Delete.

Batch Program Flow Example

This is an example of an implementing transaction master business functions during single-record processing in a batch application:

1. Do Section of Report Header.

   Call Begin Document.

2. Do Section of the Group Section.

   Call Edit Line.

3. Do Section of a Conditional Section (optional).

   Call Edit Document.

4. Do Section of Report Footer.

   Call End Document.

Document Processing

This section provides an interactive program flow example for document processing.

Program Flow Example

This is an example of an implementing transaction master business functions during document processing in an interactive application:

1. Dialog is Initialized

   Call Open Batch Edit Object module.

2. Grid is Entered

   Call Begin Document Edit Object module.

3. Row is Exited

   Call Edit Line Edit Object module.

4. OK Button Clicked

   Call Edit Document Edit Object module.

5. Before Add from Database or Before Delete from Database

   Suppress Add/Delete.

   Call End Document Edit Object module.

6. Cancel Button Clicked

   Call Close Batch Edit Object module.

Working with Master File Master Business Functions

Master business functions (MBFs) enable calling programs to process certain predefined transactions. An MBF encapsulates the required logic, enforces data integrity, and insulates the calling programs from the database structures. Use MBFs for these reasons:

• To create reusable, application-specific code.

• To reduce duplicated code.

• To ensure that hookup is consistent.

• To support interoperability models.

• To enable processing to be distributed through OCM.

• To design event-driven architecture.

MBFs are typically used for multiline business transactions such as journal entries or purchase orders. However, certain master files also require MBF support due to their complexity, importance, or maintenance requirements from external parties. The requirements for maintaining master files are different from those for multiline business transactions.

Generally, master file MBFs are much simpler than multiline business transaction MBFs. Transaction MBFs are specific to a program, while master file MBFs access a table multiple times.

For interoperability, master file MBFs can be used instead of table I/O. This enables you to perform updates to related tables using the business function instead of table event rules. Multiple records are not used; instead, all edits and actions are performed with one call.

In their basic form, master file MBFs have these characteristics:

Master file applications use the system to process all I/O for find/browse forms. This enables you to use all of the search capabilities of the software.

You should design all master file applications so that all fix/inspect forms are independent of each other. Each fix/inspect form can use the system to fetch the record, and all edits and updates occur using the master file MBF. This independent design has these major benefits:

• It organizes the application in a way that simplifies edits involving dependent fields across multiple forms.

• It enables consistent implementation of modeless processing for all master file applications and all forms within these applications.

Certain circumstances might justify deviation from this simple model. These circumstances are:

• Extremely large file formats

  When the number of columns in the master file plus the required control fields in the call data structure exceed technical limitations for data structures, the MBF can be split. You can split the MBF into one MBF that handles base data and performs all adds and deletes, and one or more MBFs that enable the calling program to update additional data when the base data has been established. In this case, it is usually logical to split it, regardless of the technical limitation. For example, assuming that the customer master file exceeded the data structure limitation, you would use these two MBFs to process the file:

• F0301ProcessMasterData

• F0301ProcessBillingData

  In this example, the F0301ProcessMasterData function processes the base data, and the F0301ProcessBillingData function updates additional data.

• Subordinate detail files

  Information can exist in addition to the primary master file that has been normalized to enable for a one-to-many relationship. Designing the Master File MBF strictly on the basis of how the database is designed translates into three calls. Including at least one occurrence of a detail relationship in the data structure of a Master File MBF is valid. This inclusion enables users to establish reasonably complete master file information using a simple interface to meet simple needs. Street addresses and phone numbers within Address Book are a good example. Customers expect that they can create an address book record by calling a simple address book API with basic identifying information, the street address, and a phone number.

MBF Information Structure

This section discusses the parameters of the MBF information structure.

Standard Parameters for Single-Record Master Business Functions

This table describes the standard parameters for single-record MBFs:

Application-Specific Control Parameters (Example: Address Book)

This table describes the application-specific parameters for Address Book:

Application Parameters (Example: Address Book)

This table describes the application parameters for Address Book:

Master Business Function Impact on Performance

Performance issues might occur regardless of how you handle large-format tables. Two options for improving performance are:

• Group data logically to enable data structures to be smaller and easier for the user to implement.

  This configuration does, however, force the user to make multiple calls to add or update an entire record in a table.

• Use a data structure that enables 300 fields.

  This configuration is cumbersome to implement, and the user can choose not to apply all of the fields.

Through different interfaces, the user can add additional data later. Most processes dictate that part of the data be added immediately, while related data can be added later. For example, the user might define a customer master record but wait until a later date to define the customer's billing instructions. Therefore, you should select the first option of splitting MBFs so that one MBF handles base data and one MBF handles additional data.

Working with Business Functions

Every business function must follow a defined structure and form. Every line of code must conform to the JD Edwards EnterpriseOne business function programming standards. Creating a business function involves these overall tasks:

• Use JD Edwards EnterpriseOne Object Management Workbench (OMW) to build business function data structures.

• Use OMW to build business function source and header files.

• Build and add type definitions for data structures to the header file.

Business function DLLs are consolidated. Therefore, you need to build each of the custom business functions into a custom DLL that you create. This process ensures that the custom business functions remain separate from JD Edwards EnterpriseOne business functions. The build program reviews the F9860 table to verify that the custom DLL exists.

When you create a custom business function, you need to specify one of the custom DLLs. If you do not, the build process builds the custom business function into the JD Edwards EnterpriseOne CCUSTOM.DLL, where CCUSTOM is the seven-character name of the company, which is the default.

Prerequisite

Create a data structure.

Creating a Custom DLL

To create a custom DLL:

1. In OMW, create a new Business Function Library.

2. In Windows, run BusBuild.exe.

   Typically, this file is located in ..\B9\System\Bin32\.

3. Rebuild all libraries by selecting Build, Rebuild Libraries in OMW.

   This process takes several minutes.

Specifying a Custom DLL for a Custom Business Function

To specify a custom DLL for a custom business function :

1. In Business Function Design Aid, enter the custom DLL name in the Parent DLL field.

   Note. You can also change the business function location if necessary.

2. Run the build for the business function.

Working with Business Function Builder

Use JD Edwards EnterpriseOne Business Function Builder to build business function code into a DLL. You can build C business functions, Named Event Rules (NERs), and table event rules. The process that occurs when you run JD Edwards EnterpriseOne Business Function Builder to build business functions includes compiling and linking. Compiling involves creating a business function object. Linking makes the object part of a DLL.

Note. Link All does not compile any business functions; it only links each DLL.

You usually use JD Edwards EnterpriseOne Business Function Builder to build a single business function. Whenever you create source code changes to a business function, you must build the business function to test it.

Build Output displays the results of the build. When the build is finished, the message ***Build Finished*** appears at the bottom of Build Output. The text after this line indicates whether the build was successful. If the build was successful, you can test the business function. Otherwise, you must correct any problems and rerun the build process.

The system creates a work directory when any object is built. This directory is in the destination directory that you specified, such as C:\b7\appl_pgf\work\buildlog.txt. This directory contains error and information logs. The build log contains the same information as the Build Output form in JD Edwards EnterpriseOne Business Function Builder.

Setting Build Options

Use options on the Build menu to control how and when the consolidated business function is built. This table describes the available options:

Reading Build Output

Build Output consists of a series of sections that display important information about the status of a build. You can use this information to determine whether the build completed successfully and to troubleshoot problems if errors occurred during the build.

Makefile Section

The makefile section indicates where Business Function Builder generated the makefile for a particular build. JD Edwards EnterpriseOne Business Function Builder generates one makefile for each DLL that it builds. A Generating Makefile statement should always appears for each DLL that you are building. If the makefile statement does not appear, then an error occurred. To resolve the error, you must complete these tasks:

• Verify that the local object directory exists.

• Verify that the permissions for the local object directory and the makefile are correct.

Begin DLL Section

Begin DLL indicates that Business Function Builder is building a particular DLL. For example, assume that the previous section begins with*****CDIST*****. A Begin DLL section appears for each DLL that you are building.

Compile Section

Before it build DLLs, Business Function Builder compiles the business functions in the DLLs first. The system displays a sequential list of each business function that the Business Function Builder attempts to compile. During the compilation process, these events might occur:

• Compiler Warning

  When a compiler warning occurs, JD Edwards EnterpriseOne Business Function Builder displays warning C XXXX (where XXXX is a number) and a brief description of the warning. To review information about the warning, search for the C XXXX value in Visual C++ online help. Warnings usually do not prevent the business function from compiling successfully. However, you can select the Warnings As Errors option in the Global Build form so that the business function will not build if any warnings occur.

• Compiler Error

  When a compiler error occurs, JD Edwards EnterpriseOne Business Function Builder displays error C XXXX (where XXXX is a number) and a brief description of the error. To review extended information about the error, search for the C XXXX value in Visual C++ online help. Because errors prevent the business function from compiling successfully, you must resolve them.

Link Section

After Business Function Builder has compiled the business functions for a DLL, it links them. This linking process creates the .lib and .dll files for the DLL. During linking, these events might occur:

• Linker Warning

  When a linker warning occurs, JD Edwards EnterpriseOne Business Function Builder displays warning LNK XXXX (where XXXX is a number) and a brief description of the warning. To review information about the warning, search for the LNK XXXX value in the Visual C++ helps. Warnings usually do not prevent the business function from linking successfully. You can select the Warnings As Errors option in the Global Build form so that the DLL will not build if it has any warnings occur.

• Linker Error

  When a linker error occurs, JD Edwards EnterpriseOne Business Function Builder displays error LNK XXXX (where XXXX is a number) and a brief description of the error. To review extended information about the error, search for the LNK XXXX value in the Visual C++ helps. If a nonfatal error occurs, Business Function Builder still creates the DLL. However, JD Edwards EnterpriseOne Business Function Builder notes that the DLL was built with errors. If a fatal error occurs, JD Edwards EnterpriseOne Business Function Builder does not build the DLL.

Rebase Section

The Rebase Section displays information about rebasing. Rebase fine-tunes the performance of DLLs so that they load faster. Rebase does this by changing the desired load address for the DLL so that the system loader does not have to relocate the image. The system automatically reads the entire DLL and also updates fixes, debug information, checksum information, and time stamp values.

Summary Section

The Summary Section contains the most important information about the build. This section indicates whether the build is successful. The summary section begins with *****Build Finished*****. JD Edwards EnterpriseOne Business Function Builder also displays a summary report for each DLL that you attempted to build. This report includes this information:

• The number of warnings.

• The number of errors.

• Whether the DLL build is successful.

Building All Business Functions

You can use Build All to build all business functions. Build All performs the same operations as global link, and it recompiles all of the objects within each DLL. A system administrator usually runs Build All. Build All processes can take a long time. To run Build All, you must access BusBuild.

To build all business functions:

1. In Windows, run BusBuild.exe.

   Typically, this file is located in ..\B9\system\Bin32\.

2. In BusBuild, start the mass build by selecting Build, Build All.

3. Select one of these options for Build Mode:

   • Debug

     A build that includes debug information. After you perform a build, you can debug the built business function using the Visual C debugger.

   • Optimize

     A build that does not include debug information. Optimized builds generally cannot be debugged using the Visual C debugger.

   • Performance Build

     A build that is the same as an optimized build except that it includes information that helps developers measure the performance of business functions. Only JD Edwards developers should select this option.

4. Complete the Source Directory field.

   Use this field to specify where the business function source resides. Business function source includes all .c, .h, named event rules, and table event rules. Full packages usually have all business function sources. These are the options for location:

   • Local

     All business function source is on the local machine.

   • Path Code

     All business function source is in the path specified by the selected path code.

   • Package

     The All business function source is in the path specified by the selected package. If a package is built correctly, it typically contains all required business function sources. Generally, you should use Package for the location.

   • Pick Directory

     All business function source is stored in another directory on the file server. You specify the directory.

5. Complete the Foundation Directory field.

   Use this field to specify the foundation to use for this build. The foundation that you select is the foundation on which you expect these business functions to run. These are the options for this field:

   • Local

     The recommended foundation is the local JD Edwards EnterpriseOne foundation.

   • Foundation

     The foundation table lists all registered JD Edwards EnterpriseOne foundations. Select a foundation from this table.

   • Pick Directory

     The JD Edwards EnterpriseOne foundation exists in a directory on the file server. You specify the directory. JD Edwards EnterpriseOne recommends this location.

6. Complete the Output Destination Directory field.

   Use this field to specify the location for the output of the build. The build output includes the file types: DLL, .LIB, .OBJ, and LOG. The location options are the same as those for Source Directory. Generally, you should select Package because it is a more stable snapshot of business function source.

7. Select any of these options:

   • Treat Warnings As Errors

     If you select this option, JD Edwards EnterpriseOne Business Function Builder does not build a business function if it encounters any warnings.

   • Clear Output Destination Before Build

     If you select this option, JD Edwards EnterpriseOne Business Function Builder deletes the contents of the bin32, lib32 and obj output directories before it builds all business functions.

   • Select Which DLLs to Build

     If you clear this option, JD Edwards EnterpriseOne Business Function Builder builds all DLLs. If you select this option, you can click the Select button and select which business function DLLs you want to build. Select this option if you want to build one or two DLLs. If you build only a subset of all DLLs, verify that the Clear Output Destination Before Build option is cleared.

   • Stop Level

     You can select the error level at which the build stops. You can ignore errors if you want to continue building despite them. You can specify that the build process stop if a DLL contains errors. You can stop on the first compile error.

   • Generate Missing Source Report

     If you select this option, v Business Function Builder generates a report in the work directory of the destination. This report is called NoSource.txt. It contains business function source file names that do not have a .c file but do have a record in the F9860 table. To resolve the information in this report, you can produce the correct .c file for the business function, or you can delete the source file from the F9860 table. It is recommended that you select this option.

   • Generate ER Source

     If you select this option, v Business Function Builder generates NER and table event rule source before building business functions.

   • Verify Check-in

     If you select this option, the system builds only objects checked in to a specified path code. A log file, Notchkdn.txt, is written to the same directory as Nosource.txt. Objects that are not checked in to the path code will be listed in this log and in Buildlog.txt.

Select the From RDB option to generate work from any path code. If this option is cleared, the business function builder assumes that the event rules source can be generated from the source directory specification files.

If you are troubleshooting a build initiated by Package Build, then the previous settings should already be set to the correct values. In this case, click Build to rebuild the problem DLLs.

Note. You can also run this build by selecting the Build BSFN option on in a package build.

Using the Utility Programs

The Tools menu contains several utility programs that assist in the build process. This table lists those utilities:

Resolving Errors with JDEBLC, Dumpbin, and PDB

You use JD Edwards EnterpriseOne  Business Function Builder tools to help you resolve errors. If you notice any unresolved external errors during a business function build, the consolidated DLL still builds, and the software should run normally. However, it cannot execute any unresolved business function.

Use the dumpbin tool to verify that a particular business function is present in a consolidated DLL. If a business function is present, its name appears in the dumpbin output, followed by a nonzero number in parentheses.

Use the PDB scan to resolve the CVPACK fatal error. The CVPACK error occurs when the Business Function Builder attempts to link an object file that was built with PDB (Program DeBug file) information. The PDB scan finds the problem object file. You must then recompile the problem object file on the machine with the JD Edwards EnterpriseOne Business Function Builder.

If a business function is compiled using Visual C++, it will not work properly. You can use PDB scan to identify any business functions that have been built outside of JD Edwards EnterpriseOne Business Function Builder. Use JD Edwards EnterpriseOne Business Function Builder to rebuild these functions so that they work properly.

If one of the DLLs is out of synch, you must rebuild it using the Build option. This generates a makefile and then relinks all the business functions within it.

The Synchronize JDEBLC option from the JD Edwards EnterpriseOne Business Function Builder Tools menu corrects any misplaced or incorrectly-built business functions. This option reviews the server DLLs and determines whether the local workstation specifications match those of the server. If they do not, then JD Edwards EnterpriseOne Business Function Builder will rebuild the business functions in the correct DLL on the server and relink them.

The Build Log contains these sections:

Customizing the Tools Menu

This table lists the sections of the Customize menu option:

This table lists the buttons in the Customize menu option:

Threadsafe Code

All BSFNs created for JD Edwards EnterpriseOne 8.11 Applications Release and earlier Applications releases are designed to run in a single-threaded environment. BSFNs designed for JD Edwards EnterpriseOne 8.11 SP1 Applications Release and later Applications releases that also run with JD Edwards EnterpriseOne Tools Release 8.96 and later Tools releases are designed to run in a multi-threaded environment. To be considered threadsafe, BSFNs cannot use:

• Global variables.

• Static variables.

• External declarations.

• Non-threadsafe ANSI C APIs.

Safety Check is a source code analysis tool that scans C source code and header files for non-threadsafe behaviors. Given a source or header file, Safety Check finds all instances of non-threadsafe code, returning line numbers and code fragments.

Several non-threadsafe APIs have a JD Edwards EnterpriseOne replacement. These replacement APIs have the same parameters as the non-threadsafe C APIs, except where noted. Most non-threadsafe APIs do not have a JD Edwards EnterpriseOne replacement. These APIs and their replacements do not necessarily have the same parameters. Use care when using these APIs.

This table lists the non-threadsafe C APIs for which SafetyCheck searches, the threadsafe standard C replacements, and the threadsafe JD Edwards EnterpriseOne replacements (if applicable):

Safety Check Usage

During the course of development, there may be times when a non-threadsafe type of code must be used. You can mark source code with an explanation about why the non-threadsafe code exists. Safety Check will then display this information as part of its run. To mark source code with an exception, include a comment in this format: /*_LRBF <comment text */. The comment must begin with "/*_LRBF." The remainder of the comment can span multiple lines and include any other necessary text. The entire comment will print as part of Safety Check output.

You control Safety Check functionality through several options, at least one of which must be supplied. Multiple options are supported. Quotation marks are required only when the path specified contains spaces. For example, if the single C source file b1234.c is stored in the "c:\source" directory, you could call SafetyCheck in one of two ways: SafetyCheck --F c:\source\b1234.c or SafetyCheck --F "c:\source\b1234.c" However, if the same C source file is stored in the "c:\test files", you must enclose the path/filename in quotations: SafetyCheck --F "c:\test files\b1234.c"

Safety Check Output

A “clean” Safety Check run will produce output of this format:

---------------- SafetyCheck Started ---------------

Scanning d:\safetychecktestrun\source\b03b0011.c...

---------------------- Done ----------------------

1 Files Processed 0 Errors 0 Warnings

“Files processed” indicates how many files were scanned. “Errors" reports the number of file-based errors encountered. “Warnings” reports the number of problems found while scanning the specified files.

A “dirty” Safety Check run will produce output of this format:

---------------- SafetyCheck Started ---------------

Scanning d:\safetychecktestrun\source\b03b0011.c...

d:\safetychecktestrun\source\b03b0011.c(186): Global variable found

int iGlobal = 0;

---------------------- Done ----------------------

1 Files Processed 0 Errors 1 Warnings

In this case, the output indicates:

• A problem was found in d:\safetychecktestrun\source\b03b0011.c

• The problem occurred on line 186.

• The problem found was the presence of a global variable.

• The section of code that caused the problem is “int iGlobal = 0;”

Note that the global variable was specified as a "Warning" and not an "Error".

Safety Check Limitations

Following are limitations for safety check:

1. Safety Check is a static code analysis tool that does not perform preprocessing of source code. Therefore, macro substitutions may introduce non-threadsafe behaviors that cannot be detected by Safety Check.

2. Safety Check does not know which compile-time flags may be set. Problems will occur in code that looks like this because the number of open braces does not match the number of close braces:

   int FunctionOne(int i) { if (i == 0) #ifdef FLAG1 { ++i; #else { --i; #endif } }

3. Non-threadsafe code may still exist even though Safety Check reports no warnings. Safety Check is looking for the presence of only four specific code elements (globals, variables, externs and non-threadsafe ANSI C APIs). Do not rely solely on a “clean” run of Safety Check as the only test of whether the code is threadsafe.

Understanding Business Function Processing Failovers

In some instances in which a business function fails to process correctly, the software can attempt to recover and reprocess the transaction. The system recognizes two principle failure states: process failure and system failure.

A process failure occurs when a jdenet_k process aborts abnormally. For a process failure, the software server processing launches a new jdenet_k process and continues processing.

A system failure occurs when all the server processing fails, the machine itself is down, or the client cannot reach the server because of network problems. For a system failure, business function processing must be rerouted either to a secondary server or to the local client. The system uses this process to attempt to recover from this state:

• When the call to the server fails, the system attempts to reconnect to the server.

• If reconnect succeeds and no cache exists, the system reruns the business function on the server.

  If a cache does exist, the system forces the user out of the application.

• If reconnect fails and no cache exists, the system switches to a secondary server or to the local client.

  If a cache does exist, the system forces the user out of the application.

After one module switches, all subsequent modules switch to the new location.

Working with Business Function Documentation

This section provides an overview of business function documentation, and discusses how to:

• Create business function documentation.

• View documentation from the Business Function Documentation Viewer.

Understanding Business Function Documentation

Business function documentation explains what individual business functions do and how they should be used. The documentation for a business function should include this type of information:

• Purpose.

• Parameters (the data structure used).

• Descriptions for each parameter that indicate required input and output, and explain return values.

• Related tables (the table accessed).

• Related business functions (business functions called from within the function itself).

• Special handling instructions.

You use Business Function Design and Data Structure Design to document the business functions.

Creating Business Function Documentation

You can create business function documentation for several levels, including these:

• Business Function Notes

  Documentation for the specific business function that you are using.

• Data Structure Notes

  Notes about the data structure for the business function.

• Parameter Notes

  Notes about the actual parameters in the data structure.

Generating business function documentation provides you with an online list of information about business functions that you can view through the Business Function Documentation Viewer (P98ABSFN). Typically, the system administrator performs this task because generating the business function documentation for all business functions takes considerable time. If you create new business function documentation, you need to regenerate the business function documentation for that business function only.

Run UBE R98ABSFN, batch version XJDE0001 to generate all business function documentation. The system creates a hypertext markup language (HTML) link for each business function for which you generated documentation. It also creates an Index HTML file. These HTML files appear in the output queue directory.

Viewing Documentation from Business Function Documentation Viewer

You can use Business Function Documentation Viewer to view documentation for all business functions or selected business functions. After you generate the report, use the Business Function Documentation Viewer (P98ABSFN) to display the information. It is suggested that you use this method to view business function documentation.

The Business Function Documentation form contains the HTML index that you generated. To view the entire index or select specific functions, click the appropriate letter in the index. Double-click a business function to view documentation that is specific to that function.

The media object loads the HTML index of the business functions based on a media object queue. In the media object queue table, a queue named Business Function Doc is defined.

This queue must point to the directory in which the business function HTML files are located. The system administrator usually generates the documentation for all business functions. Because the generation process places the documentation files in the local directory, the administrator must then copy the files to a central directory on the deployment server. The files must be copied to the media object queue for media object business function notes. If you are using the standalone version of the software, this path is usually the output directory from the Network Queue Settings section of the jde.ini file. If this entry is not in the jde.ini file, it is in the print queue directory in the JD Edwards EnterpriseOne software directory.