Welcome to the e-learning unit – Multi Threading in T24.

In this learning unit you will

learn how to write and compile multi threaded routines.

PRG10.Multi threaded routines-R13 1

 At the end of the session you will be able to

Understand how Multi threading in T24

Explain the different components of a multi threaded routine in T24

Create and Execute a multi threaded routine in T24

PRG10.Multi threaded routines-R13 2

 1 Multi threading was introduced with the R05 release of T24.

2 So has this changed the way we write all routines in T24? Actually no. Version and
Enquiry routines are still single threaded.

3 Multi threading has been extensively used in COB routines and Services (multi
threaded phantoms or background processes)

4 Multi threading obviously has its advantages over single threaded routines and allow
you to make maximum use of the server’s processor capabilities.

PRG10.Multi threaded routines-R13 3

 1 The simplest way to learn multi threading in T24 is to take a single threaded routine
and multi thread it.

2 The task given to you is to select all account records and print the currency and
working balances for each. Take a piece of paper and try to write down an algorithm
for this task.

3 This is what you would have come up with…

PRG10.Multi threaded routines-R13 4

 If you were to convert the algorithm to code, this is what you will come up with.
1 The first part contains the insert files that are part of all subroutines in T24.

2 Open the ACCOUNT application because that’s the file to read from

3 Form the SELECT statement and execute it to arrive at a list of all ACCOUNT ids.

4 For each Id in the list, the record is read and the required field details are extracted
and displayed.

Now if you were to execute this subroutine, one processes is started at operating
system level for this and this processes is solely responsible for processing the entire
list of Id’s. Now what if you could have multiple processes to process the same set of
Ids. Would this reduce the overall time for execution?

PRG10.Multi threaded routines-R13 5

 The multi threading concept in T24 is all about sharing the load or in other words the
task to be executed. One process at operating system level processing a list of Id’s will
be slower than multiple copies of the same process executing the same list of Id’s.

Executing multiple copies of the single threaded routine that you just wrote – will that
solve the problem? No it will not - since each copy of the routine will be selecting from
the ACCOUNT application and each will routine will process the same list of Ids.

PRG10.Multi threaded routines-R13 6

 So in order to multi thread successfully, the SELECT must be separate and not part of
the routine. Multiple copies of the code to process each id can be run independently.
Each copy is a process in itself at operating system level.

As discussed before – each process does not perform a select on ACCOUNT.

Thus the SELECT must happen independent of the routines processing the ids. So
how you access these id’s? If they are stored in memory, it is not possible to access
them. The only way is write them to a file and allow access to it.

PRG10.Multi threaded routines-R13 7

 So you have now seen that if you split the single threaded routine into two parts, you
are closer to achieving better performance.

PRG10.Multi threaded routines-R13 8

 This diagram shows the actual BASIC statements that you would write when splitting
the single thread into 2. Remember each part is a subroutine in itself. (You cannot
write code that is neither a program nor a subroutine in T24.)

1 The SELECT routine must be executed first otherwise the record processing
subroutine has nothing to work with.
2 The list of ids selected must be written into a common file so that the processing
subroutine (and multiple copies of it) know where to pick up ids from.
3 4 Multiple copies of the processing routine can now be started and the work load is
distributed.

PRG10.Multi threaded routines-R13

routines-R8.02 9
 1 Take a closer look at the code written in the record processing routine. There is a
CALL to the F.READ API. Two of the five parameters passed to the API are what is
returned from the OPF API which must be executed before an F.READ. Now there is
no need to perform an OPF for every Id processed. So where can you put this code?
The best option is available the use of common variables. Once initialised, they can be
re-used.

2 So, you now have to write a subroutine to LOAD or initialise these common
variables.

3 Since these common variables are specific to your routine, you must define them as
well.

PRG10.Multi threaded routines-R13

routines-R8.02 10
 So now you will agree that you must create a total of 4 components for every multi
threaded routine in T24. How 4? One subroutine to LOAD common variables, one
subroutine to SELECT the ids to be processed, one routine to process the ids (multiple
copies of this will be run) and one COMMON variable file.

You will now learn how to multi thread the subroutine you saw earlier.

PRG10.Multi threaded routines-R13

routines-R8.02 11
 Though it was listed as the last component of a multi threaded routine in the previous
