1. ® IBM Software Group © 2006 IBM Corporation EGL Programming – Built-in Function Libraries and System Variables These slides walk you through terms, concepts and show examples of EGL Built-In Function Libraries (StrLib, J2EELib, DateTimeLib, MathLib, etc.) used for developing business applications and doing common, low-level programming tasks.

2. 2 UNIT The EGL Programming Model – Terms/Concepts EGL Data Parts and Assignment Statements EGL Conditional and Looping Statements The EGL Built-in Functions and Date Math Topics: Programming in EGL

3. 3 EGL Built-in Function Libraries EGL provides a comprehensive group of Built-In Function libraries and system variables used to simplify common programming tasks. See slide ***Notes The Built-in Functions are organized in libraries, some of which include: sysLib – a group of general-purpose run-time functions and sub-routines sysVar – a set of system variables, automatically updated by run-time events strLib – a library of string handling functions – including many useful data type formatting options sqlLib – a library of functions you would use with relational database access MathLib – a library of common mathematical and scientific equations JavaLib – a library of routines to call external Java classes and methods J2EELib – a library of routines to manipulate the J2EE server objects: Session and Request LOBLib – a library of routines to manipulate BLOB and CLOB data DateTimeLib – a library of calls for date and time math and manipulation The product help describes the Built-In Function libraries extremely well. Also, you can (and should) use Content Assist whenever you are coding to the Built-In Function API. There are several hundred functions in total – attempting to cover that many would be daunting. So while its true that any Built-in Function you need (to handle a requirement) is the most important – well limit ourselves to commonly used functions that seem to be popular with developers

4. 4 EGL strLib Functions strLib allows you to manipulate char/mbchar/unicode and String variables. Essential functions from strLib include: The format functions: formatDate, formatTime, formatNumber – returns a string format of a date, time, or numeric value, note that you can apply a custom mask to the result Clip – removes leading/trailing blanks and nulls from values getNextToken – returns a delimited value from a string. upperCase/lowerCase – changes the alpha case to upper or lower in a variable characterLen – returns the # of alpha-numeric characters in a string (excluding leading/trailing blanks and nulls – no example shown)

5. 5 EGL dateTimeLib Functions There are so many useful DateTimeLib functions its a challenge to list or sub-set them. So instead, do an EGL Help search on: EGL library dateTimeLib From the table that results click on a few of the dateTimeLib functions to have a look at their detail use – and note the examples. We will do an extensive workshop with Date arithmetic using many of these functions in a minute.

6. 6 EGL mathLib Functions Mathlib contains most of the scientific and engineering functions required by any sort of computing application. Among the more commonly used business functions are: Pow Sqrt Round

7. 7 EGL sysLib Functions Syslib contains a large number of extremely useful functions. Please visit the HELP system and view its contents. Among the more commonly used business functions from sysLib are: Commit/rollback setError(msg) Size( ) bytes( ) bytes( ) – allows you find the size (in bytes) of any variable of any type, including an EGL record, etc. callCmd() callCmd() – allows you to execute an Operating System level command (like FTP, copy, etc.). startCmd() is a similar and useful function. Two other very useful functions: 1.getMessage (…) 2.getProperty(…)

8. 8 EGL vgLib Functions vgLib while, mostly available for VAGEN to EGL backwards compatibility, vgLib contains a few extremely useful functions. Please visit the HELP system and view its contents. Among the more commonly used business functions from vgLib are: compareBytes(…) – compares variable byte positions irrespective of data type. Note the following example that is looking at byte 1 of a field within a record for low-values (x00) – which is the value of an EGL Hex variable. setSubStr(…) – can be used to set values in variables or records, irrespective of type. Consider – you need to set every byte in a record to low-values (x00) – or to the letter A – as shown in this example:.

9. 9 EGL J2EELib – Application Server Variables J2EELib allows you to retrieve user authentication values, as well as to set, get and clear three types of application server-maintained state-management variables: 1.Request – variables set from page-to-page 2.Session – variables that persist for the duration of a users access to your application 3.Application – a global variable that is available across all EGL Logic Parts running in the App Server The syntax for setting and getting is based on a key (of type string) – that can set or return any EGL type – including records and arrays: j2eeLib.getSessionAttr( key STRING in, value ANY in)

10. 10 EGL sysVar – System Variables SysVar stores and carries values useful for your application, and makes them accessible as an API call. Many of the variable values are primarily useful in TUI (character-based screen) applications. Two of the more generally useful APIs include: arrayIndex overFlowIndicator

