This chapter contains the following topics:
Variables and data structures must be defined and initialized before they can be used to store data. This chapter describes how to declare and initialize them. It includes topics on using define statements, using typedef, creating function prototypes, initializing variables, initializing data structures, and using standard variables.
A define statement is a directive that sets up constants at the beginning of the program. A define statement always begins with a pound sign (#). All business functions include the system header file: jde.h. System-wide define statements are included in the system header file.
If you need define statements for a specific function, include the define statement in uppercase letters within the source file for the function whenever possible. The statement should directly follow the header file inclusion statement.
Usually, you should place define statements in the source file, not the header file. When placed in the header file, you can redefine the same constant with different values, causing unexpected results. However, rare cases exist when it is necessary to place a define statement in the function header file. In these cases, precede the definition name with the business function name to ensure uniqueness.
This example includes define statements within a business function source file:
/************************************************************* * Notes *************************************************************/
#include <bxxxxxxx.h>
/************************************************************* * Global Definitions *************************************************************/ #define CACHE_GET '1' #define CACHE_ADD '2' #define CACHE_UPDATE '3' #define CACHE_DELETE '4'
This example includes define statements within a business function header:
/********************************************************** * External Business Function Header Inclusions **********************************************************/ #include <bxxxxxxx.h> /********************************************************** * Global definitions **********************************************************/ #define BXXXXXXX_CACHE_GET '1' #define BXXXXXXX_CACHE_ADD '2' #define BXXXXXXX_CACHE_UPDATE '3' #define BXXXXXXX_CACHE_DELETE '4'
When using typedef statements, always name the object of the typedef statement using a descriptive, uppercase format. If you are using a typedef statement for data structures, remember to include the name of the business function in the name of the typedef to make it unique. See the example for using a typedef statement for a data structure.
This is an example of a user-defined data structure:
/**************************************************************
* Structure Definitions
**************************************************************/
typedef struct
{
HUSER hUser; /** User handle **/
HREQUEST hRequestF0901; /** File Pointer to the
* Account Master **/
DSD0051 dsData; /** X0051 - F0902 Retrieval **/
int iFromYear; /** Internal Variables **/
BOOL bProcessed;
MATH_NUMERIC mnCalculatedAmount;
JCHAR szSummaryJob[13];
JDEDATE jdStartPeriodDate;
} DSX51013_INFO, *LPDSX51013_INFO;
Refer to these guidelines when defining function prototypes:
Always place function prototypes in the header file of the business function in the appropriate prototype section.
Include function definitions in the source file of the business function, preceded by a function header.
Ensure that function names follow the naming convention defined in this guide.
Ensure that variable names in the parameter list follow the naming convention defined in this guide.
List the variable names of the parameters along with the data types in the function prototype.
List one parameter per line so that the parameters are aligned in a single column.
Do not allow the parameter list to extend beyond 80 characters in the function definition. If the parameter list must be broken up, the data type and variable name must stay together. Align multiple-line parameter lists with the first parameter.
Include a return type for every function. If a function does not return a value, use the keyword void as the return type.
Use the keyword void in place of the parameter list if nothing is passed to the function.
This is an example of a standard business function prototype:
/*****************************************************************
* Business Function: BusinessFunctionName
*
* Description: Business Function Name
*
* Parameters:
* LPBHVRCOM lpBhvrCom Business Function Communications
* LPVOID lpVoid Void Parameter - DO NOT USE!
* LPDSD51013 lpDS Parameter Data Structure Pointer
*
*****************************************************************/
JDEBFRTN (ID) JDEBFWINAPI BusinessFunctionName (LPBHVRCOM lpBhvrCom,
LPVOID lpVoid,
LPDSXXXXXX lpDS)
This is an example of a standard internal function prototype:
Type XXXXXXXX_AAAAAAAA( parameter list ... ); type : Function return value XXXXXXXX : Unique source file name AAAAAAAA : Function Name
This is an example of a standard external business function definition:
/*
* see sample source for standard business function heading
*/
JDEBFRTN (ID) JDEBFWINAPI GetAddressBookDescription(LPBHVRCOM lpBhvrCom,
LPVOID lpVoid,
LPDSNNNNNN lpDS)
{
ID idReturn = ER_SUCCESS;
/*--------------------------------------------------------------
* business function code
*/
return idReturn;
}
This is an example of a standard internal function definition:
/*-----------------------------------------------------------------------
* see sample source for standard function header
*/
void I4100040_GetSupervisorManagerDefault( LPBHVRCOM lpBhvrCom,
LPSTR lpszCostCenterIn,
LPSTR lpszManagerOut,
LPSTR lpszSupervisorOut )
/*-----------------------------------------------------------------------
* Note: b4100040 is the source file name
*/
{
/*
* internal function code
*/
}
Variables store information in memory that is used by the program. Variables can store strings of text and numbers.
When you declare a variable, you should also initialize it. Two types of variable initialization exist: explicit and implicit. Variables are explicitly initialized if they are assigned a value in the declaration statement. Implicit initialization occurs when variables are assigned a value during processing.
This information covers standards for declaring and initializing variables in business functions and includes an example of standard formats.
Use these guidelines when declaring and initializing variables:
Declare variables using this format:
datatype variable name = initial value; /* descriptive comment*/
Declare all variables used within business functions and internal functions at the beginning of the function. Although C allows you to declare variables within compound statement blocks, this standard requires all variables used within a function to be declared at the beginning of the function block.
Declare only one variable per line, even if multiple variables of the same type exist. Indent each line three spaces and left align the data type of each declaration with all other variable declarations. Align the first character of each variable name (variable name in the preceding format example) with variable names in all other declarations.
Use the naming conventions set forth in this guide. When initializing variables, the initial value is optional depending on the data type of the variable. Generally, all variables should be explicitly initialized in their declaration.
The descriptive comment is optional. In most cases, variable names are descriptive enough to indicate the use of the variable. However, provide a comment if further description is appropriate or if an initial value is unusual.
Data structures should be initialized to zero using the memset function immediately after the declaration section.
Some Application Program Interfaces (APIs), such as the JDB ODBC API, provide initialization routines. In this case, the variables intended for use with the API should be initialized with the API routines.
Always initialize pointers to NULL and include an appropriate type call at the declaration line.
Initialize all variables, except data structures, in the declaration.
Initialize all declared data structures, MATH_NUMERIC, and JDEDATE to NULL.
Ensure that the byte size of the variable matches the size of the data structure you want to store.
This example shows how to initialize variables:
JDEBFRTN (ID) JDEBFWINAPI F0902GLDateSensitiveRetrieval
(LPBHVRCOM lpBhvrCom,
LPVOID lpVoid,
LPDSD0051 lpDS)
/****************************************************************
* Variable declarations
***************************************************************/
ID idReturn = ER_SUCCESS;
JDEDB_RESULT eJDEDBResult = JDEDB_PASSED;
long lDateDiff = 0L;
BOOL bAddF0911Flag = TRUE;
MATH_NUMERIC mnPeriod = {0};
/****************************************************************
* Declare structures
***************************************************************/
HUSER hUser = (HUSER) NULL;
HREQUEST hRequestF0901 = (HREQUEST) NULL;
DSD5100016 dsDate = {0};
JDEDATE jdMidDate = {0};
/****************************************************************
* Pointers
***************************************************************/
LPX0051_DSTABLES lpdsTables = (LPX0051_DSTABLES) 0L;
/****************************************************************
* Check for NULL pointers
**************************************************************/
if ((lpBhvrCom == (LPBHVRCOM) NULL) ||
(lpVoid == (LPVOID) NULL) ||
(lpDS == (LPDSD0051) NULL))
{
jdeErrorSet (lpBhvrCom, lpVoid, (ID) 0,
_J(4363), (LPVOID) NULL);
return ER_ERROR;
}
/**************************************************************
* Main Processing
**************************************************************/
eJDEDBResult = JDB_InitBhvr ((void*)lpBhvrCom,
&hUser,
(JCHAR *) NULL,
JDEDB_COMMIT_AUTO);
memcopy ((void*)) &dsDate.jdPeriodEndDate,
(const void*) &lpDS->jdGLDate, sizeof(JDEDATE));
When writing to the table, the table recognizes these default values:
Space-NULL if string is blank
0 value if math numeric is 0
0 JDEDATE if date is blank
Space if character is blank
Always memset to NULL on the data structure that is passed to another business function to update a table or fetch a table.
This example resets the data structure to NULL when initializing the data structure:
bOpenTable = B5100001_F5108SetUp( lpBhvrCom, lpVoid,
lphUser, &hRequestF5108);
if ( bOpenTable )
{
memset( (void *)(&dsF5108Key), 0x00, sizeof(KEY1_F5108) );
jdeStrcpy( (JCHAR*) dsF5108Key.mdmcu,
(const JCHAR*) lpDS->szBusinessUnit );
memset( (void *)(&dsF5108), 0x00, sizeof(F5108) );
jdeStrcpy( (JCHAR*) dsF5108.mdmcu,
(const JCHAR*) lpDS->szBusinessUnit );
MathCopy(&dsF5108.mdbsct, &mnCentury);
MathCopy(&dsF5108.mdbsfy, &mnYear);
MathCopy(&dsF5108.mdbtct, &mnCentury);
MathCopy(&dsF5108.mdbtfy, &mnYear);
eJDEDBResult = JDB_InsertTable( hRequestF5108,
ID_F5108,
(ID)(0),
(void *) (&dsF5108) );
}
This section discusses how to:
Use flag variables.
Use input and output parameters.
Use fetch variables.
When creating flag variables, use these guidelines:
Any true-or-false flag used must be a Boolean type (BOOL).
Name the flag variable to answer a question of TRUE or FALSE.
These are examples of flag variables, with a brief description of how each is used:
| Flag Variable | Description |
|---|---|
| bIsMemoryAllocated | Apply to memory allocation |
| bIsLinkListEmpty | Link List |
Business functions frequently return error codes and pointers. The input and output parameters in the business function data structure should be named as follows:
| Input and Output Parameter | Description |
|---|---|
| cReturnPointer | When allocating memory and returning GENLNG. |
| cErrorCode | Based on cCallType, cErrorCode returns a 1 when it fails or a 0 when it succeeds. |
| cSuppressErrorMessage | If the value is 1, do not display error message using jdeErrorSet(...). If the value is 0, display the error. |
| szErrorMessageId | If an error occurs, return an error message ID (value). Otherwise, return four spaces. |
Use fetch variables to retrieve and return specific information, such as a result; to define the table ID; and to specify the number of keys to use in a fetch.
| Fetch Variable | Description |
|---|---|
| idJDEDBResult | APIs or JD Edwards EnterpriseOne functions, such as JDEDB_RESULT |
| idReturnValue | Business function return value, such as ER_WARNING or ER_ERROR |
| idTableXXXXID | Where XXXX is the table name, such as F4101 and F41021, the variable used to define the Table ID. |
| idIndexXXXXID | Where XXXX is the table name, such as F4101 or F41021, the variable used to define the Index ID of a table. |
| usXXXXNumColToFetch | Where XXXX is the table name, such as F4101 and F41021, the number of the column to fetch. Do not put the literal value in the API functions as the parameter. |
| usXXXXNumOfKeys | Where XXXX is the table name, such as F4101 and F41021, the number of keys to use in the fetch. |
This example illustrates the use of standard variables:
/****************************************************************
* Variable declarations
**************************************************************/
ID idJDEDBResult = JDEDB_PASSED;
ID idTableF0901 = ID_F0901;
ID idIndexF0901 = ID_F0901_ACCOUNT_ID;
ID idFetchCol[] = { ID_CO, ID_AID, ID_MCU, ID_OBJ,
ID_SUB, ID_LDA, ID_CCT };
ushort usNumColToFetch = 7;
ushort usNumOfKeys = 1;
/***************************************************************
* Structure declarations
****************************************************************/
KEY3_F0901 dsF0901Key = {0}
DSX51013_F0901 dsF0901 = {0}
/***************************************************************
* Main Processing
***************************************************************/
/** Open the table, if it is not open **/
if ((*lpdsInfo->lphRequestF0901) == (HREQUEST) NULL)
{
if ( (*lpdsInfo->lphUser) == (HUSER) 0L )
{
idJDEDBResult = JDB_InitBhvr ((void*)lpBhvrCom,
&lpdsInfo->lphUser,
(JCHAR *) NULL,
JDEDB_COMMIT_AUTO);
}
if (idJDEDBResult == JDEDB_PASSED)
{
idJDEDBResult = JDB_OpenTable( (*lpdsInfo->lphUser),
idTableF0901,
idIndexF0901,
(LPID)(idFetchCol),
(ushort)(usNumColFetch),
(JCHAR *) NULL,
&lpdsInfo->hRequestF0901 );
}
}
/** Retrieve Account Master - AID only sent **/
if (idJDEDBResult == JDEDB_PASSED)
{
/** Set Key and Fetch Record **/
memset( (void *)(&dsF0901Key),
(int) _J('\0'), sizeof(KEY3_F0901) );
jdeStrcpy ((char *) dsF0901Key.gmaid,
(const JCHAR*) lpDS->szAccountID );
idJDEDBResult = JDB_FetchKeyed ( lpdsInfo->hRequestF0901,
idIndexF0901,
(void *)(&dsF0901Key),
(short)(1),
(void *)(&dsF0901),
(int)(FALSE) );
/** Check for F0901 Record **/
if (eJDEDBResult == JDEDB_PASSED)
{
statement
}
}