slide, the common variables file must be created first. The jBASE COM keyword must
be used along with a unique name incase the same common variable names area is
used elsewhere, jBASE uses this unique name to avoid confusion of values.

The next component that must be created is called the .LOAD subroutine. If you
decide the name of your multi threaded subroutine is ACCOUNT.LIST, then this
subroutine must be called ACCOUNT.LIST.LOAD. In this subroutine, you must
initialise all the common variables defined in the common file. Remember to include
this common file in the .LOAD routine.

A good practice to follow when creating I_ files to hold common variables is to define
each variable on a new line and use the ;* to add a comment that describes the use of
each variable. For example, if you redid the I_ACCOUNT.LIST.COMMON it would
look like this

*Content of I_ACCOUNT.LIST.COMMON
COM /ACCOUNT.LIST/ FN.ACCOUNT, ;* File Name of the ACCOUNT file to be
opened
F.ACCOUNT, ;* File Path return from OPF for the ACCOUNT file

Refer to the core COMMON file I_GTS.COMMON for a clearer picture.

PRG10.Multi threaded routines-R13

routines-R8.02 12
 Once the .LOAD routine is ready, the SELECT routine can be coded. The name of
your select routine must contain the .SELECT key word. So in the example you are
looking at, it must be ACCOUNT.LIST.SELECT. In this routine, you will form and
execute the select statement. Remember the file that must contain the selected ids?
That is created in this routine using the core routine BATCH.BUILD.LIST. This routine
takes two parameters. The first one is a dynamic array with 7 values in total (will be
discussed a little later in this session) and the second is the actual list of Ids returned
from the execution of the SELECT statement. Without that line of code, your .SELECT
routine is useless.

Note: The file from which id’s have to be selected along with selection criteria can be
specified in the dynamic array passed as first parameter to BATCH.BUILD.LIST. This
eliminates the need for using EB.READLIST to perform the select.

The last component is the RECORD or PROCESS routine. It takes one parameter.
You guessed right, it is the ID from the list to be processed. The looping structure has
been left out of the subroutine logic totally.

Now that you have learnt the components of a multi threaded routine, let’s take a look
at how to execute it.

PRG10.Multi threaded routines-R13

routines-R8.02 13
 1. Every multi threaded routine in T24 must have a PGM.FILE entry with TYPE set to
B. A multi threaded routine has 3 components – so do they each get a PGM.FILE
entry?

2. No, there is only one PGM.FILE entry per multi threaded routine. The ID of the
PGM.FILE must be the name of the process or record routine. In the example that you
are looking at – ACCOUNT.LIST

3. How do we execute the .LOAD, .SELECT and the Record Routine

3.1 Can you execute it from the command prompt? No.
3.2 Can you attach it to a version or an enquiry? No.

PRG10.Multi threaded routines-R13 14

 1. Now do you have to execute each component manually? First the .LOAD, then the
.SELECT and finally multiple copies of the processing routine or the record routine?
No.

2. There is a T24 core routine called BATCH.JOB.CONTROL that is written

exclusively to execute multi threaded routines.

3. This multi-threaded routine can either be run as a Service or as a COB Job. This
learning unit does not include details on how to execute a service or COB. You will
learn this in the session on COB and its execution

4. A tSA (T24 Service Agent) is a program that eventually calls

BATCH.JOB.CONTROL.

5. So, then how do we say that a routine is running in a multithreaded fashion. How is
it improving performance? This is done by starting multiple tSA’s. The next slide will
help you visualise this better.

To sum things up, BATCH.JOB.CONTROL -

Splits the job into ‘multiple’ threads
Executes them simultaneously
Thus making optimum use of the available processors

PRG10.Multi threaded routines-R13 15

 As you know a multi threaded routine comprises of 3 parts. Each part is a separate
routine that does a specific task.

For example: If we look at a sample routine ROUTINE1, it will be made up of three

parts ROUTINE1.LOAD, ROUTINE1.SELECT and ROUTINE1 (This is called the
record routine).
2.Once the tSAs are started, each of the tSA’s execute the .LOAD routine.
3.Then only 1 of the tSAs will execute the .SELECT routine while the others wait. As a
result of the .SELECT routine a LIST file will be populated. This list file will contain the
actual list of ID’s to be processed from the database (as a result of the select
statement inside the .SELECT routine)
4. Once the LIST is ready, all the tSA’s will pick up ID’s from the list file, and start
executing the ID’s one by one by calling the record routine, viz the routine name itself
i.e. ROUTINE1 (does not have any suffix to it)

