®

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

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 MathThe EGL Built-in Functions and Date Math

Topics:

Programming in EGLProgramming in EGL

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

4

EGL strLib FunctionsstrLib 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

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.

6

EGL mathLib FunctionsMathlib 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

EGL sysLib FunctionsSyslib 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>)bytes(<varName>) – 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.1. getMessage (…)getMessage (…)

2.2. getProperty(…)getProperty(…)

8

EGL vgLib FunctionsvgLib 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:

.

9

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:

1. Request – variables set from page-to-page2. Session – variables that persist for the duration of a user’s access to your application3. 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

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

11

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

twoYears1Mth Interval ("yyMM") = "0201"; //up to 99 years + 99 months. Initialized to 2 years and 1 month.

12

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 monthsAdd 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 yearsAdd 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 monthsAdd the interval to the date

dateIn = dateIn + yearMonthInt;

13

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 monthsSubtract 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 yearsSubtract 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 monthsSubtract 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

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***Notes for some examples of time/timestamp calculations.

15

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 NotesNotes for this slide)

Temp variables

Setup the subtraction

Subtract years…and months

Adjust for partial years and

months

16

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 notnot 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 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. 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(…);dateTimeLib.dateValueFromGregorian(…);

dateVar date {dateFormat = “yyyy/MM/dd”}; //declare your date variabledateVar date {dateFormat = “yyyy/MM/dd”}; //declare your date variable

dateVar = datetimelib.dateValueFromGregorian(<Decimal8-0var>);dateVar = datetimelib.dateValueFromGregorian(<Decimal8-0var>);

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: ISOFormatISOFormat, EURFormatEURFormat, USAFormatUSAFormat, etc. and the ability to create your own custom formats. Common custom examples include:

17

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 functionBut the good news is that you can combine try/onExceptiontry/onException with built-in function calls

Here’s an example, implemented using hello3.jsphello3.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

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

Built-in Functions Workshops – 2 of 53. Create the function shown here that exercises several of the strLibstrLib

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!!!)

20

Built-in Functions Workshops – 3 of 54. Create the function shown here that exercises several of

the dateTimeLibdateTimeLib 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

Built-in Functions Workshops – 4 of 55. Create the function shown here that exercises several of the mathLib mathLib

and sysLib and sysVar 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

*** EXTRA CREDIT ****** EXTRA CREDIT ***

If time remains, return to the slide titled: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 NotesNotes section into your builtInFunctionTest.eglbuiltInFunctionTest.egl program.

- DebugDebug through this new use case

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.

23

Copy Existing Build File Values – 1 of 4Now 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***Notes). Please do the

following:

1. From the Project Explorer,- Right-click over EGLWeb.eglbld and select: - Right-click over EGLWeb.eglbld and select:

- Open With > Text Editor- 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

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:

1. From Project Explorer, right-click over \EGLSource\\EGLSource\ and select: New Other… Expand EGL and select: EGL Build FileEGL Build File

From the next wizard, name the file: batchBuildFilebatchBuildFile

2. Close the new build file (you need to re-open, and edit it in Text Editor mode)

3. Reopen batchBuildFilebatchBuildFile using the Text Editor

4. Paste (Ctrl/V) (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”

6. Save your changes (Ctrl/SCtrl/S) and close the file

25

Assign the batchBuildFile to Your Programs Folder – 3 of 4 Now you will assign (or associate) the new batchBuildFile with the \programs\ directory.

1. From Project Explorer, right-click over \programs\\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 <EGLWeb/EGLSource/batchBuildFile.eglbld>

For both: Target system build descriptorTarget system build descriptor Debug build descriptorDebug build descriptor

Close the Properties viewClose the Properties view

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

1. From Project Explorer open EGLWeb.eglbldEGLWeb.eglbld with the EGL Build Parts Editor

2. From the Build parts editor, find the j2ee option, and set it to: YES (it’s a ComboBox)

3. From Project Explorer, right-click over your Project, and select GenerateGenerate

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 resourcesBatch resources – all .EGL files in the \programs\ directory – all .EGL files in the \programs\ directory J2EE/Web resources J2EE/Web resources – everything else in your project (using the default build file settings)– everything else in your project (using the default build file settings)

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

BatchBatch

ProcessProcess

.JSP.JSP

PagePage

Copy a fileCopy a file

FTP a fileFTP a file

28

(OPTIONAL) Calling Operating System Commands - Lab From the \programs\\programs\ package, right-click, and create a new, EGL program, named: callcmdPgm Replace the boiler-plate code with the EGL statements in the ***Notes***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, you’ll 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

(OPTIONAL) Running EGL-Called Operating System Commands The v7.1 Debugger has been setup to make some specific Java .JAR files part of your PC’s 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

Note: If calling the startCmd() or callCmd() built-in functions from a web page you do notnot have to do this.

However, there is a requirement when running either startCmd() or callCmd() from an EGL generated Java batchbatch 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: From the Start menu, select ControlControl Panel Panel

SystemSystem AdvancedAdvanced – and on the Advanced tab, click: – and on the Advanced tab, click: Environment VariablesEnvironment Variables In the System variables window, scroll down and select: In the System variables window, scroll down and select: PathPath, and click , and click EditEdit Add the Add the <RBD7.1 installation-directory>\bin;<RBD7.1 installation-directory>\bin; to the end of the Variable value 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

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