“A fault confessed is half redressed” – Old English Saying
Trapping errors and providing helpful feedback are a number of those mundane tasks which the developer must, sooner rather than later, come to terms with. Proper error management and recovery remain at the heart of our programming responsibilities, and if applied correctly, will pay out future dividends on the time invested in its appropriation.
One technique available to us is that of substituting a portion of the error notification with text appropriate for the actual setting. For example, we may have a defined glossary text which states: “Error opening table”. When triggered in an application our response to this message may very well be: “Yes but which one?” A more helpful message will be “Error opening table F4211”, immediately pointing us in the right direction. However, we want a generic solution; imagine creating an error message for every single table! Fortunately, E1 provides a suitable solution and we need apply only a little time and effort to get it to work efficiently.
To set up text substitution the following steps are required:
• Create the Error Message with a Substitute Parameter(s)
• Create a Data Structure with Substitution Text Members
• Link the Data Structure to the Error Message
• Write a C Function incorporating the jdeErrorSet API
• Call the Function from an E1 Application
This exercise assumes that you have Visual Studio installed and properly configured in the jde.ini.
Create the Error Message with Substitute Parameter(s)
In P92002 – Work with Glossary Items, define a new error message by clicking Add. In this example we will use error code LL010
Note that the ampersand symbol (“&”) is used in conjunction with numeric values to define the position of the text substitution.
On the Item Glossary tab enter informative information positioning the “&1”, “&2” etc. parameters appropriately:
Note the Data Structure Template tab. This is where we will associate the Error Message with our Data Structure, once we have created it.
Create a Data Structure with Substitution Text Members
In the OMW create a new structure and name it D55E0022. Use AA10, ALPH and PH1 or other valid items. Name them appropriately. These fields will be used to move the actual substitute text segments into the business function, requiring the input/output arrows to point to the right.
The definition of this structure will be pasted into our .h file when we create the C function. The next step is to link this function to our error message.
Link the Data Structure to the Error Message
Back in P92002 select the Data Structure Template tab, click on Text Substitution, then on the Browse button and select D55E0022.
Write a C Function incorporating the jdeErrorSet API
Many of you may never have written a C function in JDE. I will therefore include the basic steps which may serve as an introduction to the topic.
From the OMW create a new C function. Let’s call it B55E0022 with description “Call Error with Text Substitution”. Select “C” as the Source Language and “Client/Server” as the Function Location.
Click OK and select the Design Tools tab. Click on Select Business Functions Design Aid. For the purpose of this demonstration we will name this function “CallErrorWithSub” (no spaces allowed) with description “Call Error with Substitution Text”. Select the row and click the “Parameter” Row Exit:
In the “Select Business Function Parameters” find the D55E0022 structure and select it. Back on the “Business Function Design” screen you will notice that the template name has been added to the definition.
It is time to generate our basic C function files. Click on the Create button in the main toolbar. Select “Yes” on all prompts to ensure that the function skeletons are created. We now have a B55E0022.c and a B55E0022.h file in our Source and Include directories respectively (these will be listed in the path code we are signed into – for this example it is DEMO).
Next, click the Typedef button in the Row Exit. This action will display “Your typedef is in the clipboard”, in the message bar at the bottom of the screen. This “typedef” describes our data structure and needs to be pasted in the .h header file.
Select the row containing the function definition in the grid, and on the Form Exit click Edit. Visual Studio should open and load the .h and .c files. Place your cursor just below this section in the .h file:
Press Ctrl + V to paste the typedef into the header file. The result should be as below:
It is important to understand that the mere association of a data structure with a C function (as achieved in Business Function Design) does not make the parameters available to the source file. One has to define the structure in the .h file as we have done above, for C to “see” it.
Save the .h file.
Now select the source .c file. For the purposes of this exercise we will keep the coding to an absolute minimum, in fact we will add one line to the source file only.
Place the cursor just below the comment Main Processing:
Type in the following line:
jdeErrorSet(lpBhvrCom, lpVoid,(ID)0, _J(“LL010”), lpDS);
Typically you don’t need to worry about the first three parameters and can almost always pass them in the same way.
The fourth and fifth parameters need to be commented on: The “LL010” is the id of the error message we created at the beginning of this exercise. The _J () macro transforms the CHAR data type (i.e. “LL0101”) to the Unicode compliant JCHAR type. The fifth parameter passes the pointer itself i.e. the memory address of our data structure to the jdeErrorSet API. The rest of the work is done by the API – once it obtains the location in memory it will find the various members of our structure and work the segments into the error message.
Save the source file and return to “Business Function Design”. Exit the form if necessary to return to the Design Tools tab. From here build the function; hopefully your output will list 0 errors as below:
Call the Function from an E1 Application
The final step is to test the function – write a simple application using a Fix Inspect form. Add three appropriate data dictionary items to pass values into the B55E0022 function. Attach the function to a Button control, map the values from the form and Bob’s your uncle!
It should be noted that the above type of error message is used primarily in interactive applications (forms) where the E1 runtime engine manages and displays it. Grid and UBE error messages are handled differently.
In conclusion, it is clear that with very little effort, one can enhance E1 application error management. I hope that this exercise illuminates more that it confuses. The C API is huge and knowledge of C programming a requirement to using it effectively. However, a small introduction is better than none, and by studying existing E1 examples things eventually become clear. Learning the ins and outs of pointers, data structures and memory management is essential towards developing a sound technical foundation, since these topics form part of the very core of E1 C Programming.