11. 11 Date and Time Math – in EGL EGL date handling has 4 elements: 1. Date data type – which weve seen so far: myDate date {dateFormat = yyyyMMdd}; 2. Timestamp data type – which weve seen but havent used much myTimeStamp timestamp; Timestamps are necessary for certain date manipulation routines 3. dateTimeLib EGL built-in library functions – just covered 4. INTERVAL data type – used to represent a calendar duration Intervals are declared as strings with mask characters: Years – y, Months – M, Days – d And if needed hours/minutes/seconds/micro-seconds – hhmmss You declare an interval and give it a mask that dictates the range of the date duration it holds – and you can optionally initialize the Interval. Examples: twoYears Interval ("yy") = "02"; //holds 0 – 99 years. Initialized to 2 years nineMonths Interval ("MM") = "09"; //holds 0 – 99 months. Initialized to 9 months twoYears9Mths Interval ("yyMM") = "0209"; //up to 99 years + 99 months. Initialized to 2 years 9 months twoYears1Mth Interval ("yyMM") = "0201"; //up to 99 years + 99 months. Initialized to 2 years and 1 month.

12. 12 Date and Time Math – Adding Days, Months and Years You can add days, months, years or any combination. 1. Add Days by adding an integer number; dateIn = dateIn + 90; //add 90 days to a given date 2. Add months as follows: Declare an Interval with a month mask and give it a value monthIntInterval (MM) = 03; //3 months Add the interval to the date dateIn = dateIn + monthInt; 3. Add years as follows: Declare an Interval with a year mask and give it a value yearIntInterval (yy) = 08; //8 years Add the interval to the date dateIn = dateIn + yearInt; 3. Add years and months as follows: Declare an Interval with a year mask and give it a value yearMonthIntInterval (yyMM) = 0209; //2 years 9 months Add the interval to the date dateIn = dateIn + yearMonthInt;

13. 13 Date and Time Math – Subtracting Days, Months and Years You can subtract days, months, years or any combination. 1. Subtract days by subtracting an integer number; dateIn = dateIn - 90; //subtract 90 days from a given date 2. Subtract months as follows: Declare an Interval with a month mask and give it a value monthIntInterval (MM) = 03; //3 months Subtract the interval to the date dateIn = dateIn - monthInt; 3. Subtract years as follows: Declare an Interval with a year mask and give it a value yearIntInterval (yy) = 08; //8 years Subtract the interval from the date dateIn = dateIn - yearInt; 3. Subtract years and months as follows: Declare an Interval with a year mask and give it a value yearMonthIntInterval (yyMM) = 0209; //2 years 9 months Subtract the interval from the date dateIn = dateIn - yearMonthInt; 4. Subtract dates – giving an integer number of days between daysDiff int = currDate – DateIn; //results in an integer

14. 14 Date and Time Math – Working With Time and Timestamp Values You can add and subtract time and timestamp values, but youll need to understand the results of such expressions – and the allowable types for each calculation. The product help does an excellent job of describing the options (see chart) Note from this chart the following: Subtracting dates yields an integer number of days difference To perform calculations with time and timestamp results, you will need to convert your input dates or times to timestamps (assuming the input values are not already timestamps) The EGL built-in functions to do this are the following: - timeStampValueWithPattern() - timeStampFrom() - timeStampValue() You can look up the exact syntax for these expressions in the help. ***Notes See the slide ***Notes for some examples of time/timestamp calculations.

15. 15 Date and Time Math – Obtaining Months and Years Difference Between Dates Notes Because of the way Interval currently works, in order to calculate the difference between two dates in months or years you need to custom code a function like this (see example – and the code for this (along with a test-calling function) is embedded in the Notes for this slide) Temp variables Setup the subtraction Subtract years …and months Adjust for partial years and months

