3 Using Business Functions

This chapter contains the following topics:

3.1 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.

3.1.1 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:

Component Where Created
Business Function Specifications OMW

Business Function Design

Data Structure Specifications OMW

Data Structure Design Tool

.C file Generated in Business Function Design

Modified with the IDE

.H file Generated in Business Function Design

Modified with the IDE


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:

DLL Name Functional Group
CAEC Architecture
CALLBSFN Consolidate BSFN Library
CBUSPART Business Partner
CCONVERT Conversion Business Functions
CCORE Core Business Functions
CCRIN Cross Industry Application
CDBASE Tools - Database
CDDICT Tools - Data Dictionary
CDESIGN Design Business Functions
CDIST Distribution
CFIN Financials
CHRM Human Resources
CINSTALL Tools Install
CINV Inventory
CLOC Localization
CLOG Logistics Functions
CMFG Manufacturing
CMFG1 Manufacturing - Modification BFs
CMFGBASE Manufacturing Base Functions
COBJLIB Tools - Object Librarian
COBLIB Busbuild Functions
COPBASE Distribution/Logistic Base Functions
CRES Resource Scheduling
CRUNTIME Tools - Run Time
CSALES Sales Order
CTOOL Tools - Design Tools
CTRAN Transportation
CTRANS Tools - Translations
CWARE Warehouse
CWRKFLOW Tools - Workflow
JDBTRG1 Table Trigger Library 1
JDBTRG2 Table Trigger Library 2
JDBTRG3 Table Trigger Library 3
JDBTRG4 Table Trigger Library 4
JDBTRIG Parent DLL for Database Triggers

Note:

Do not use table triggers for regular business functions.

3.1.2 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:

Figure 3-1 Distributed business function

Description of Figure 3-1 follows
Description of ''Figure 3-1 Distributed business function''

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

3.1.3.1 Header File Sections

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

Section What It Includes Description and Guidelines
Header File Comment
  • Header file name
  • Description

  • History

  • Programmer

  • SAR number

  • Copyright information

Comments that the input process of the Business Function Source Librarian builds.

The programmer name and SAR number are manually updated by the programmer.

Table Header Inclusions Include statements for header files associated with tables that are directly accessed by this business function. Table header files include definitions for the fields in a table and the ID of the table itself.
External Business Function Header Inclusions Include statements for headers associated with externally defined business functions that are directly accessed by this business function. External function calls with jdeCallObject are included to use the predefined data structures.
Global Definitions Global constants used by the business function. Use global definitions sparingly. They include symbolic names that you enter in uppercase; words are separated by an underscore character.
Structure Type Definitions Data structure definitions for internal processing. To prevent naming conflicts, define this structure using structure names that are prefixed by the source file name.
DS Template Type Definition Data structure type definitions generated by Business Function Design.

Symbolic constants for the data structure generated by Business Function Design.

Modify this structure through OMW.
Source Preprocessor
  • Undefines JDEBFRTN if it is already defined.
  • Checks for how to define JDEBFRTN.

  • Defines JDEBFRTN.

Ensures that the business function declaration and prototype are properly defined for the environment and source file, including this header.
Business Function Prototype Prototypes for all business functions in the source file. Defines the business functions in the source file, the parameters that are passed to them, and the type of value that they return.
Internal Function Prototype Prototypes for all internal functions that are required to support business functions within this source file. Defines the internal functions that are associated with the business functions in the source file, the parameters that are passed to each internal function, and the type of value that they return.

3.1.3.2 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:

Header File Line Where Input Description
Header File OMW Verify the name of the business function header file.
Description OMW Verify the description.
History IDE Manually update the modification log with the programmer name and the appropriate SAR number.
#ifndef Business Function Design Symbolic constant prevents the contents from being included multiple times.
Table Header Inclusion Business Function Design When business functions access tables, related tables are input and Business Function Design generates an include statement for the table header file.
External Business Function Header Inclusions Business Function Design No external business functions for this application.
Global Definitions IDE Constants and definitions for the business function. It is not recommended that you use this block. Global variables are not recommended. Global definitions go in .c not .h.
Structure Definitions IDE Data structures for passing information between business functions, internal functions, and database APIs.
TYPEDEF for Data Structure Business Function Design Data structure type definition. Used to pass information between an application or report and a business function. The programmer places it on the clipboard and pastes it in the header file. Its components include:
  • Comment Block, which describes the data structure.

  • Preprocessor Directives, which ensure that the data type is defined only once.

  • Typedef, which defines the new data type.

  • #define, which contains the ID to be used in processing if the related data structure element is in error.

  • #endif, which ends the definition of the data structure type definition and its related information.

