1 EGL Built-in System Function LibrariesThis section describes how to use the EGL Built-in System Function Libraries (or the APIs) to simplify common programming tasks
2 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 it’s true that any Built-in Function you need (to handle a requirement) is the “most important” – we’ll limit ourselves to commonly used functions that seem to be “popular” with developers Notes: Other libraries include: ServiceLib DLILib ConverseLib VGLib ReportLib ConsoleLib The RBD product help covers these libraries in depth. Not all of the EGL functions are available in all of the platforms. Please consult the EGL Programmer’s Guide for an up-to-date list of what works and what doesn’t work across all run-times.
3 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) Notes:
4 EGL dateTimeLib Functions There are so many useful DateTimeLib functions it’s 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. Notes:
5 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 Notes:
6 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(
7 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 (x”00”) – 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 (x”00”) – or to the letter “A” – as shown in this example: . Notes:
8 EGL J2EELib – Application Server VariablesJ2EELib allows you to retrieve user authentication values, as well as to set, get and clear three types of application server-maintained state-management variables: Request – variables set from page-to-page Session – variables that persist for the duration of a user’s access to your application 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) Notes:
9 EGL sysVar – System VariablesSysVar 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 Notes: In order to enable the overFlowIndicator, you must be in V6 exception compatibility mode, with vgVar.handleOverflow = 0
10 Date and Time Math – in EGL EGL date handling has 4 elements: 1. Date data type – which we’ve seen so far: myDate date {dateFormat = “yyyyMMdd”}; 2. Timestamp data type – which we’ve seen but haven’t 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 twoYears9Mths Interval ("yyMM") = "0201"; //up to 99 years + 99 months. Initialized to 2 years and 1 month. Notes: The date mask characters: (y-year, M-month, d-day) are case-sensitive.
11 Date and Time Math – Adding Days, Months and YearsYou 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 monthInt Interval (“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 yearInt Interval (“yy”) = “08”; //8 years dateIn = dateIn + yearInt; 3. Add years and months as follows: yearMonthInt Interval (“yyMM”) = “0209”; //2 years 9 months dateIn = dateIn + yearMonthInt; Notes:
12 Date and Time Math – Subtracting Days, Months and YearsYou 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 monthInt Interval (“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 yearInt Interval (“yy”) = “08”; //8 years Subtract the interval from the date dateIn = dateIn - yearInt; 3. Subtract years and months as follows: yearMonthInt Interval (“yyMM”) = “0209”; //2 years 9 months dateIn = dateIn - yearMonthInt; 4. Subtract dates – giving an integer number of days between daysDiff int = currDate – DateIn; //results in an integer Notes:
13 Date and Time Math – Working With Time and Timestamp ValuesYou can add and subtract time and timestamp values, but you’ll 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. See the slide ***Notes for some examples of time/timestamp calculations. Notes: Take the difference (in minutes) between two Timestamp values: t1 timestamp; //your input timestamp t2 timestamp; //your other input timestamp mn interval ("mm") = "12"; //used this for testing m interval ("mm"); //the output in minutes function main() t2 = t2 + mn; //Added 12 minutes... m2 = t2 - t1; //…and got 12 minutes back end //Take the difference in days/hours/minutes/etc. Note that with this Interval operation, you can do things like verify that two dates are not more than 24 hours apart, etc. function hoursTest() dt1 timestamp = " "; dt2 timestamp = " "; diff02 INTERVAL ("ddhhmmss"); diff02 = dt2 - dt1;
14 Date and Time Math – Obtaining Months and Years Difference Between DatesBecause 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 Notes: Take the difference (in months and years) between two date values: function calculateDateDifferencesInYearsAndMonths() startDate date; endDate date; years int; // Exactly a year strlib.defaultDateFormat = "yyyyMMdd"; startDate = DateTimeLib.dateValue(" ") as date; endDate = DateTimeLib.dateValue(" ") as date; years = getNumFullYearsAndMonths( startDate, endDate ); writeStdOut( "For date1 of " + startDate + " and date2 of " + endDate + " number full years is " + strLib.formatNumber(years) ); // A year and over a month startDate = DateTimeLib.dateValue(" "); endDate = DateTimeLib.dateValue(" "); // Less than a year startDate = DateTimeLib.dateValue(" "); endDate = DateTimeLib.dateValue(" "); // Less than a month over a year endDate = DateTimeLib.dateValue(" "); // Less than a month short of a year endDate = DateTimeLib.dateValue(" "); end function getNumFullYearsAndMonths( inDate1 date, inDate2 date ) returns ( int ) fromTimeStamp timeStamp; //Temporary Timestamp1 - "from" date toTimeStamp timeStamp; //Temporary Timestamp2 - "to" date numYears int; //Number of years difference numMonths int; //Number of months difference // Set up timestamps containing the earlier and later dates if ( inDate1 <= inDate2 ) fromTimeStamp = DateTimeLib.extend( inDate1 ); toTimeStamp = DateTimeLib.extend( inDate2 ); else fromTimeStamp = DateTimeLib.extend( inDate2 ); toTimeStamp = DateTimeLib.extend( inDate1 ); //Initialize years and months difference between input dates numYears = DateTimeLib.yearOf(toTimeStamp) - DateTimeLib.yearOf(fromTimeStamp); //Note Absolute value of months, to cross years correctly, add 12 * years difference numMonths = mathlib.abs(DateTimeLib.monthOf(fromTimeStamp)- DateTimeLib.monthOf(toTimeStamp)) + (numYears * 12); // If if the end month is > the start month, need to adjust for partial year if ( DateTimeLib.monthOf(fromTimeStamp) > DateTimeLib.monthOf(toTimeStamp) ) numYears = numYears - 1; // If the start and end months are same, need to check for partial month if ( DateTimeLib.monthOf(fromTimeStamp) == DateTimeLib.monthOf(toTimeStamp) ) // If had a partial last month, then need to adjust the number of years if ( DateTimeLib.dayOf(fromTimeStamp) > DateTimeLib.dayOf(toTimeStamp) ) end //end inner-if end //end middle-if end //end outer-if return ( numYears ); //Note - currently returns number of years, end // but could just return number of months
15 Date and Time Math – Miscellaneous Topics1. The default formats for an interval mask are (either / or): Year/Month format: yyyyMM – or any combination Days/Hours format: ddHHmmssffffff - or any combination But: You can not combine the two formats above Can’t 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 ). So if you want EGL to create new variables with valid micro-second values, do the following: aTS timeStamp ("yyyyMMddHHmmssffffff"); aTs = dateTimeLib.currentTimeStamp(); 3. 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:
16 Date and Time Math – Miscellaneous Topics – Date Validation RoutineYou 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 But the good news is that you can combine try/onException with built-in function calls Here’s 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. function movedate() dtVar date {DateFormat = "MM/dd/yyyy"}; //A date in U.S.A. format dtString string; //A string variable try dtVar = datetimelib.dateValue(dtString); //built-in function to assign string-date to date onException(exception TypeCastException) //Oops - didn't work SysLib.setError("dtString is invalid"); //Let the user know end
17 Do and Acquire – Built-in Functions Workshops – 1 of 5Test your knowledge of the EGL Built-in Functions and Date Arithmetic by doing the following workshop: 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) //Program Source package programs; program builtInFunctionTest type BasicProgram {} //Global Variables twoYears Interval ("yy") = "02"; nineMonths Interval ("MM") = "09"; twoYears9Months Interval ("yyMM") = "0209"; newInterval Interval ("yMM") = "109"; dayInterval Interval ("dd") = "01"; currDate date; //the current date, default format newDate date {dateFormat = "yyyyMMdd", Value = " " }; newTime time {timeFormat = "hhmmss"}; newTS timeStamp; tokens STRING[0]; //a string array function main() testStrLib(); // testDateTimeLib(); // mathLibTest(); // testSysLibSysVar(); // dateMathAddition(); // dateMathSubtraction(); end
18 Do and Acquire – Built-in Functions Workshops – 2 of 53. 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 (Don’t forget to add a break-point!!!) //Program code function testStrLib() //get the length of a string or character data myString String = "EGL Rocks "; length INT = strLib.characterLen(myString); //Format a date myDate DATE; myFormat STRING = "EEE, MMM d, ''yy"; dateResult string = strLib.formatDate(myDate,myFormat); dateResult = strLib.formatDate(myDate,StrLib.eurDateFormat); //return individual tokens from a string commandLine STRING = "CALL PROG1 arg1,arg2"; delimiters STRING = " ,"; // space and comma delimiters i INT = 1; token STRING; while( i < strLib.byteLen(commandLine)) // Note that i is updated by the getNextToken Function! token = StrLib.getNextToken(commandLine, i, delimiters); writeStdOut(token as string); writeStdOut(i as string); if (token != null) tokens.appendElement(token); end //end-if end //end-while // reset the tokens array (optional) //tokens.removeAll(); - optional end //end-function
19 Do and Acquire – Built-in Functions Workshops – 3 of 54. 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. //Program Source function testDateTimeLib() tempTs timeStamp = DateTimeLib.timestampFrom(newDate, newTime); yr int = DateTimeLib.yearOf(newTS); mn int = DateTimeLib.monthOf(newTS); dy int = DateTimeLib.dayOf(newTS); case (DateTimeLib.weekDayOf(newTS)) when (0) SysLib.writeStdout("Sunday"); when (1) SysLib.writeStdout("Monday"); when (2) SysLib.writeStdout("Tuesday"); when (3) SysLib.writeStdout("Wedneday"); when (4) SysLib.writeStdout("Thursday"); when (5) SysLib.writeStdout("Fridayday"); otherwise SysLib.writeStdout("Saturday"); end
20 Do and Acquire – Built-in Functions Workshops – 4 of 55. 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. //Program Source function mathLibTest() fl float = MathLib.sqrt(12.4); rd money = MathLib.round( , -2); pwr decimal(7,2) = MathLib.pow(4.6, 3); end function testSysLibSysVar() sz int = syslib.size(tokens); srchFld string = "arg1"; if(srchFld in tokens) SysLib.writeStdout(sysvar.arrayIndex as string);
21 Do and Acquire – Built-in Functions Workshops – 5 of 56. 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. *** EXTRA CREDIT *** If time remains, return to the slide titled: Date and Time Math – Obtaining Months and Years Difference Between Dates - Copy/Paste the code from the Notes section into your builtInFunctionTest.egl program. - Debug through this new use case //Program Source function dateMathAddition() newDate = currDate + twoYears; newDate = currDate + nineMonths; newDate = currDate + twoYears9Months; newDate = currDate + newInterval + dayInterval; end function dateMathSubtraction() newDate = currDate - twoYears; newDate = currDate - nineMonths; newDate = currDate - twoYears9Months; newDate = currDate - newInterval - dayInterval; daysDiff int = currDate - newDate;