16. 16 Date and Time Math – Miscellaneous Topics 1. The default formats for an interval mask are (either / or): Year/Month format: yyyyMM – or any combination Days/Hours format: ddHHmmssffffff - or any combination not But you can not combine the two formats above Cant declare a mask of: yyMMdd ; And you cannot leave out intermediate characters (from the days format) 2. The default EGL Timestamp does not value the micro-seconds portion of the variable (you just get 000000). So if you want EGL to create new variables with valid micro-second values, do the following: aTS timeStamp ("yyyyMMddHHmmssffffff"); aTs = dateTimeLib.currentTimeStamp(); dateTimeLib.dateValueFromGregorian(…); 3. Many System i users store date values as Decimal(8,0) – as this is efficient from a system storage perspective. To convert these numeric values into EGL date variables use: dateTimeLib.dateValueFromGregorian(…); dateVar date {dateFormat = yyyy/MM/dd}; //declare your date variable dateVar = datetimelib.dateValueFromGregorian( ); ISOFormatEURFormat USAFormat 4. The valid date and timestamp formats include any of the legal Java date format mask characters (see the Help system for a comprehensive list). Note that EGL offers enumerated formats: ISOFormat, EURFormat, USAFormat, etc. and the ability to create your own custom formats. Common custom examples include:

17. 17 Date and Time Math – Miscellaneous Topics – Date Validation Routine You may – at some point, need to test input data for valid dates … okay – not just at some point frequently - as this is a common business programming concern The bad news is that there currently is no isValidDate() EGL built-in library function try/onException But the good news is that you can combine try/onException with built-in function calls hello3.jsp Heres an example, implemented using hello3.jsp You can use the code in a program …or… create a JSFHandler and page to test it out …or… test it out using one of your hello.jsp pages.

18. 18 Built-in Functions Workshops – 1 of 5 Test your knowledge of the EGL Built-in Functions and Date Arithmetic by doing the following workshop: builtInFunctionTest.egl 1. Create a new, main program in the \programs\ folder, named: builtInFunctionTest.egl 2. Remove the standard program boilerplate and replace it with the following variables and main() function calls: Note – You can find copy/paste source in the slide notes (below) Note – You can find copy/paste source in the slide notes (below)

19. 19 Built-in Functions Workshops – 2 of 5 strLib 3. Create the function shown here that exercises several of the strLib APIs – either by Using Content Assist …or… Copy/pasting in source code (in the notes section below) If you decide to copy/paste at a minimum change some of the string literals (except, not myFormat – unless you use Content Assist to select a different Date format) After you have added this function: Return to the main() function and uncomment the call to this function (OPTIONALLY) Debug the program and the code in this function (Dont forget to add a break-point!!!)

20. 20 Built-in Functions Workshops – 3 of 5 dateTimeLib 4. Create the function shown here that exercises several of the dateTimeLib APIs – either by Using Content Assist …or… Copy/pasting in source code (in the notes section below) If you decide to copy/paste at a minimum try changing the value of newDate in the Global Data area of the program After you have added this function: Return to the main() function and uncomment the call to this function (OPTIONALLY) Debug the program and the code in this function.

21. 21 Built-in Functions Workshops – 4 of 5 mathLib and sysLib and sysVar 5. Create the function shown here that exercises several of the mathLib and sysLib and sysVar APIs – either by Using Content Assist …or… Copy/pasting in source code (in the notes section below) If you decide to copy/paste at a minimum change the value of the literal (numbers) in the APIs. After you have added this function: Return to the main() function and uncomment the call to this function (OPTIONALLY) Debug the program and the code in this function.

22. 22 *** EXTRA CREDIT *** If time remains, return to the slide titled: Date and Time Math – Obtaining Months and Years Difference Between Dates Notes builtInFunctionTest.egl - Copy/Paste the code from the Notes section into your builtInFunctionTest.egl program. Debug - Debug through this new use case Built-in Functions Workshops – 5 of 5 6. Create the function shown here that exercises date arithmetic – both adding and subtracting dates: Using Content Assist …or… Copy/pasting in source code (in the notes section below) If you decide to copy/paste at a minimum change the value of the literal (numbers) in the Intervals or dates in the Global Data area. After you have added this function: Return to the main() function and uncomment the call to this function (OPTIONALLY) Debug the program and the code in this function.

23. 23 Copy Existing Build File Values – 1 of 4 ***Notes Now that we have both batch and web (J2EE) programs in your project, we should probably have separate EGL Build Files dedicated to supporting them (see ***Notes). Please do the following: 1.From the Project Explorer, - Right-click over EGLWeb.eglbld and select: - Open With > Text Editor 2. From inside the file: Press Ctrl/A (to select all) …then Ctrl/C (to copy all selected) 3. Close the build file