Source Preprocessor Definitions Business Function Design All business function header files contain this section to ensure that the business function is prototyped and declared based on where this header is included.
Business Function Prototype Business Function Design Used for prototypes of the business function.
JDEBFRTN(ID) JDEBFWINAPI CheckForInAddMode Business Function Design Business Function Standard

All business functions share the same return type and parameter data types. Only the function name and the data structure number vary between business functions.

Parameters include:

  • LPBHVRCOM

    Pointer to a data structure used for communicating with business functions. Values include an environment handle.

  • LPVOID

    Pointer to a void data structure. Currently used for error processing; will be used for security in the future.

  • LPDS#####

    Pointer to a data structure containing information that is passed between the business function and the application or report that invoked it. This number is generated through Object Librarian.

  • JDEBFRTN(ID)JDEBFWINAPI

    All business functions will be declared with this return type. It ensures that they are exported and imported properly.

Parameter names (lpBhvrCom, lpVoid, and lpDS) will be the same for all business functions.

Internal Function Prototypes Business Function Design Internal function prototypes required to support the business functions in this source file.

3.1.3.3 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:

Section What It Includes Description
Source File Comment Block
  • Source file name
  • Description

  • History

  • Programmer

  • Date

  • SAR Number

  • Description

  • Copyright information

Built from the information in the Business Function Design Tool.

The programmer manually updates the programmer name and SAR number.

Notes Comment Block Any additional relevant notes concerning the business function source. Document complex algorithms used, how the business functions in the source relate to each other, and so on.
Business Function Comment Block
  • Business function name
  • Description

  • Description list of the parameters

n/a
Business Function Source Code Source code for the business function. n/a
Internal Function Comment Block
  • Function name
  • Notes

  • Returns

  • Parameters

Copy these blocks and place the values in the specified sections to describe the internal function. Follow the comment block with internal function source code.
Internal Function Source Code Source code for the internal function described in the comment block. The business function developer enters this code as needed. A populated internal function comment block must precede this code.

3.1.3.4 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:

Source File Line Where Input Description and Guidelines
#include <jde.h> Business Function Design Includes all base JD Edwards EnterpriseOne definitions.
#define b98sa001_c Business Function Design Ensures that related header file definitions are correctly created for this source file.
Source File OMW Verifies the information in the file comment section. Enter the programmer's name, SAR number, and description.
#include <B98SA001.h> OMW Includes the header file for this application.
Business Function Business Function Design Verifies the name and description in the business function comment block.
JDEBFRTN(ID) JDEBFWINAPI CheckForInAddMode (LPBHVRCOM lpBhvrCom, LPVOID lpVoid,

LPDS104438 lpDS)

Business Function Design Includes the header of a business function declaration.
Variable declarations IDE Declares variables that are local to the business function.
Declare structures IDE Declares local data structures to communicate between business functions, internal functions, and the database.
Declare pointers IDE Declares pointers.
Check for NULL pointers Business Function Design Business Function Standard

Verifies that all communication structures between an application and the business function are valid.

jdeErrorSet (lpBhvrCom, lpVoid, (ID) 0, _J("4363"), LPVOID) NULL);

return ER_ERROR;

Business Function Design Sets the standard error to be returned to the calling application when any of the communication data structures are invalid.
Set pointers IDE Declares and assigns appropriate values to pointers.
Main Processing IDE Provides main functionality for a business function.
Function Clean Up IDE Frees any dynamically allocated memory.
Internal function comment block IDE Defines internal functions that are required to support the business function. They should follow the same C coding standards. A comment block is required for each internal function and should be formatted correctly.

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.

3.1.4 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

3.2 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:

Field Description Field Key Type Size
Job Number JOBS X Num N/A
Document Action ACTN N/A Char 1
Processing Options N/A N/A N/A N/A
Currency Flag CYCR N/A Char 1
Business View Fields N/A N/A N/A N/A
Work Fields N/A N/A N/A N/A

This table explains the fields:

Field Description Purpose
Job Number A unique system-assigned number assigned when the BeginDoc module starts the job. This distinguishes transactions in the cache for each job on the workstation that is using the cache. Use next number 00/4 for the job number. If you are using a unique cache name (Dxxxxxxxxx[job number]), you do not necessarily need the job number field stored in the cache for a key because you would only be working with one transaction per cache. You can, therefore, use any field as the key to the cache.
Document Action The action for the document. Values are:
  • A or 1 = Add

  • C or 2 = Change

  • D = Delete

Processing Options Processing option values were read in using AllocatePOVersionData, and are needed in other modules of the MBF.
Currency Flag A system value that indicates whether currency is on and what method of currency conversion is used (N, Y, or Z).
Business View Fields The fields required for processing the transaction and writing it to the database. All fields in the record format that are not saved in the header cache will be initialized when the record is added to the database using the APIs.
Work Fields Fields that are not part of the business view (BV), but are needed for editing and updating the transaction.