Q. Now, how is this different from single threaded routine?

Ans . In case of a single threaded routine, there would be just one routine that would
have the logic of .LOAD, .SELECT and execution built into it. Therefore, only 1 tSA
would process the whole routine. However, in case of a multi threaded routine, the
logic is split and written in the 3 separate routines, and multiple tSA’s can execute it at
the same time, thereby decreasing the total time taken to execute a routine, and
increasing throughput.

PRG10.Multi threaded routines-R13 16

 1. The call to BATCH.BUILD.LIST is the most important line of code in the .SELECT routine of any multi threaded
routine. This is the subroutine responsible for writing the selected Contract ID’s in to the LIST FILE. It takes two
parameters.
1.1 The first one is a dynamic arrays in which 7 positions can be used for various different uses.
1.2 The second one is the actual list of Contract IDs returned after the execution of the SELECT statement.

2. Lets assume the name of the first variable is PARAM. The variable name can be any generic name.
2.1 The first position in the array denotes the name of the list file to be created with the selected ids. This is always
null, T24 decides the name of the LIST FILE. Normally the name of the LIST FILE will be F.JOB.LIST.<Seq No> for
eg: F.JOB.LIST.1

2.2 The second position can be used to pass an application (F.APPLICATION name) so that BATCH.BUILD.LIST
itself can form and execute the SELECT for you.

2.3 The criteria for the selection can be passed in the third position if any.

2.4 The fourth position contains the last ID in the LIST FILE. So if the last record ID in the LIST FILE is 101, meaning
there are 101 records, this position will contain the value 101.

2.5 The fifth position contains the total number of contacts selected and written on to the list file. Let’s assume you
did a select on the FUNDS.TRANSFER application, and 110 contracts were selected and written, then 110 will be
returned by BATCH.BUILD.LIST to this position.

2.6 When T24 processes each ID from the list it is wrapped around a transaction boundary. Using the sixth position
you can decide at you own risk and bulk transactions. In other words, multiple ids can be processed in one
transaction boundary. The number of ids to bulk is mentioned here.

PRG10.Multi threaded routines-R13 17

 2.7 A multi threaded routine can have a .FILTER routine that can contain logic to filter the ids selected
but this is done before the list file is built.

PRG10.Multi threaded routines-R13 17

 The .FILTER routine is an optional part of a multi threaded routine in T24. It filters out
the IDs selected before actually building the list file.

This routine is called from BATCH.BUILD.LIST for each Contract ID selected, to

decide whether it must be part of the list file or not.

The routine has one parameter that must be set to NULL in order to discard the
current id from the list.

You must remember never to perform any IO from within the .FILTER routine as it will
be a performance bottleneck.

The routine must follow the naming convention used in the .LOAD and .SELECT

PRG10.Multi threaded routines-R13 18

 This is a sample program that will help you understand the parameters to
BATCH.BUILD.LIST. As you can see, LIST.PARAM is the first parameter passed.
ID.LIST is normally the list of contracts to be populated in the LIST FILE, in this case
the select is done by BATCH.BUILD.LIST itself and the output is stored in the LIST
FILE, therefore ID.LIST is null.
ID.LIST is an incoming parameter to the routine.

In this routine, a select is done on the FUNDS.TRANSFER file to select contracts in

which the DEBIT.AMOUNT is greater than zero. The result of the select is stored in a
LIST FILE.

You can also see the common variable BATCH.LIST.FILE has been hardcoded in this
routine. This should not be done as T24 will decide the name of the LIST FILE. In this
example I have used it for illustration purposes.

To execute this program, login to T24 once and log out, so that the common variables
are set.

PRG10.Multi threaded routines-R13 19

 The select statement formed is “SELECT FBNK.FUNDS.TRANSFER WITH
DEBIT.AMOUNT GT 0”. The total contracts selected is 45 and the last ID on the list
file is 45.

Show below is the screen shot of the contents of the LIST FILE.

