EGL Built-in System Function Libraries

EGL Built-in System Function Libraries This section describes how to use the EGL Built-in System Function Libraries (or the APIs) to simplify common programming tasks

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

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)

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.

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

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(<arrayVar>) • bytes(<varName>)– allows you find the size (in bytes) of any variable of any type, including an EGL record, etc. • 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: • getMessage (…) • getProperty(…)

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

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: • 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( keySTRINGin, valueANYin)

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

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: • twoYearsInterval ("yy") = "02"; //holds 0 – 99 years. Initialized to 2 years • nineMonthsInterval ("MM") = "09"; //holds 0 – 99 months. Initialized to 9 months • twoYears9MthsInterval ("yyMM") = "0209"; //up to 99 years + 99 months. Initialized to 2 years 9 months • twoYears9MthsInterval ("yyMM") = "0201"; //up to 99 years + 99 months. Initialized to 2 years and 1 month.

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 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 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 yearMonthInt Interval (“yyMM”) = “0209”; //2 years 9 months Add the interval to the date dateIn = dateIn + yearMonthInt;

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 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: Declare an Interval with a year mask and give it a value yearMonthInt Interval (“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

Date and Time Math – Working With Time and Timestamp Values You 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.

Date and Time Math – Obtaining Months and Years Difference Between Dates 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

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 But: • You can notcombine 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 000000). 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:

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

 Do and Acquire – Built-in Functions Workshops – 1 of 5 Test 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)

 Do and Acquire – Built-in Functions Workshops – 2 of 5 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 (Don’t forget to add a break-point!!!)

 Do and Acquire – Built-in Functions Workshops – 3 of 5 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.

 Do and Acquire – Built-in Functions Workshops – 4 of 5 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.

 Do and Acquire – 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. *** 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

EGL Built-in System Function Libraries