For example, Last Line Number is the last line number written to the detail cache. It will be stored at the header level, and retrieved and incremented by the MBF. The incremented line number will be passed to the header cache and stored for the next transaction.


This table describes the components of the detail section:

Field Description Field Key Type Size
Job Number JOBS X Char 8
Line Number (Application-specific) X Num N/A
Line Action ACTN N/A Char 1
Business View Fields N/A N/A N/A N/A
Work Fields N/A N/A N/A N/A

This table explains the fields:

Field Description Purpose
Job Number A unique number assigned when the BeginDoc module starts the job. This distinguishes transactions in the cache for each job on the client that is using the cache. If you are using a unique cache name (Dxxxxxxxxx[job number]), you do not necessarily need to store the job number field in the cache for a key because you work with only one transaction per cache. You can, therefore, use line number only as the key to the cache.
Line Number The number used to uniquely identify lines in the detail cache. This line number can also eventually be assigned to the transaction when it is written to the database. The transaction lines are written to the detail cache only if they are error-free.
Line Action The action for the transaction line. Values are:
  • A or 1 = Add

  • C or 2 = Change

  • D = Delete

Business View Fields Fields required for processing the transaction that will be written to the database. All fields in the record format that are not saved in the detail cache will be initialized when the record is added to database using the APIs.
Work Fields Fields that are not part of the business view, but are needed for editing and updating the transaction line.

3.3 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

3.3.1 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:

Figure 3-2 Building transaction master business functions

Description of Figure 3-2 follows
Description of ''Figure 3-2 Building transaction master business functions''

Next, you combine the business functions into a DLL:

Figure 3-3 Combining business functions into a .DLL

Description of Figure 3-3 follows
Description of ''Figure 3-3 Combining business functions into a .DLL''

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

Component Purpose
Begin Document Called when all header information has been entered. Creates initial header if it has not already been created. Can also include default values, editing, and processing options (POs).
Edit Line Called when all line information has been entered. Creates cache for detail information if it has not already been created.
Edit Document Called when ready to commit the transaction. Processes any remaining document edits and verifies that all records are valid to commit.
End Document Called when you need to commit the transaction. Processes all records in the header and detail cache, performs I/O, and deletes caches.
Clear Cache Called when you are ready to delete all cache records. Deletes header and detail cache records.

3.3.2 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.

3.3.2.1 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.

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

3.3.2.3 Common Parameters

This table describes the common parameters for Begin Document:

Name Alias I/O Description
Job Number JOBS I/O Pass Job Number created in Begin Document, if previously called; otherwise, pass zeros and assign a job number.
Document Action ACTN I A or 1 = Add

C or 2 = Change

D = Delete

This is the action of the entire Document, not the individual detail lines. For example, you might modify a few detail lines in Edit Line, add a few detail lines in Edit Line, and delete a few detail lines in Edit Line, but the Document Action in Begin Document would be Change.

Process Edits EV01 I Optional

0 = No Edits

Any Other = Full Edits

Note: The GUI interface usually uses the partial edit, and the batch interface uses the full edit. If you leave this parameter blank, the default option is full edits.

ErrorConditions EV02 O Blank = No Errors

1 = Warning

2 = Error

Version VERS I This field is required if this MBF is using versions.
Header Field One **** I/O Pass in all the header fields that are common to the entire document. Begin Document processes all of these fields and validates them, data dictionary edits, UDC editing, default values, and so on. Begin document might also fetch to the table to validate that records matching these header fields exist for Delete and Change, or do not exist for Add.
Header Field Two **** I/O N/A
.

.

.

**** I/O N/A
Header Field XX **** I/O N/A
Work Field / Processing Flag One **** I List any work fields that the program needs. These could be flags for processing, dates to validate, and so on. These fields might or might not be used. For example, currency control might be saved in the header cache so that all detail records would either use currency or not.
Work Field / Processing Flag One **** I N/A
.

.

.

N/A I N/A
Work Field / Processing Flag One N/A I N/A

3.3.2.4 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.

3.3.3 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.

3.3.3.1 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.

3.3.3.2 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.

3.3.3.3 Common Parameters

This table describes the common parameters for Edit Line:

Name Alias I/O Description
Job Number JOBS I Used as key or to create a unique name for the cache or work file. Retrieved from Begin Document.
Line Number LNID I/O The unique number identifying the transaction line. Can also be used as the line number in the Detail Cache.
Line Action ACTN I A or 1 = Add

C or 2 = Change

D or 3 = Delete

Process Edits (optional) EV01 I 0 = No Edits

1 = Full Edits

2 = Partial Edits

Note: GUI interface typically uses the partial edit, and the batch interface typically uses the full edit. If you leave this parameter blank, the default edit is Full.