24. 24 Add a Batch Program Buildfile to Your Project – 2 of 4 Next you need to create a new EGL build file, and paste the copied entries into it: \EGLSource\ 1. From Project Explorer, right-click over \EGLSource\ and select: New Other… EGL Build File Expand EGL and select: EGL Build File batchBuildFile From the next wizard, name the file: batchBuildFile 2. Close the new build file (you need to re-open, and edit it in Text Editor mode) batchBuildFile 3. Reopen batchBuildFile using the Text Editor (Ctrl/V) 4. Paste (Ctrl/V) the contents of your copied EGLWeb.eglbld (from the last slide) 5. Change the following entries in the file: name=BatchBuildOptions J2EE=NO Ctrl/S 6. Save your changes (Ctrl/S) and close the file

25. 25 Assign the batchBuildFile to Your Programs Folder – 3 of 4 Now you will assign (or associate) the new batchBuildFile with the \programs\ directory. \programs\ 1. From Project Explorer, right-click over \programs\ - under \EGLSource\ and select: Properties Properties (note this option is usually at or near the bottom of the Context Menu) 2. From the EGL Default Build Descriptors, select For both: Target system build descriptor Target system build descriptor Debug build descriptor Debug build descriptor Close the Properties view Close the Properties view

26. 26 Regenerate the Project – 4 of 4 Finally, you should try to re-Generate your application, with the new build files, to ensure that your project settings are correct. First ensure that your EGLWeb project default build file setting is: j2ee=YES EGLWeb.eglbld 1.From Project Explorer open EGLWeb.eglbld with the EGL Build Parts Editor 2. From the Build parts editor, find the j2ee option, and set it to: YES (its a ComboBox) Generate 3. From Project Explorer, right-click over your Project, and select Generate Congratulations. You now have a project configured with build files to generate: Congratulations. You now have a project configured with build files to generate: Batch resources – all.EGL files in the \programs\ directory Batch resources – all.EGL files in the \programs\ directory J2EE/Web resources – everything else in your project (using the default build file settings) J2EE/Web resources – everything else in your project (using the default build file settings)

27. 27 (OPTIONAL) Calling Operating System Commands Many applications require you to call Windows, or AIX/UNIX, etc. native operating system functions. Ex: Copy files, FTP a file, Launch a process, etc. Ex: Copy files, FTP a file, Launch a process, etc. This is easy to do with these EGL built-in functions: This is easy to do with these EGL built-in functions: SysLib.startCmd() SysLib.startCmd() launch an Operating System function asynchronously (i.e. in parallel with your EGL program) Syslib.callCmd() Syslib.callCmd() launch an Operating System function, wait for it to finish, then continue with your EGL program BatchProcess.JSPPage Copy a file FTP a file

28. 28 (OPTIONAL) Calling Operating System Commands - Lab \programs\ From the \programs\ package, right-click, and create a new, EGL program, named: callcmdPgm ***Notes Replace the boiler-plate code with the EGL statements in the ***Notes section of this slide Save/Generate and Debug your program: During Debug, when an O.S. command is executed, a DOS window will appear (see below) In this workshop, the copy statement is going to try and copy a file in the c:\temp directory. In order for this to actually work, youll have to create such a directory, and create or copy a file into it. When the callCmd(notepad.exe); statement is launched, you will have to close Notepad (recall why, from the text on the previous slide)

29. 29 (OPTIONAL) Running EGL-Called Operating System Commands The v7.1 Debugger has been setup to make some specific Java.JAR files part of your PCs PATH environment variable. So - you can debug the program code you just wrote, but not Run (which you very well would want to do say, if you went into production ) So you will need to modify the Java Build Path by following the instructions below: Modify/Extend the Java Build Path not Note: If calling the startCmd() or callCmd() built-in functions from a web page you do not have to do this. batch However, there is a requirement when running either startCmd() or callCmd() from an EGL generated Java batch application that you add the \bin\ directory – from of your product installation directory to the Java build path. Here are the steps to do this: Control Panel From the Start menu, select Control Panel System System Advanced – and on the Advanced tab, click: Environment Variables Advanced – and on the Advanced tab, click: Environment Variables In the System variables window, scroll down and select: Path, and click Edit In the System variables window, scroll down and select: Path, and click Edit Add the \bin; to the end of the Variable value Add the \bin; to the end of the Variable value Restart the workbench (restart RBD or RDz or RDi) Restart the workbench (restart RBD or RDz or RDi)

30. 30 Now that you have completed this topic, you should be able to: List the different types of EGL Built-in Libraries Describe at least 10 of the EGL Built-in Library Functions Define the purpose of an EGL build-file Create a build-file used for Batch Programs Assign a project resource (like a file program or package) to a default build-file Open a Build-file in either text or EGL build-file editor mode Topic Summary Summary