PRG10.Multi threaded routines-R13 20

 1. CONTROL.LIST is a common variable declared in I_BATCH.FILES.

2. Multi threaded routines (jobs) though effective in distributing the load on multiple agents has a
drawback in terms of sequencing the job. For example, an accrual processing job in LD over a
weekend shall accrue for all the contracts on Friday, then again on Saturday and again on Sunday.
Here agents shall together process the accrual for Friday and on completion of this start the processing
for Saturday. After completing the same, it should go over to Sunday.
Here we cannot do the following:
a.) Select all contracts and accrue for Friday/Saturday/Sunday in one go, as we want to finish Friday’s
work and then go to Saturday
b.) Run three different jobs, as the list will become infinite
Thus, there is a requirement for jobs to determine sequences and multi thread within every
sequence. Both sequence and performance has to be kept in mind.

3. This can be filled in the .SELECT routine (only the first time) when it is invoked. And then .SELECT will
be invoked for every value in CONTROL.LIST. The first invocation where we fill in the values is the
invocation for the first value in CONTROL.LIST.

4. Since .SELECT is called multiple times, the job can perform the select accordingly (First time for
Friday, second time for Saturday etc…) and the LIST FILE will be populated. The processing then will
happen based on what is there in LIST FILE and once finished we will invoke .SELECT for the next
value in CONTROL.LIST

5. As you have already learnt, BATCH.JOB.CONTROL is the core routine that is responsible for executing
a Multi-threaded routine. Within this logic, there is a file called F.BATCH.STATUS, that contains the

PRG10.Multi threaded routines-R13 21

 status of the routine (also known as job) being executed. The value in CONTROL.LIST is written into
F.BATCH.STATUS along with the keyword “processing” to denote that the job is being processed.
Once all values in CONTROL.LIST are over, then the CONTROL.LIST is set as “processed” and
written to F.BATCH.STATUS

PRG10.Multi threaded routines-R13 21

 Important points to remember about CONTROL.LIST

1. CONTROL.LIST to be populated by jobs only when they want sequencing.

Otherwise core takes care of it

2. Jobs should fill in CONTROL.LIST only once in the .SELECT routine

3. CONTROL.LIST is updated in F.BATCH.STATUS. In the screen shot,

CONTROL.LIST is populated with two values AC and CUST. As is evident from
the snapshot, contracts have been selected for the first value ‘AC’ and the
corresponding LIST FILE is populated with the selected contracts. When all the
contracts are processed, the first line from F.BATCH.STATUS is deleted and the
second line becomes the first line. Selection of contracts is repeated for the
second value in the CONTROL.LIST that is CUST.

PRG10.Multi threaded routines-R13 22

 You are able to see a sample .SELECT routine where sequencing needs to be done
within the same job for ACCOUNT records and then for CUSTOMER records.

First time the .SELECT routine is called by BATCH.JOB.CONTROL, the value of

CONTROL.LIST will be NULL. Therefore, the values in CONTROL.LIST should be
stored separated by FM (Field Markers)

Always the first value in CONTROL.LIST will be the current value to be processed, as
you just learnt that once values are processed in CONTROL.LIST its removed from
the variable.

PRG10.Multi threaded routines-R13 23

 First time the select is done on the ACCOUNT file, and then on the CUSTOMER file in
the CALL.BBL block.

CONTROL.LIST variable is populated with dummy values AC and CUST, one for
account and the other for customer.

PRG10.Multi threaded routines-R13 24

 While running cob, we can view certain information shown in the console. This
information is stored in the user directory &COMO& for future references. The id
components of the file are “Tsa”, agent number, date and time. Each of the component
are separated by underscore. The core API OCOMO is called to display the batch
information on the console. Following information are updated by OCOMO in the
COMO directory
1)Batch Process name
2)Batch Name
3)Agent number
4)Current date
And
5)Current time.

PRG10.Multi threaded routines-R13 25

PRG10.Multi threaded routines-R13 26
PRG10.Multi threaded routines-R13 27
 1. FALSE – Only one entry for the actual process(record) routine
2. TRUE
3. FALSE – I_BATCH.FILES

PRG10.Multi threaded routines-R13 28

PRG10.Multi threaded routines-R13 29
PRG10.Multi threaded routines-R13 30