Error Conditions ERRC O 0 = No Errors

1 = Warning

2 = Error

Update Or Write to Work File EV02 I 1 = Write or update records to the work file, or do both.
Record Written to Work File EV03 I/O 1 = A record is written to the work file. This reduces I/O calls to the work file.

Blank = No record is written to the work file.

Detail Field One **** I/O Pass in all the Detail fields that will be edited. Typically, these are the grid record fields. Edit Line provides validation, data dictionary edits, UDC editing, default values, and so on.
Detail Field Two **** I/O N/A
Detail Field XX **** I/O N/A
Work Field / Processing Flag One **** I List any work fields that the program needs. These fields could be flags for processing, dates to validate, and so on.
Work Field / Processing Flag One **** I N/A
Work Field / Processing Flag One **** I N/A

3.3.4 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.

3.3.4.1 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.

3.3.4.2 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.

3.3.4.3 Common Parameters

This table describes the common parameters for Edit Document:

Name Alias I/O Description
Job Number JOBS I Retrieved from Begin Document
ErrorConditions EV01 O Blank = No Errors

1 = Warning

2 = Error


3.3.4.4 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.

3.3.5 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.

3.3.5.1 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.

3.3.5.2 Common Parameters

This table describes the common parameters for End Document:

Name Alias I/O Description
Job Number JOBS I Retrieved from Begin Document
Computer ID CTID I Retrieved from GetAuditInfo(B9800100) in application (optional)
Error Conditions EV01 O Blank = No errors

1 = Warning

2 = Error

Program ID PID I Usually hard-coded

3.3.5.3 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.

3.3.6 Clear Cache

Clear Cache has this format:

FxxxxxClearCache

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

3.3.6.1 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.

3.3.6.2 Common Parameters

This table describes the common parameters for Clear Cache:

Name Alias I/O Description
Job Number JOBS I Indicates the job number of the transaction that you want to clear. This job number should have been returned from BeginDoc.
Clear Header EV01 I Indicates whether the header cache should be cleared.

1 = clear cache

Clear Detail EV02 I Indicates whether the detail cache should be cleared

1 = clear cache

Line Number From (Optional) LNID I Indicates where to begin clearing records in the detail cache. If this line is blank, the system begins clearing from the first record.
Line Number Thru (Optional) NLIN I Indicates where to stop clearing records in the detail cache. If this line is blank, the system deletes to the end of the cache.

3.3.7 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.

3.3.7.1 Special Logic or Processing Required

This function is application-specific.

3.3.7.2 Common Parameter

This table describes the common parameter for Cancel Document:

Name Alias I/O Description
Job Number JOBS I The job number of the transaction that you want to clear. This number should have been returned from BeginDoc.

3.4 Implementing Transaction Master Business Functions

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

3.4.1 Single-Record Processing

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

3.4.1.1 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.

3.4.1.2 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.

3.4.2 Document Processing

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

3.4.2.1 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.

3.5 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:

Characteristic Description
Single call Generally, you can make one call to an MBF to edit, add, update, or delete a master file record. An edit-only option is available also.
Single data structure The fields required to make the request and provide all the necessary values are in one data structure. The data fields should correspond directly with columns in the associated master file.
No cache Because each master file record is independent of the others, caching is unnecessary. The information provided with each call and the current condition of the database provides all of the information that the MBF needs to perform the requested function.
Normal error handling As with other MBFs, master file MBFs must be capable of executing both in interactive and batch environments. Therefore, the calling program must determine the delivery mechanism of the errors.
Inquiry feature To enable external systems to be insulated from the JD Edwards EnterpriseOne database, an inquiry option is included. This enables an external system to use the same interface to access descriptive information about a master file key as it uses to maintain it.
Effect on applications For JD Edwards EnterpriseOne applications, the effect of implementing a master file MBF should be minimal. Consider and follow several standards before implementing a master file MBF.

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.

3.5.1 MBF Information Structure

This section discusses the parameters of the MBF information structure.

3.5.1.1 Standard Parameters for Single-Record Master Business Functions

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

Name Alias I/O Required/Optional Description
Action Code ACTN I Required A = Add.

I = Inquiry.

C = Change.

D = Delete.

S = Same as except (the record is the same except for what the user changes).

Update Master File EV01 I Optional 0 = No update; edit only (default).

1 = Update performed.

Process Edits EV02 I Optional 1 = All Edits (default).

2 = Partial Edits (no data dictionary (DD)).

Suppress Error Messages SUPPS I Optional 1 = Error messages are suppressed.

0 = Process errors normally (default).

Error Message ID DTAI O Optional Returns error code.
Version VERS I Future The default value is XJDE0001.

3.5.1.2 Application-Specific Control Parameters (Example: Address Book)

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

