1. No category

I
INTELLIGENT TEXT PROCESSING
ITP
How to get started with ITP
2001-12-21
This tutorial provides a step-by-step description of developing ITP
applications. It introduces the reader to both describing databases for ITP
as well as to developing documents.
©2002, Aia Holding BV, Nijmegen, The Netherlands
ITP – How to get started with ITP
I
Table of contents
1.
Introduction ........................................................................... 3
1.1
About this tutorial. ........................................................................................ 3
1.2
Sample application database & software.................................................... 3
1.3
Word processing and sample output ........................................................... 3
2.
Installation and configuration ................................................. 6
2.1
Installation of the AS/400 software.............................................................. 6
2.2
Installation of ITP/CS ................................................................................... 6
2.3
Configuring ITP/CS ...................................................................................... 6
2.4
Configuring the AS/400 side......................................................................... 6
Tutorial
3.
The ITP development cycle ..................................................... 7
3.1
4.
Starting ITP/SDK AS/400............................................................................. 8
ITP working environment........................................................ 9
4.1
ITP Quick start.............................................................................................. 9
4.1.1
4.1.2
4.1.3
4.1.4
4.2
5.
Work with DIDs .......................................................................................... 11
ITP cycle: database data........................................................ 12
5.1
Customer information ................................................................................ 12
5.1.1
5.1.2
5.1.3
5.1.4
5.1.5
5.2
6.
Name and initials of customer..........................................................................12
Creating entry Customer ..................................................................................12
Creating the main entry ....................................................................................16
Downloading the DID to ITP/CS .....................................................................16
Developing and testing the model document ...................................................17
Adding address information ...................................................................... 20
5.2.1
5.2.2
5.2.3
5.2.4
5.2.5
A Customer’s address information...................................................................20
Creating entry Address_of_customer...............................................................21
Creating the sub-entry ......................................................................................22
Updating the DID on the PC ............................................................................23
Extending your model document .....................................................................24
ITP cycle: application programs ............................................ 26
6.1
Total debt of customer ................................................................................ 26
6.2
Creating the user defined function ............................................................ 27
6.2.2
6.3
1/31
Creating and linking ITP DID components........................................................9
Create DID .......................................................................................................10
Create DID-source............................................................................................10
Link the DID-source to the DID ......................................................................11
Updating the DID on the PC ............................................................................28
Extending your model document............................................................... 29
ITP – How to get started with ITP
Tutorial
I
2/31
7.
How to get on with ITP? ....................................................... 31
7.1
Review .......................................................................................................... 31
7.2
Future extensions ........................................................................................ 31
ITP – How to get started with ITP
I
1. Introduction
Tutorial
1.1 About this tutorial.
This "How to get started with ITP" tutorial is meant for all developers who will be working with
ITP/CS and the ITP/SDK AS/400 for the first time. For your first inspection it's very useful to
perform all the operations shown in this tutorial. You can use this tutorial also as a starting point
and a guide when testing and evaluating the ITP product.
In this tutorial we are going to explain the basic operations necessary to be able to produce the
output you want when using ITP. These operations are part of the "ITP development cycle".
But first, we are going to introduce you to the example database used throughout this book. This
database is part of the standard ITP distribution. Next, we will introduce some sample output. This
sample output will be your starting point. We will also discuss the parts of ITP that have to be
installed.
In chapter three the ITP development cycle will be introduced. Following that, you will start
working with ITP/SDK AS/400 and with ITP/CS for developing your documents.
You are referred to the ITP/SDK AS/400 and the ITP/CS online manuals contain additional
explanation on all subjects.
1.2 Sample application database & software
The sample application that you will be using is located in library TSTEXAMPLE. This library is
optionally installed with the ITP AS/400 software. The database consists of 6 files, three of which
are logical files:
CUSTADD
CUSTADDL
CUSTOM
CUSTOML
INVOICE
INVOICEL
Physical file containing addresses of customers
LF on CUSTADD with unique key: 'Customer number'
Physical file containing customers (name, date of birth, etc.)
LF on CUSTOM with unique key: 'Customer number'
Physical file of invoices of customers
LF on INVOICE with unique key: 'Invoice number' ; 'Customer number' ; 'Article
number'.
The database application is designed to work with specific data pertaining to several customers:
e.g. customer names, dates of birth, the address and invoice data.
Normally, to be able to work with and maintain the above sample database, you would need
maintenance programs (e.g. to enter customers). Other programs would also be available, for
example to perform certain calculations and updates. The maintenance programs, however, are not
actual included in our sample application. Only one sample calculation program is available.
1.3 Word processing and sample output
Conceivably, there are several types of output you would like to produce. For example: a variety of
letters, lists, invoices and reminders.
Such output could be produced by using a word processor to edit it. The advantage of using a word
processor is that you are able to use all its features. This enables you to select the layout of output
3/31
ITP – How to get started with ITP
I
you desire, using bold and underline features, for example. The disadvantage of using only a word
processor, however, is that most of the output you want will also consist of data already stored in
the application database. ITP adds these data retrieval functions to your word processor
environment.
Next, some sample output is listed:
Mr D.A. Benitas
Gonzales 123
1254 Tijuana
Mexico
12 July 2001
Tutorial
Dear Mr Benitas,
Recent items ordered by you amount to US$ 5,760.==. This concerns
the following:
Invoice: 50593
Tape streamer
Processor
$
$
1,100.==
1,560.==
$
$
1,200.==
1,900.==
Invoice: 100593
WP 5.2
PS/2 Model75
According to the terms of our agreement, payment is one week
overdue. We kindly ask you to make payment as soon as possible.
Yours sincerely,
P. Gonzales
Example 1: Reminder to one particular person.
4/31
ITP – How to get started with ITP
I
CUSTOMER CARD
Customer number:
Initials:
Surname:
1234
D.A.
Benitas
ADDRESS:
Street:
Number:
Postal Code:
City:
Country:
Gonzales
123
1254
Tijuana
Mexico
Tutorial
Example 2: List showing one customer.
Personal
number
Surname
Initials
1002
1111
1234
1237
3214
4321
4335
4336
6345
7634
Benitas-Fuentes
Turing
Benitas
Washington
Prefect
Wilson
Bundy
Bundy
Jansen
Jansen-De Vries
G.
A.F.G.
D.A.
G.S.
F.
G.
A.
P.
S.J.M.M.
B.F.K.
Example 3: List of all customers.
In all previous examples the variable information, i.e. information that can be retrieved from the
application database, is printed boldface and information that can be deducted from the application
database is printed in italic. When using ITP you have to create the proper ITP components, to be
able to create output of the kind shown in the previous examples.
Details about developing the actual document, i.e. what instructions to use etc., can be found in the
ITP/CS online manual, that includes an introduction to model development and a reference manual.
5/31
ITP – How to get started with ITP
I
2. Installation and configuration
This tutorial is based on ITP 2.1. In particular the following products are concerned:
• ITP/SDK AS/400 2.1
• ITP/CS 2.1
• ITP AS/400 Connection 2.1
2.1 Installation of the AS/400 software
Follow the steps outlined in the installation guides for the AS/400 software. Make sure to install the
following components:
• ITP/SDK AS/400
• ITP AS/400 Connection
Tutorial
• How to get started with ITP (this is the example database used in this tutorial)
2.2 Installation of ITP/CS
Follow the steps outlined in the installation guides for the Windows ITP/CS software. Make sure
you enter a valid ITP/CS licence.
The last step of the installation process asks you which configuration file to activate. For this
tutorial, you are going to create your own ITP components, so you will need to use the
configuration file for the ITP working environment, in which you will create your own stuff.
2.3 Configuring ITP/CS
ITP/CS is largely automatically configured. The only part that has to be configured is the AS/400
Connection. Start the ‘Configuration’program from the ‘ITP 2.1/Administration’ folder in your
Start menu. Select ‘Connection configuration. The Connection configuration window will appear:
In this window you can configure the AS/400 Connection. You can choose to configure settings on
global level, i.e. for all DIDs of the AS/400 Connection or you can choose to configure settings on
DID level.
Enter the protocol that you want to use for your connection (Protocol) and the name or address of
your AS/400 that is running the ITP AS/400 software (Address) on global level.
2.4 Configuring the AS/400 side
Install the software on the AS/400 side. Enter a valid license.
6/31
ITP – How to get started with ITP
I
3. The ITP development cycle
Normally, before producing any output, you will first analyse your needs. Certain output
requirements were shown in the previous paragraph. You will make use of data from your
application database. Further, you will use your word processor to develop and format the output.
Basically, ITP development consists of two parts: database administration (ITP data dictionary) and
model development (using your word processor).
Tutorial
The ITP data dictionary, called the DID, enables you to define ways to retrieve data from your
database, i.e. you create entries to your database, using existing access paths. The DID also enables
you to appoint existing application programs to act as functions, e.g. to perform calculations and
updates. This means you will be able to construct so-called user-defined functions that can be used
when producing the output. The DID is developed with the ITP/SDK AS/400 on your AS/400.
ITP model development is performed with the ITP/CS PC software, the ITP component in which
you actually are going to compose and produce your output. This component enables you to use the
DID definitions to retrieve data (entries) and to perform certain functions (user defined functions).
First, the output is composed together with the ITP instruction language and word processor
instructions, after which you will be able to produce the output.
In chapter 4 you will first set up an empty DID with the ITP/SDK AS/400.
In chapters 5 and 6 you will then construct the data dictionary components and model documents to
be able to produce the desired output. A step-by-step method will be used to produce the output:
1. Analyze your needs:
- Which database file contains the data concerned or which program actually performs the
function needed?
- Which data dictionary components have to be created to be able to retrieve the data concerned
or to perform the necessary function?
2. Create the corresponding database entries or user defined functions in the ITP DID
3. Download the DID to the PC using the ITP/CS PC software
4. Develop the model document
5. Create output by running the model
You should repeat steps 1 to 5 as many times as necessary to be able to produce the desired output.
In this tutorial you will repeat this development cycle three times.
7/31
ITP – How to get started with ITP
I
3.1 Starting ITP/SDK AS/400
Type on an AS/400 command line (in a 5250 session) the start-up command of ITP/SDK AS/400.
ITPPGM21/STRITP
The ITP Main menu will appear:
MNUITP
ITP Main menu
13/07/01
10:50:34
Select one of the following:
1. Work with DIDs
2. Work with DID-sources
Tutorial
7. Authorisation menu options ITP Main menu
30. ITP Quick start
40. ITP Management
90. Signoff
Option:
===>___
F3=Exit
F12=Cancel
F10=Command entry
Before actually producing any output, you will first create an empty DID. This is explained in the
next chapter.
8/31
ITP – How to get started with ITP
I
4. ITP working environment
4.1 ITP Quick start
You will now create your own working environment containing the basic ITP components needed
for your own DID.
This environment can be created by selecting option '30. ITP Quick start'.
4.1.1 Creating and linking ITP DID components
Tutorial
The following are the various ITP components created by “ITP Quick start”:
- ITP database administration (ITP data dictionary):
- DID
- DID-source (including a reference to an object and source library)
- Connection between the DID and the DID source
DID sources are a kind of DID modules. For now you will only need one DID source per DID.
When developing more complex ITP applications you may need to create modular DIDs, which
can be implemented using these DID sources.
The minimum set of ITP components to be created can be shown schematically as the 'Structure of
an ITP working environment'.
DID
DID Source
Object library
Source library
9/31
ITP – How to get started with ITP
I
The structure you will create is as follows:
TSTDID
TSTSRC
TSTOBJ
TSTOBJ
Now select option ‘30. ITP Quick start’ in the ‘ITP Main menu’ to set up your own working
environment.
Tutorial
4.1.2 Create DID
After selecting option 30 in the ITP Main menu, the 'Create DID' screen appears:
Fill in the screen as follows:
DID:
Identification:
Description:
...
TSTDID
EXP
Any description you want
The example above contains the name of the DID and the so called three-letter code of the DID
(EXP). This three-letter code will be used in your model documents so that ITP knows which DID
is concerned. Press enter to create the DID. After the DID ‘TSTDID’ has been created, you will see
the ‘Create DID-source’screen.
4.1.3 Create DID-source
Next you create your DID-source:
Fill in the ‘Create DID-source’ screen as follows:
DID-source:
PGM Object Library:
PGM Source Library:
Description:
...
TSTSRC
TSTOBJ
TSTOBJ
Any description you want
The OS/400 library ‘TSTOBJ’ will also be created, including the physical source files QRPGSRC
and QDDSSRC. This object library will be used to store the program objects related to entries in
the database (if you decide to generate RPG code for data retrieval instead of using direct database
file access) and to the user defined functions of your DID-source. Press enter to create the DIDsource and the library(ies).
10/31
ITP – How to get started with ITP
I
4.1.4 Link the DID-source to the DID
After creating the DID-source and related object library with the two physical source files, this
DID-source should then be linked to your DID. Therefore, the ‘Link DID-source to DID’ screen
appears.
Fill in the screen as follows:
DID:
TSTDID
DID-source:
TSTSRC
Then press enter. The ITP Quick start returns to the ITP Main menu. Select option '1. Work with
DIDs' and press Enter.
4.2 Work with DIDs
Tutorial
Your DID is present in the list of DIDs. From this screen you can reach all ITP DID components
that are and will be defined in your DID.
WRKDID
Work with DIDs
13/07/01 10:57:34
List selection:
Type options and press Enter.
2=Change
4=Delete
11=Main entries
15=Standard funct. 16=DID-sources
OPT
__
__
DID
ITP
TSTDID
F3=Exit
F6=Create
Status
F
F
Id.
ITP
EXP
F5=Refresh
F23=More options
5=Display
22=Model environm.
Description
ITP description of ITP
Example "How to get started"
F12=Cancel
F13=Repeat option
Subsequent chapters describe step-by-step how the structure of the sample application is defined.
You will start with the ITP description of the file structure of the sample database.
11/31
ITP – How to get started with ITP
I
5. ITP cycle: database data
5.1 Customer information
Mr D.A. Benitas
5.1.1 Name and initials of customer
When looking at example 1 in Chapter 1, you see that the information you will first want to place
in your letter are the initials and the surname of one specific customer.
Tutorial
Locating the corresponding database file
12/31
Information about customers is stored in the file CUSTOM, together with the logical file
CUSTOML. In the next paragraph you will create the necessary ITP data dictionary components.
You have now complete step 1 of the ITP cycle. You will now proceed to create an ITP entry for
this data.
5.1.2 Creating entry Customer
In the 'Work with DIDs' screen select your DID using the '16=DID sources' option. The 'Work with
DID-sources of DID' screen now appears.
Select your DID source (TSTSRC) using option '16=Work with DID-source'. The DID source
menu appears. Select option '1. Work with Entries'.
The 'Work with Entries' screen will appear. No entries have been created yet. You will now
generate the entry: 'Customer'.
Select function key 'F20=Generate'. The 'Generate Entry' screen appears.
ITP – How to get started with ITP
I
Fill in the 'Generate Entry' screen as shown in the following screen:
GENENT
Generate Entry
13/07/01 11:01:44
Tutorial
Type values and press Enter.
13/31
DID source ......................:
TSTSRC
Entry ...........................:
Entry type ......................:
Entry processing ................:
Customer
S
S=WITH, P=FORALL
E
L=Lazy, E=Eager
PGM data retrieval ..............:
*DBMS400
Retrieve information from:
File .........................:
Library ...................:
CUSTOML
TSTEXAMPLE
Description .....................:
Any description you want
Press Enter after you have specified all entry attributes.
ITP now scans the internal description of the file. The internal field definitions (field name, field
description, type and length) of the file fields are retrieved. Next, the screen appears in which these
field definitions are listed. The ITP field names are defaulted by the field descriptions. In the
'Specify entry fields' screen you can change these ITP field names. These field names are used in
your ITP model documents.
Remark: throughout this tutorial we will use direct database file access to retrieve data for ITP.
This is done by using the *DBMS400 special value for ‘PGM data retrieval’. You can also specify
program names if you want to use programs for data retrieval. The SDK also provides functions to
generate either RPG or Cobol source for these programs. You can adapt these sources to your own
needs.
ITP – How to get started with ITP
I
Adding fields
Now the ‘Work with Entry fields’ screen appears in which the field names to be used with this
entry are listed. On this screen you can change the field names:
WRKFILFL
Work with Entry fields
13/07/01 11:02:17
File ..............: CUSTOML
Entry ........: Customer
Library ........: TSTEXAMPLE
DID-source : TSTSRCnn
Record format .....: CUSTOM
Tutorial
Type options and press Enter.
7=Convert to valid ITP name
OPT
__
__
__
__
__
__
__
__
__
Field
CUSTNO
SURNAME
FIRSTNAM
INITIALS
BIRTH
DEATH
GENDER
MARSTAT
PARTNER
ITP field name
Customer_number
Surname
First_name
Initials
Date_of_birth
Date_of_death
Gender
Marital_status
Partner number
F3=Exit
F5=Refresh
F20=Add fields to entry
Type
Length
S
A
A
A
P
P
A
A
S
6
30
30
10
5
5
1
1
6
Decimals
00
00
00
00
F13=Repeat option
Some of these field names will now have to be converted to valid ITP names. Use option
‘7=Convert to valid ITP name’ for ‘Customer number’, ‘First name’, ‘Date of birth’, ‘Date of
death’, ‘Marital status’ and ‘Partner number’. These field names contain spaces which are not
allowed in ITP field names. Valid ITP names always start with an uppercase character and can
further contain lower cases, upper cases, digits and underscores (‘_’).
After all fields names have been converted to valid ITP names, add the fields to the entry by
pressing ‘F20=Add fields to entry’.
14/31
ITP – How to get started with ITP
I
Adding formal parameters
After the field names have been added, the formal parameters of the entry have to be specified.
These are the keys to be used when selecting a record from the database file. In this case you will
want to produce a document for one specific customer. The formal parameters will be the customer
number, that will be used for selecting this customer.
The ‘Work with Formal parameters’ screen appears in which all key fields of the database file are
listed:
WRKFILKY
Work with Formal parameters
File ..............: CUSTOML
Library ........: TSTEXAMPLE
Record format .....: CUSTOM
Tutorial
Type options and press Enter.
4=Drop key field
7=Convert to valid ITP name
OPT Key
__ CUSTNO
13/08/01 11:05:37
Entry ........: Customer
DID-source : TSTSRCnn
6=Retrieve key field
Formal parameter
Customer_number
F3=Exit
F5=Refresh
F20=Add formal parameters to entry
Seqno
00010
F13=Repeat option
The formal parameter names are defaulted by the ITP field names of the corresponding file field.
Now select F20 to add the formal parameters shown in the screen. Customer_number will be
recorded as the formal parameter of the entry, Customer.
After the entry has been generated, the 'Work with Entries' screen reappears.
Selecting screen fields
You will use this entry as a so-called main entry. In stand-alone mode, i.e. when ITP is not
integrated in an application, using this main entry means that the user has to select the customer for
which to retrieve the fields. This selection window will, during document production, be generated
by ITP/CS. You will have to tell ITP which fields to display in this selection window.
Choose option ‘36=Screen fields’ and enter sequence numbers for the fields to display in the
selection window. Select at least the ‘Surname’.
You now have defined a complete entry, ready to use. You can compare your 'Customer' entry to
the 'Customer' entry in the example DID source 'TSTSRC.ENG'. This DID source and the
corresponding DID ‘TSTDID.ENG’ can be used as a reference. This holds true for every operation
you perform in this tutorial. All components you create can be compared to the corresponding
components in the example DID. This enables you to check from time to time whether you have
created everything the way it should be created.
Remark: when you have chosen to use a program for data retrieval, you should use option
‘25=Generate data retr.’ for entry Customer on the 'Work with Entries' screen to generate the RPG
or Cobol source for this entry. The source will be created in TSTOBJ. More details can be found in
the ITP/SDK AS/400 manual.
15/31
ITP – How to get started with ITP
I
5.1.3 Creating the main entry
Before you can use your DID, you first have to assign the Customer entry as a main entry in your
DID. This is because you will need the Customer entry as the starting point for the sample
document in this chapter; i.e. as a starting point of the model you are going to run.
Go back to the 'Work with DIDs' screen, select your DID using the '11=Main entries' option.
The 'Work with Main entries of DID' screen will appear. Select the function key 'F6=Create' to add
‘Customer’ to the list of main entries in your DID. With the 'Create Main entry' screen you can
select the entry you want to assign to be the main entry and the DID-source in which the entry is
defined.
You have now completed step 2 of the ITP cycle. You will now proceed to download this DID to
ITP/CS and to create your first model document for this DID.
5.1.4 Downloading the DID to ITP/CS
Tutorial
DID development and maintenance is all done in the ITP/SDK AS/400. To be able to use your DID
in ITP/CS you will have to download the DID to the PC.
The DID download is performed with the ITP/CS program ‘AS400 DID Management’. Start this
program from the ‘ITP 2.1/Integration’ folder in your Start menu.
Fill in the DID Management window as follows:
The librarylist during model execution can also be configured in the Connection configuration
window.
Press ‘Add’ to download the DID from the AS/400 to your PC. When this is finished you can
proceed to develop your own model documents.
16/31
ITP – How to get started with ITP
I
5.1.5 Developing and testing the model document
You develop and test your model documents in the ITP/CS ‘Model development’ program and in
your word processor. For more information you are referred to the ITP/CS online manual.
Creating the model document
Begin with creating a new document in your word processor with the following contents.
# BEGIN
WITH Cust IN EXP.Customer DO
Tutorial
IF Cust.Gender = "M"
THEN # Mr #
ELSE # Ms #
FI
#
@(Cust.Initials) @(Cust.Surname)
#
17/31
OD
END #
Save this file in the model document directory of your ITP working environment using file name
“Sample.doc” where doc is the file extension used by your word processor. In a default ITP/CS
installation with Microsoft Word the file may be stored in: ‘c:\itpwork\moddocs\sample.doc’.
Compiling the model document
The next step is to ‘compile’ and test this model document either with the Model Developer Kit
(installation is optional) or with the Model development programm. In this tutorial we use the
‘Model development’ program from the ‘ITP 2.1/Model development’ folder in your Start menu to
'compile' and test the model document. Start this program and fill in the window as follows:
ITP – How to get started with ITP
Tutorial
I
18/31
Select the model document you have just created, select your own DID (‘TSTDID’) and enable
‘Edit test document’. All other data and options are automatically filled in and selected.
Select the ‘Create’ button to compile your model document. If you did not make any mistakes you
should see the Status message: ‘Ready creating model, no errors’. If not, a copy of the model
document will be opened in your word processor with the errors annotated. Press the ‘Edit’ button
in the window above to open the original model document in your word processor. Correct the
errors and close both your model document as well as the error document. Next re-select the
‘Create’ button to compile the corrected document.
Testing your model
After successful compilation you can test your model document by selecting the ‘Run’ button. A
selection window will appear in which you can select a customer, whose name is to be printed in
the result document:
ITP – How to get started with ITP
I
This window is like an AS/400 selection screen where you can use the Customer_number as a
positioner or the scroll bar and the ‘Next’ button to browse for the customer that you want to use.
The example database does not contain enough data to use the ‘Next’ button.
You can either double click on a customer or select the customer and then press ‘Ok’ to proceed.
After a few seconds, usually less, the actual result document will have been produced and opened
automatically in your word processor to show you the result. This result should be similar to the
example at the beginning of this chapter. Close the result document before proceeding.
Tutorial
You are advised not to close the ‘Model development’ program, since you will return to working
on this model document in a while.
19/31
ITP – How to get started with ITP
I
5.2 Adding address information
5.2.1 A Customer’s address information
In this paragraph you are going to extend your model. You want to be able to place the address of
the customer selected in your reminder:
Mr D.A. Benitas
Gonzales 123
1254 Tijuana
Mexico
July 13 2001
Dear Mr Benitas,
Tutorial
You recently ordered items amounting to $ ...... This concerns the following:
.....
According to the terms of our agreement, payment is one week overdue. We kindly
ask you to make payment as soon as possible.
Yours sincerely,
P. Gonzales
Locating the corresponding database file
Customer address information is stored in the file CUSTADD, together with the logical file
CUSTADDL (see chapter 1). In the next paragraph you will create the necessary ITP data
dictionary components.
20/31
ITP – How to get started with ITP
I
5.2.2 Creating entry Address_of_customer
Go to the 'Work with Entries' screen. You have already created entry Customer. You are now going
to generate the entry 'Address_of_customer'.
Again select the 'F20=Generate' function key. The 'Generate entry' screen will appear. Fill in the
screen as follows:
GENENT
Generate Entry
13/07/01 11:15:12
Tutorial
Type values and press Enter.
DID source ......................:
TSTSRC
Entry ...........................:
Entry type ......................:
Entry processing ................:
Address_of_customer
S
S=WITH, P=FORALL
E
L=Lazy, E=Eager
PGM data retrieval ..............:
PGM key retrieval ...............:
*DBMS400
*DBMS400
Retrieve information from:
File .........................:
Library ...................:
CUSTADDL
TSTEXAMPLE
Description .....................:
Any description you want
Press Enter after you entered the entry attributes.
Adding fields
ITP now scans the internal description of the entered file. The ‘Work with Entry fields’ screen will
appear in which you can drop fields and change fields names.
Make sure at least the following field names are recorded with the 'Address_of_customer' entry:
Customer_number
Street
Housenumber
Postcode
City
Country
Again, use option 7 to convert the field names to valid ITP field names. Make sure to press Enter
after editing one or more fields.
Select the F20 function-key to add the fields to the 'Address_of_customer' entry.
Adding formal parameters
After the field names have been added, the formal parameters of the entry have to be specified. The
'Work with Formal parameters' screen enables you to do so. You will need 'Customer_number' as
21/31
ITP – How to get started with ITP
I
the formal parameter of the 'Address_of_customer' entry. This will be used to connect entry
Customer to entry Address_of_customer.
Select F20 to add the formal parameters shown on the screen. Next, 'Customer_number' will be
recorded as the formal parameter of the 'Address_of_customer' entry.
When the entry has been generated automatically, the 'Work with Entries' screen will reappear.
Contrary to the Customer entry you will not need to specify screen fields, because no selection
window is needed for this entry. The address selection will be performed for an already selected
customer. This ‘connection’ of the ‘Address_of_customer’ entry to entry ‘Customer’ is called a
sub-entry. This sub-entry relation will be created in the next paragraph.
5.2.3 Creating the sub-entry
Tutorial
Before extending the model that you created in the previous paragraph, you must first create a socalled sub-entry relation. In this the entry 'Address_of_customer' will become a sub-entry of
'Customer', enabling you to retrieve the address of a particular customer.
Select the 'Customer' entry using option '17=Sub entries' on the 'Work with Entries' screen. The
'Work with Sub entries' screen will then appear. On this screen you must create the sub-entry,
'Address_of_customer' of the 'Customer' entry. To do this, select the 'F6=Create' function key.
Fill in the ‘Create Sub-entry’ screen as follows:
CRTSUBEN
Create Sub-entry
13/07/01
11:18:03
Type values and press Enter.
DID-source ......................:
Entry ...........................:
TSTSRC
Customer
Sub-entry .......................:
Address_of_customer
F3=Exit
F4=List selection
F12=Cancel
Enter 'Address_of_customer' on the screen or select that entry by using 'F4=List selection'.
Adding actual parameters
After creating the sub-entry, you must enter the so-called actual parameters of the sub-entry
definition. The actual parameters of a sub-entry relation are the values filled in for the formal
parameters when ‘going’ from the entry to the sub-entry at run-time.
To do so, select the 'Address_of_customer' sub-entry using the '18=Actual parameters' option on
the ‘Work with Sub entries’ screen. The 'Work with Actual parameters' screen will appear.
On this screen the actual parameter records are listed. Using option '2=Change', the actual
parameters can be entered. The Address_of_customer entry has one formal parameter:
Customer_number. An actual parameter has to be assigned to this formal parameter. In this case,
the actual parameter will be a field from the entry, Customer. To be able to retrieve the
address_of_customer of a specific customer, the field Customer_number from the Customer entry
22/31
ITP – How to get started with ITP
I
has to be assigned as an actual parameter to the corresponding formal parameter of the
Address_of_customer entry.
Now select the actual parameter using option 2.
The 'Create actual parameter' screen will appear:
CHGSUBAP
Create Actual parameter
16/07/01
8:50:23
Tutorial
Type values and press Enter.
DID-source ......................:
Entry ...........................:
Sub entry .......................:
Formal parameter ................:
TSTSRC
Customer
Address_of_customer
Customer_number
Sequence number formal parameter :
Data type .......................:
Length ..........................:
Decimal pos./Alignment ..........:
00010
Z T=TEXT, P=PACKED, Z=ZONED, B=BINARY
00006
00000
Actual parameter ................:
Customer_number
Constant value ..................:
F3=Exit
F12=Cancel
F4=List selection
Select F4 to select the field 'Customer_number' for ‘Actual parameter’. Finally press Enter.
The sub-entry definition has now been completed. You can now use this sub-entry in your model
documents. In the next paragraph you will update the DID on your PC and extend your model
document.
5.2.4 Updating the DID on the PC
Because the DID has been changed in the ITP/SDK AS/400 you will need to update the DID on the
PC in ITP/CS as well. To do so start the ‘AS400 DID Management’ program, select your DID and
press the ‘Update’ button.
Now you can proceed to extend your model document.
23/31
ITP – How to get started with ITP
I
5.2.5 Extending your model document
Make sure that your model document (sample.doc) is selected in the ITP/CS ‘Model development’
program and press the ‘Edit button’ to open the document in your word processor.
Extend your document to the following:
# BEGIN
Tutorial
WITH Cust IN EXP.Customer DO
IF Cust.Gender = "M"
THEN # Mr. #
ELSE # Mrs. #
FI
#
@(Cust.Initials) @(Cust.Surname)
#
WITH Addr IN Cust.Address_of_customer DO
#
@(Addr.Street) @(numerals(Addr.Housenumber))
@(Addr.Postcode) @(Addr.City)
@(Addr.Country)
#
OD (* sub-entry Address_of_customer *)
#
@(date(today))
#
IF Cust.Gender = "M"
THEN # Dear Mr #
ELSE # Dear Ms #
FI
#
@(Cust.Surname),
You recently ordered items amounting to US$ ...... This concerns the following:
According to the terms of our agreement, payment is one week overdue. We kindly
ask you to make payment as soon as possible.
Yours sincerely,
P. Gonzales
#
OD (* main Customer entry *)
END #
When you are finished, save and close the document and return to the ‘Model development’
program.
24/31
ITP – How to get started with ITP
I
Select the ‘Create’ button again to compile your model document. If you did not make any
mistakes you should see the Status message: ‘Ready creating model, no errors’. If not a copy of the
model document will be opened in your word processor with the errors annotated. Press the ‘Edit’
button in the window above to open the original model document in your word processor. Correct
the errors and close both your model document as well as the error document. Next re-select the
‘Create’ button to compile the corrected document.
Testing your model
After successful compilation you can test your model document again by selecting the ‘Run’
button. After selection of a customer a result document will be produced similar to the desired
result.
Tutorial
There still is some information missing in your output. Especially, the customer's total debt is not
yet available. In the next chapter you will create a user defined function that calculates the total
debt of that particular customer. The actual calculation is performed by an AS/400 program.
25/31
ITP – How to get started with ITP
I
6. ITP cycle: application programs
Often you will need to insert data in your documents that cannot directly be read from the database.
A program is needed to calculate this data or maybe a program is already available that performs
exactly this calculation.
In these cases you can define a ‘user defined functions’ (also called ‘DID defined functions’) for
ITP. These functions can be used in the model documents and are actually linked to programs on
the AS/400. These programs must follow the interface rules for ITP that are descibed in the
ITP/SDK AS/400 manual. You can also take a look at the source code of the example used in this
chapter.
This chapter will introduce you to defining these functions in your DID.
6.1 Total debt of customer
Tutorial
Example output: calculation of a customer's total debt
Mr D.A. Benitas
Gonzales 123
1254 Tijuana
Mexico
12 January 2001
Dear Mr Benitas,
Recently you ordered items amounting to US$ 5,760.==. This concerns the
following:
....
According to the terms of our agreement, payment is one week overdue. We kindly
ask you to make payment as soon as possible.
Yours sincerely,
P. Gonzales
When looking at the example you see that the information printed boldface is information that is
not yet available. In this chapter you will create the required ITP component to calculate that piece
of information, and place it in your result document.
Locating corresponding application program
We have provided a program source in the example application to calculate the total debt of one
particular customer. This source is located in QRPGSRC in library TSTEXAMPLE, called
CALCDEBTEN. The compiled program should also be available in this library. Please verify this.
This program source has been created for use in this tutorial. The source has already been adjusted
to the program structure of user defined functions (see your ITP/SDK AS/400 manual).
26/31
ITP – How to get started with ITP
I
In general, you will adjust existing sources or construct new ones in order to create user defined
functions, so the related programs can be used as user defined functions.
6.2 Creating the user defined function
First, go to the ‘DID source menu’ to work with your DID source. Next, select the option: '2. Work
with User defined functions'. The 'Work with User defined functions' screen will appear.
There are no functions available yet. To create a user defined function, select the 'F6=Create'
function key. The 'Create User defined function appears' screen will appear.
Tutorial
Enter the following on this screen:
DID-source ......................:
TSTSRC
User defined function ...........:
Description .....................:
PGM function execution ..........:
Calculate_total_debt
Any description you want
CALCDEBTEN
Press ‘Enter’.
Defining the parameters
Back on the 'Work with User defined functions' screen you must now specify the input parameters
of this user defined function. Therefore, select the 'Calculate_total_debt' function using the
'18=Input parameters' option. The 'Work with Input parameters of function' screen will appear.
The input parameter of this function will be the customer number. Now select the function-key,
'F6=Create', to create that input parameter.
Enter the following on the 'Create Input parameter' screen:
DID-source ......................:
User defined function ...........:
TSTSRC
Calculate_total_debt
Input parameter .................:
Sequence number .................:
Data type .......................:
Length ..........................:
Decimal positions ...............:
Alignment .......................:
Customer_number
1
Z
T=TEXT, P=PACKED, Z=ZONED, B=BINARY
6
0
L
L=Left, R=Right
Press Enter.
27/31
ITP – How to get started with ITP
I
Defining the function result
Now return to the 'Work with User defined functions' screen. Select your function using the
'19=Result' option. The 'Work with Result' screen will appear. Select the result using the
'2=Change' option, then enter the following:
DID-source ......................:
User defined function ...........:
TSTSRC
Calculate_total_debt
Result ..........................:
Total_debt
Data type .......................:
Length ..........................:
Decimal positions ...............:
Alignment .......................:
P
5
2
L
T=TEXT, P=PACKED, Z=ZONED, B=BINARY
L=Left, R=Right
Tutorial
Press Enter.
Assigning to the DID
Before extending your model document, you must first assign the user defined function,
'Calculate_total_debt', as a user defined function of your DID.
Return to the 'Work with DIDs' screen. Select your DID using the '15=Functions' option.
The 'Work with User defined functions of DID' screen will appear. Select the 'F6=Create' function
key to add the user defined function, 'Calculate_total_debt', to the list of user defined functions of
your DID:
DID .............................:
TSTDID
User defined function ...........:
DID-source ......................:
Calculate_total_debt
TSTSRC
6.2.2 Updating the DID on the PC
Because the DID has been changed in the ITP/SDK AS/400 you will need to update the DID on the
PC in ITP/CS as well. To do so start the ‘AS400 DID Management’ program, select your DID and
press the ‘Update’ button.
Now you can proceed to extend your model document.
28/31
ITP – How to get started with ITP
I
6.3 Extending your model document
Make sure that your model document (sample.doc) is selected in the ITP/CS ‘Model development’
program and press the ‘Edit button’ to open the document in your word processor.
Extend your document to the following:
# BEGIN
Tutorial
WITH Cust IN EXP.Customer DO
IF Cust.Gender = "M"
THEN # Mr. #
ELSE # Mrs. #
FI
#
@(Cust.Initials) @(Cust.Surname)
#
WITH Addr IN Cust.Address_of_customer DO
#
@(Addr.Street) @(numerals(Addr.Housenumber))
@(Addr.Postcode) @(Addr.City)
@(Addr.Country)
#
OD (* sub-entry Address_of_customer *)
#
@(date(today))
#
IF Cust.Gender = "M"
THEN # Dear Mr #
ELSE # Dear Ms #
FI
#
@(Cust.Surname),
You recently ordered items amounting to US$ @( amount( Calculate_total_debt
(Cust.Customer_number ) ) ). This concerns the following:
According to the terms of our agreement, payment is one week overdue. We kindly
ask you to make payment as soon as possible.
Yours sincerely,
P. Gonzales
#
OD (* main Customer entry *)
END #
The expression @( amount .....), printed in bold, is the only part added to the document.
29/31
ITP – How to get started with ITP
I
When you are finished, save and close the document and return to the ‘Model development’
program.
Select the ‘Create’ button again to compile your model document. If you did not make any
mistakes you should see the Status message: ‘Ready creating model, no errors’. If not a copy of the
model document will be opened in your word processor with the errors annotated. Press the ‘Edit’
button in the window above to open the original model document in your word processor. Correct
the errors and close both your model document as well as the error document. Next re-select the
‘Create’ button to compile the corrected document.
Testing your model
Tutorial
After successful compilation you can test your model document again by selecting the ‘Run’
button. If you have adapted your model document correctly, the result document will contain text
as similar to the output sample at the beginning of this chapter.
30/31
ITP – How to get started with ITP
I
7. How to get on with ITP?
7.1 Review
In this tutorial you have been working with a rather obvious example. On a step-by-step basis, you
developed one of several kinds of output. Normally you would want to produce all kinds of output,
most likely of a more complex nature. ITP is ideally suited to this.
You have been creating several ITP components in a rather simple way, to be able to create the
output from example 1 in chapter 1. These components are also sufficient to create a model
document for example 2 (the customer card).
For example 3 (a list of customers) you will have to create an additional ITP component, similar to
the Customer entry but then for retrieving all customer records. This is called a plural entry. More
information about defining plural entries can be found in the ITP/SDK AS/400 manual.
Tutorial
7.2 Future extensions
So far, you have been working with a subset of ITP's functionality. This goes for both DID
development as well as the model document . To compose more complex output such as financial
reports and policies, you will probably need to use a larger set of ITP's functionality than you have
been using so far.
Various other model development constructs are available, such as: variables, operators, repeat
constructs, arrays, functions, procedures and instructions to add simple user interactions. Other
ways of constructing your ITP DID components are available, such as: using different kinds of
entries, import and export entries in DID-sources and alias entries. Finally we did not pay any
attention to integrating ITP with your own application(s). ITP/CS provides a set of advanced Api’s
to run models and to pass keys and parameters to these models.
It is beyond the scope of this tutorial to go into more detail concerning these other ITP concepts.
Additional exercises could be the creation of the other kinds of output in chapter 1 of this tutorial
(examples 2 and 3). In such a case you can of course make use of the complete sample application
as a reference in checking your own operations. If you installed the ITP/CS examples you can also
take a look at some interesting model documents. These documents use a similar database as you
have been using in this tutorial.
31/31
I
ITP is developed by
For more information please contact us.
Telephone:
+31 24 371 02 30
Fax:
+31 24 371 02 31
WWW:
http://www.aia-itp.com/
Email:
[email protected]
Postal Adres:
POBox 38025
6503 AA Nijmegen
The Netherlands
Visiting Adres:
Kerkenbos 10-129
6546 BJ Nijmegen
The Netherlands