Name Alias I/O Required/Optional Description
Address Book Number AN8 I/O Optional For additions, AN8 is optional. For all other action codes, this parameter is required.
Same as except AN8 I Optional Required for S = Action Code. The record is the same except for what the user changes.

3.5.1.3 Application Parameters (Example: Address Book)

This table describes the application parameters for Address Book:

Name Alias I/O Required/Optional
Alpha Name ALPH I/O Required
Long Address Number ALKY I/O Optional
Search Type AT1 I Required
Mailing Name MLMN I Required
Address Line 1 ADD1 I Optional
City CTY1 I Optional
State ADDS I Optional
Postal Code ADDZ I Optional

3.5.2 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.

3.6 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.

3.6.1 Prerequisite

Create a data structure.

3.6.2 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.

3.6.3 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.

3.7 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.

3.7.1 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:

Option Result
Build Generates a makefile, compiles the selected business functions, and links the functions into the current consolidated DLL. Rebuilds only those components that are out of date.
Compile Generates a makefile and compiles the selected business functions. The application does not link the functions into the current consolidated DLL.
ANSI Check Reviews the selected business function for ANSI compatibility.
Link Generates a makefile for each consolidated DLL and then builds each consolidated DLL. The application does not compile any of the selected business functions.
Link All Generates a makefile for each consolidated DLL and then builds each consolidated DLL and links it to all business functions that are called. The application does not compile any of the selected business functions.
Rebuild Libraries Rebuilds the consolidated DLL and static libraries from the .obj files.
Build All Links and compiles all objects within each DLL.
Stop Build Stops the build from finishing. The existing consolidated DLL remains intact.
Suppress Output Limits the text that appears in Build Output.
Browse Info Generates browse information when compiling business functions. Clear this option to expedite the build.
Precompiled Header Creates a precompiled header when compiling a business function. When compiling multiple business functions, the Business Function Builder generally compiles faster if it uses a precompiled header.
Debug Info Generates debug information when compiling. The Visual C++ can debug any function that was built with debug information. Clear this option to expedite the build.
Full Bind Resolves all of the external runtime references for each JD Edwards EnterpriseOne consolidated DLL.

3.7.2 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.

3.7.2.1 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.

3.7.2.2 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.

3.7.2.3 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 CXXXX (where XXXX is a number) and a brief description of the warning. To review information about the warning, search for the CXXXX 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 CXXXX (where XXXX is a number) and a brief description of the error. To review extended information about the error, search for the CXXXX value in Visual C++ online help. Because errors prevent the business function from compiling successfully, you must resolve them.

3.7.2.4 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 LNKXXXX (where XXXX is a number) and a brief description of the warning. To review information about the warning, search for the LNKXXXX 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 LNKXXXX (where XXXX is a number) and a brief description of the error. To review extended information about the error, search for the LNKXXXX 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.

3.7.2.5 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.

3.7.2.6 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.

3.7.3 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.

3.7.4 Using the Utility Programs

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

Utility Purpose
Synchronize JDEBLC You run the Synchronize JDEBLC program to reorganize JD Edwards EnterpriseOne business functions into new DLL groupings. This program synchronizes DLL field for the local JDEBLC parent specification table with the parent DLL in the F9860 table. Use this program with caution. You typically use this program only if you have manually dragged business function DLLs from a recent package build and you are experiencing failures in the business function load library.
Dumpbin You run the Dumpbin program to verify whether a particular business function built successfully. This program displays all the business functions that were built into the selected consolidated DLL.
PDB (Program DeBug file) Scan You receive a CVPACK fatal error when one of the object files that you are trying to link is incorrectly compiled with PDB information. To resolve this problem, you can use the PDB Scan to identify any object fields that were built with PDB information. Recompile any business functions that the PDB Scan reports.
Customize You use Customize to add programs to the Tools menu. For example, you could add the programming tool and pass that tool a file name as a parameter when it opens.
Safety Check You use Safety Check to check selected files (.c, .h or both) for:
  • global variables

  • static variables

  • extern declarations

  • non-"threadsafe" ANSI C APIs

Safety Check-Check All You use Safety Check-Check All to check all files (.c, .h or both) in a directory for the same conditions as for Safety Check.

3.7.4.1 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:

Section Description
Build Header This section defines the configuration for a specific build, including the source path, foundation path, and destination path.
Build Messages This section displays the compile and link activity. During a compile, a line is output for each business function that was compiled Any compile errors are reported as error cxxxx. During the link part, business function builder outputs the text Creating library .... This text might be followed by linker warnings or errors.
Build Summary The last section of the build summarizes the build for each DLL. This summary is in the form x error(s), x warnings (y). The summary indicates the status of the build. If you have no warnings and no errors, then the build was successful. If the summary reports an error, search the log for the word error to determine the source of the error. Typical build errors are syntax errors and missing files.

3.7.4.2 Customizing the Tools Menu

This table lists the sections of the Customize menu option:

Menu Option Usage
Menu Contents Review all current tools menu customizations.
Menu Text Enter the text to display in the menu.
Command Enter the executable to run. You must supply a full path for any program that does not reside in system\bin32 or that is not defined in Initial Directory.
Arguments Specify any command line arguments to pass to the executable.
Initial Directory Specify the initial directory that should be used by the executable, if it is not system\bin32.
Include in Build Select to display output from the program as part of the build process.

Note: This option is only valid and will only appear for Release 8.11 SP1 or later. If you are running an earlier version, this option is not available, and Safety Check does not run during build. You must, instead, run Safety Check manually from the menu.

Hide Window Select to hide command windows. The functionality remains the same.

This table lists the buttons in the Customize menu option:

Button Usage
Add Select to enter new programs to appear in the pull-down menu.
Remove Select to remove the selected item from the menu.
Move Up Select to move the selected item up in the menu.
Move Down Select to move the selected item down in the menu.
Ellipsis Select to open a file or directory dialog so that you can browse for a file or directory.
Question Mark Select to display a list of substitutions you can use as part of command line arguments. In our SafetyCheck example, one of the command line arguments is: --F <source_file>. By specifying <source_file>, you are telling SafetyCheck to use as its input file the selected source file. When BusBuild starts the build process, it can determine which file is being built and substitute that name in place of the text <source_file>.

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

Non-Threadsafe Standard C API Threadsafe Standard C API Threadsafe JD Edwards EnterpriseOne API
acltostr acltostr_r None
asctime asctime_r jdeJAsctime
crypt crypt_r None
ctime ctime_r jdeJCtime
drand48 drand48_r None
ecvt ecvt_r None
encrypt encrypt_r None
endgrent endgrent_r None
endhostent endhostent_r None
endnetent endnetent_r None
endprotoent endprotoent_r None
endpwent endpwent_r None
endservent endservent_r None
endspwent endspwent_r None
endusershell endusershell_r None
endutent endutent_r None
erand48 erand48_r None
fcvt fcvt_r None
fgetgrent fgetgrent_r None
fgetpwent fgetpwent_r None
getdate getdate_r None
getdiskbyname getdiskbyname_r None
getgrent getgrent_r None
getgrgid getgrgid_r None
getgrnam getgrnam_r None
gethostbyaddr gethostbyaddr_r jdeGetHostByAddr_r
gethostbyname gethostbyname_r jdeGetHostByName_r
gethostent gethostent_r None
getlocale getlocale_r None
getlogin getlogin_r None
getnmtent getmntent_r None
getnetbyaddr getnetbyaddr_r None
getnetbyname getnetbyname_r None
getnetent getnetent_r None
getprotobyname getprotobyname_r jdeGetProtoByName_r
getprotobynumber getprotobynumber_r None
getprotoent getprotoent_r None
getpwent getpwent_r None
getpwnam getpwnam_r None
getpwuid getpwuid_r None
getservbyname getservbyname_r None
getservbyport getservbyport_r None
getservent getservent_r None
getspwaid getspwaid_r None
getspwnam getspwnam_r None
getspwuid getspwuid_r None
getusershell getusershell_r None
getutent getutent_r None
getutid getutid_r None
getutline getutline_r None
gmtime gmtime_r jdeGmtime
inet_ntoa inet_ntoa_r jde_inet_ntoa_r
jrand48 jrand48_r None
l64a l64a_r None
lcong48 lcong48_r None
localtime localtime_r jdeLocaltime

Note: The parameters changed on this due to the need to send a location to store the value. The standard C call stores it in a global static variable, which is not threadsafe.

lrand48 lrand48_r None
ltoa ltoa_r None
ltostr ltostr_r None
mrand48 mrand48_r None
nrand48 nrand48_r None
ptsname ptsname_r None
pututline pututline_r None
rand rand_r jdePPRand

Note: Must be used in conjunction with jdePPSRand to seed the random number generator correctly. Existing calls to srand should be replaced with jdePPSRand.

readdir readdir_r None
seed48 seed48_r None
setgrent setgrent_r None
sethostent sethostent_r None
setkey setkey_r None
setlocale setlocale_r jdeSetLocale
setnetent setnetent_r None
setprotoent setprotoent_r None
setpwent setpwent_r None
setservent setservent_r None
setspwent setspwent_r None
setusershell setusershell_r None
setutent setutent_r None
srand srand_r jdePPSRand
srand48 srand48_r None
strerror strerror_r None
strtoacl strtoacl_r None
strtoaclpatt strtoaclpatt_r None
strtok strtok_r None
ttyname ttyname_r None
ultoa ultoa_r None
ultostr ultostr_r None
utmpname utmpname_r None
wcstok wcstok_r None

3.7.4.4 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"

Argument Usage
--F<C source file> Use to check a single C source file, for example, --F c:\test\b1234.c
--I<Header file> Use to check a single header file, for example, --I c:\include\b1234.h
--FD<C source directory> Use to check all C source files in a given directory, for example, --FD c:\my project\source.

Note: Do not include a trailing slash as part of the directory argument.

--ID<Header file directory> Use to check all header files in a given directory, for example --ID c:\my project\include

Note: Do not include a trailing slash as part of the directory argument.

--P<Project file> Use to create a text file that contains a list of files, each of which will be scanned by Safety Check. The project file should contain multiple lines of the form: SOURCE=<fully qualified file name>

Note: Do not use quotation marks in the project file.

For example, a project file that specifies three files to scan could look like this:

SOURCE=c:\my project\source\b1111.c

SOURCE=c:\my project\source\b2222.c

SOURCE=c:\my project\include\main.h

--csv Use to produce output in a comma-delimited format. The output will contain these elements:
  • File (the fully qualified file name)

  • Line (the line number of the erroneous code)

  • Global (1 if a global was found, 0 if not.)

  • Static (1 if a static was found, 0 if not.)

  • Extern (1 if an external declaration was found, 0 if not.)

  • API (1 if a non-threadsafe API was found, 0 if not.)

  • BraceMismatch (1 if scanning could not complete due to a brace mismatch)

  • Exception (1 if an exception comment was found, 0 if not.)

  • CouldNotOpen (1 if the file could not be opened, 0 if it could.)

  • NotCSource (1 if the file name did not end in either ".c" or ".h")

  • C++Comment (1 if a C++ style comment was found)

  • CapInclude (1 if a capital letter was used in a #include)

  • LastChar (1 if the last character was not a new line character)

  • CommentInComment (1 if a comment was found inside a comment)

--X Select to print a warning message when a file to check is specified that does not end in "c" or "h". By default, these warning messages are hidden.

3.7.4.5 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".

3.7.4.6 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.

3.7.5 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.

3.8 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.

3.8.1 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.

3.8.2 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.

3.8.3 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.

3.9 Configuring the B98ORCH Business Function to Invoke an Orchestration or Notification (Release 9.2.3)

This section contains the following topics:

3.9.1 Prerequisites

Make sure communication is enabled between the EnterpriseOne Enterprise Server and the AIS Server. See "Configuring the AIS Server with an EnterpriseOne Enterprise Server" in the JD Edwards EnterpriseOne Application Interface Services Server Reference Guide.

3.9.2 Understanding B98ORCH

Use the B98ORCH business function to invoke an EnterpriseOne orchestration or notification automatically from an EnterpriseOne interactive application or batch application. Orchestrations and notifications are created in the Orchestrator Studio, typically by a business analyst, to automate manual business processes.

You can configure the following items in EnterpriseOne to invoke B98ORCH:

  • Named event rule

  • Application event rules

  • Report or UBE event rules

  • Business function

  • Table trigger event rules

B98ORCH calls orchestrations and notifications that execute on the AIS Server, a server that provides a JSON over REST interface to enable communication from calling clients to the EnterpriseOne HTML Server. Data passed from B98ORCH is converted to JSON in order to interface with orchestrations and notifications on the AIS Server. Optionally, you can map full JSON payloads in and out of B98ORCH.

B98ORCH supports asynchronous or synchronous processing. By default, B98ORCH calls an orchestration or notification asynchronously, without waiting for a response. You can enable B98ORCH for synchronous processing if expecting a response from a completed orchestration or notification. Calls to B98ORCH from a report or UBE always process synchronously, even if B98ORCH is configured for asynchronous processing.

3.9.3 Runtime Architecture for Calling B98ORCH

How B98ORCH invokes an orchestration or notification depends on how it is called:

  • If called directly from an event rule in an interactive application, B98ORCH is executed on the HTML Server, where it calls the orchestration or notification on the AIS Server associated with the HTML Server.

  • If called from a business function, a server-side named event rule, or a report, B98ORCH is executed on the Enterprise Server, where it calls the orchestration or notification on the AIS Server associated with the Enterprise Server.

Figure 3-4 depicts the architecture for both of these scenarios.

Figure 3-4 Runtime Architecture for Calling B98ORCH

This image is described in surrounding text.

3.9.4 Configuring B98ORCH

You can map up to 20 inputs and outputs in B98ORCH. Outputs are supported only when the business function is set for synchronous processing. If name-value pairs are passed to the inputs of the business function, then the input JSON is ignored.

The following table describes parameters in the B98ORCH data structure that you need to configure to specify the orchestration or notification to invoke and define the expected inputs and outputs:

Parameter Value
Name_FUNCNM Enter the name of the orchestration or notification to invoke. Maximum characters is 255. You can also enter the UDO name of the orchestration or notification.
Type_WOTYP Specify the object type being called. Enter ORCH for orchestration or NTF for notification.
InputType_ACTYP Future use. Do not use.
OutputType_ACTYP Future use. Do not use.
WaitForResponse_ER066 Complete this parameter to specify asynchronous or synchronous processing. Valid values are:
  • 0 or blank for asynchronous processing.

  • 1 for synchronous processing.

    Use synchronous processing if you are configuring B98ORCH with output mappings for the orchestration or notification response.

<Error flag> This is a return value. If a failure occurs during B98ORCH processing, a value of 1 is returned.
InputString_REPTEXT A JSON string that is the input of the orchestration. Maximum characters is 3200.
Use the next 20 parameters as needed to define the name-value pairs for input mappings:

NameX_ENTRNM

ValueX_TSTRING

For NameX_ENTRNM, enter the name for the input name-value pair. Maximum characters is 50.

ValueX_TSTRING is for passing the value for the name-value pair. Maximum characters is 200.

OutputString_REPTEXT A JSON string that is the output of the orchestration, if executing synchronously.
Use the next 20 parameters as needed to define name-value pairs for output mappings:

OutNameX_ENTRNM

OutValueX_TSTRING

For OutNameX_ENTRNM, enter the name for the output name-value pair. Maximum characters is 50.

OutValueX_TSTRING is for passing the value for the name-value pair. Maximum characters is 200.


3.9.5 B98ORCH Design Considerations

When you configure B98ORCH to call an orchestration or notification from an EnterpriseOne event, there are many factors to consider to ensure that the process completes successfully with little or no impact to performance. Some of the considerations listed here are no different than if you were designing a business function for a custom application.

Understand the action that the orchestration or notification performs

Is the notification set to Run as Subscriber? If so, be aware of impacts when calling a notification that is set to "Run as Subscriber." See Planning for "Run As Subscriber" and "Allowing Subscriber Overrides" in the JD Edwards EnterpriseOne Tools Notifications Guide.

Is the orchestration performing updates or deletes? Is it calling a UBE and waiting for it to complete? These operations take time and have the potential to lock database records.

Consider the event from where you call an orchestration or notification

If you call an orchestration or notification from an event rule, consider how many times the event is executed. Do you want to call the orchestration or notification every time or do you need to condition the call?

If called from a table trigger, to avoid recursion and locking, it is recommended that you run it asynchronously. Recursion and locking can happen on update or delete operations on existing records if the trigger on a table calls an orchestration that attempts to update the same record in the table.

Consider the performance impact of a UBE designed to invoke an orchestration repeatedly. For example, if you have a UBE configured to invoke an orchestration hundreds of times to update hundreds of records, expect a marginally longer processing time. The time the system takes to complete each transaction is no different, but the overhead for each orchestration invocation (100 milliseconds per invocation at a minimum) should be considered. You should determine the actual runtime of your orchestration to understand the impact of calling the orchestration repeatedly during the report execution.

Orchestrations invoked from a UBE always runs synchronously, regardless of whether the B98ORCH parameter is set for synchronous or asynchronous processing.

Design considerations for avoiding time-outs

If a trigger on a table calls B98ORCH configured for synchronous processing, the table operation may time out, which will cause the operation to fail, and potentially roll back the transaction.

Important:

If a transaction times out or fails, it is important to note that even though the transaction might be rolled back, the operation performed by the orchestration is not rolled back.

If an orchestration launches a UBE, it has to wait for the UBE to complete before proceeding to the next step. Because of the time it can take for a UBE to process, it is likely that the session between the calling client and the AIS Server or the session between the AIS Server and HTML Server will time out. Therefore, the recommendation is to call an orchestration asynchronously, especially if the orchestration is designed to launch a UBE.

Make sure that the recommended timeout settings for the servers in an EnterpriseOne with AIS Server architecture are set properly. See "Timeout Settings" in the JD Edwards EnterpriseOne Tools Security Administration Guide for details.

3.9.6 Security Considerations for Invoking Orchestrations and Notifications from B98ORCH

When invoked, B98ORCH uses the credentials of the EnterpriseOne user to establish the AIS Server session and invoke the orchestration or notification. The EnterpriseOne user must have UDO view security for the orchestration or notification called by B98ORCH.

It is recommended that you use roles to establish UDO view security for orchestrations and notifications called by B98ORCH. All components associated with an orchestration are managed as separate UDOs, therefore you must associate the orchestration and all its components to the same role. For example, if you use B98ORCH to launch an orchestration from a table trigger, for security purposes, you need to associate the orchestration and all its components to the same role allowed to update the table.