This chapter includes sections about the CallCoordinator application programming interfaces (APIs) and exit related to Transfer Load Balancing. These sections are:
This API allows applications to do any of these:
The CallCoordinator APIs are defined as general-use programming interfaces.
This CallCoordinator exit can access a customized version of the load balancing module. It is a product-sensitive programming interface. This module determines the least busy ACD group and sends the number to the requesting agent.
This exit may optionally be run to gather information about the least busy ACD group for the requested function, that is Balance points and Queue Count, without reserving the Transfer Load Balancing number
Each section of this chapter explains the function of the API or exit and describes when it would be useful. It also explains how to use the API and exit and defines the CICS communication data area.
The CallCoordinator APIs are defined as general-use programming interfaces. See "Programming Interfaces" for a definition of general-use programming interfaces.
When an application requires to transfer a call, it request the telephone number of an ACD group that performs the desired function. This API communicates that request to the CallCoordinator Load Balancing module. This module determines which ACD group is the least busy at that time. The API returns the number of the least busy ACD group along with a backup number.
The API may optionally be run to gather information about the requested function, that is Balance Points and Queue Count, without reserving the Transfer Load Balancing number. The API may also optionally be run to perform inter-switch transfer without finding the least-busy ACD group. By requesting and using these numbers, applications can help to balance the call load between ACD groups.
Refer to the Planning section of the CallPath CallCoordinator/CICS System Management Guide for information about how Transfer Load Balancing works.
The Transfer Load Balancing API is useful when:
For example, a CallCoordinator agent who handles auto insurance wants to transfer a call to a CallCoordinator agent who handles life insurance. There are several agent groups that handle life insurance. The agent requests the number of the least busy life insurance group by entering LIFE in a space provided on the auto insurance application screen. Then the following occurs:
To use the Transfer Load Balancing API in your application program, do the following:
If calling the API from COBOL II or later, INITIALIZE
the Communication data area
(CAMC705-LBA-COMMAREA-DATA)
before setting any of the fields.
Table 29. CICS Communication Data Area for the Transfer Load Balancing API (CAMC705)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| LBA-COMMAREA | N/A | N/A | 01 level name. |
| LBA-COMMAREA-LEN | PIC S9(04) COMP VALUE +250 | In | Length in bytes of the CICS communication data area. |
| LBA-COMMAREA-DATA | N/A | N/A | 03 level name. |
| FROM-PROGRAM-NAME | PIC X(08) | In | The name of the program invoking this API. |
| TO-PROGRAM-NAME | PIC X(08) | In | The name of this API (CAMI705C). |
| LBA-RETURN-CODE | PIC X(10) | Out | Indicates the result of the attempted
operation performed by the Load Balancing module.
See "Transfer Load Balancing Exit".
If an error condition persists, refer to
CallPath CallCoordinator CICS/MVS: Inbound Problem Determination for problem determination and recovery procedures for
each return code listed here.
Data about these errors is written to the active trace log, which is either the EZPTRAV or EZPTRBV log file. This data includes the actual ACD group name. The last character of the return code indicates the severity of the error:
|
| RETURN-CODE | PIC 9(04) | Out | Indicates the result of the attempted operation.
|
| ACTION | PIC X(1) | In | Indicates which action is to be performed.
Valid values are :
The default is 1 |
| CMCT-INDEX | PIC X(05) | In | The CMCT index of the call data record associated with the requesting transaction. |
| COR-SYSID | PIC X(04) | In | Sysid of COR owning the call. Required if CMCT-INDEX is passed. |
| REASON-CODE | PIC 9(04) | Out | For routing errors see "API Router".
|
| FILLER | PIC X(92) | N/A | Spaces. Reserved for future use. |
| ORIG-TERM-ID | PIC X(08) | In | Terminal ID (EIBTRMID) of the requesting agent. |
| FUNCTION | PIC X(10) | In | The name of the function of ACD groups that handle this type of call as defined in the Load Balancing Function Table. For example, LIFE for ACD groups that handle calls about life insurance. |
| PRIMARY-NUMBER | PIC X(32) | Out | The telephone number of the ACD group of indicated function that was determined the least busy by the Load Balancing module and reserved for the call transfer. It is the dialable pilot number of the selected ACD group if in same switch. It is an inter-switch tracking number for the ACD group number if in a different switch. The data is displayed unformatted, left-justified, and filled with spaces. |
| BACKUP-NUMBER | PIC X(10) | Out | The backup number associated with the pilot number of the selected ACD group. The agent uses the backup number if the call cannot be transferred to the target pilot number. The data is displayed unformatted, left-justified, and filled with spaces. |
| QUEUE-COUNT | PIC X(3) | Out | Contains the Queue Count for the ACD group identified by the PRIMARY-NUMBER. |
| BPN1 | PIC X(3) | Out | Balance Point Number 1 |
| BPN2 | PIC X(3) | Out | Balance Point Number 2 |
| ACD-GROUP | PIC X(06) | In | ACD group |
| LOGON-COUNT | PIC 9(3) | Out | Number of agents logged on to ACD group |
| AVAIL-COUNT | PIC 9(3) | Out | Number of agents available in ACD group |
| TOT-Q-COUNT | PIC 9(6) | Out | Cumulative number of calls that have been queued at this ACD group |
| TOT-Q-ABSTIME | PIC S9(15)
COMP-3 | Out | Cumulative amount of time that calls have been queued at this ACD group |
| FILLER | PIC X(17) | N/A | Spaces. Reserved for future use. |
The required input includes the desired function of the group to which the call is to be transferred (FUNCTION) and the ID of the requesting terminal (ORIG-TERM-ID), or CMCT-INDEX and COR-SYSID. See Table 29 for descriptions of the input fields for the data area of the API.
EXEC CICS LINK PROGRAM('CAMI705C')
COMMAREA(LBA-COMMAREA)
LENGTH(LBA-COMMAREA-LEN)
END-EXEC.
If the operation of the API was successful, the output fields of the communication data area contain the number for the selected ACD group and a backup number.
Sample program source code for the Sample Transfer Load Balancing program is provided as a source library member in the CallCoordinator SEZPSRCE target library, member name CAMB600C. Relevant code can be found in paragraph 9000-LINK-TO-LOAD-BALANCING.
+-------------Product-sensitive programming interface information--------------+
The Transfer Load Balancing Exit is an interface that provides input to the Load Balancing Module.
Refer to the Planning part of the CallPath CallCoordinator/CICS System Management Guide for information about how Transfer Load Balancing works.
CallCoordinator Call Tracking Manager continually monitors the queues of primary ACD groups, keeping count of all calls queued. When an agent requests a load-balanced number for call transfer, the Transfer Load Balancing API carries the request to the Load Balancing Module. See "Transfer Load Balancing API (CAMI705C)". The Load Balancing Module acts to fulfill the request by doing the following:
The API returns the numbers to the requesting agent. When the requesting agent transfers the call to the load-balanced number, the call and screen are transferred. This requires the following events when the transfer is to a different switch:
The CallCoordinator Load Balancing Module contains a load balancing algorithm that you can customize. It determines which ACD group of a particular function is the least busy. You can write your own algorithm to perform this function and use the Load Balancing exit for access.
Before you can customize Transfer Load Balancing using static balancing points, you must understand three load balancing activities:
Transfer Load Balancing looks at the queue count for an ACD group and compares it to the balance points to determine busy level. The queue count in the CallCoordinator Balance Point table is incremented for each queue event. If the call is queued to multiple ACD groups, the queue count for the primary ACD group is the only one incremented. The queue count is decremented when the call is assigned or abandoned. (An ACD group is identified by its switch and target pilot number.)
Transfer Load Balancing uses two balance points to determine the busy level of the queue for each ACD group. Balance point 1 is the number of calls in a queue that an ACD group can handle comfortably at any given time. Balance point 2 is the maximum number of calls in a queue that an ACD group can handle before overload occurs.
The busy levels are as follows:
Selecting the Least Busy ACD Group:
Transfer Load Balancing selects the least busy ACD group in the following way:
The Percent Busy Number (PBN) is used when more than one ACD group is at the lowest busy level. Transfer Load Balancing compares the queue count and Balance Points for each available ACD group to calculate which group is least busy:
When calculating the PBN, the decimal fractions are truncated. The PBN is calculated as follows:
'PBN' equals 'QC' over 'BP1' times 100
'PBN' equals lparen 'QC' minus 'BP1' rparen over lparen 'BP2' minus 'BP1' rparen times 100
'PBN' equals lparen 'QC' minus 'BP2' rparen over lparen '10000' minus 'BP2' rparen times 100
Table 30 and the explanations
that follow show how Transfer Load Balancing
uses the busy levels and percent busy numbers (PBN) to assign
calls to less busy groups.
Table 30. Busy Levels and Percent Busy Numbers
| Group | Balance point 1 | Balance point 2 | Queue Count | Busy Level | PBN |
|---|---|---|---|---|---|
| Group 1 | 4 | 10 | 5 | 1 | 16% |
| Group 2 | 4 | 7 | 4 | 1 | 0% |
| Group 3 | 9 | 18 | 7 | 0 | 77% |
| Group 4 | 1 | 4 | 5 | 2 | 0% |
Table 30 shows the following about each group:
Before setting balance points for a group, you must consider the following items:
These items are discussed in detail in the sections that follow.
Time of Operation: In setting balance points for a group, you first must look at the hours of operation for your call center. If the level of call activity varies during a day or from one day to another, you should define those time periods based on the differences in call activity. You might enter this information on the CallCoordinator Balance Point Work Sheet. The times specified are based on the specific switch on which the target pilot number is defined.
For example, assume the call activity for an ACD group that handles orders is as follows:
You would set up these four time periods for the billing ACD group as follows before considering the other factors involved in setting balance points:
Any day and time not specified in a detail record defaults to the ACD group and backup number.
Group Characteristics: After deciding the important time periods for transferred calls for each group, you must consider the following characteristics in setting balance points for each group:
If you do not want this group to handle any transferred calls for some specific time period, you should set both balance points to zero for that time period.
Alternatively, you can customise Transfer Load Balancing to use dynamic ACD data. See "When to Customize the Load Balancing Algorithm".
Specific Balance Point Settings: Specific balance point settings cause specific results with Transfer Load Balancing operation. You need to consider the following additional items before setting the balance points:
After you have considered all of the above items, you can enter the balance points for each group on the CallCoordinator Balance Point panel (refer to the Operations part of the CallPath CallCoordinator/CICS System Management Guide. ). When your system has been in operation for several weeks, you might need to reset the balance points to improve your level of client service.
When a new ACD group is added, or a new date/time record is added, the algorithm may not immediately toggle between two eligible ACD groups. The algorithm requires that the least selected of two or more eligible ACD groups is selected. This will result in one group being selected until its number of times selected catches up with the other eligible ACD groups. To avoid this, the CallCoordinator host needs to be recycled.
The CallCoordinator Transfer Load Balancing module uses an algorithm that distributes the load of transferred calls between groups on the same switch or between groups on more than one switch. The steps that follow show how Transfer Load Balancing works between groups on the same switch. The additional steps for Transfer Load Balancing between switches are described in the section that follows.
Transfer Load Balancing on One Switch: The Transfer Load Balancing algorithm distributes the load of transferred calls between groups on one switch as follows:
The Transfer Load Balancing module uses the same algorithm to distribute the load of transferred calls between ACD groups on several switches. However, the following conditions are checked besides the basic algorithm:
Some application programs might require different logic for selecting load balanced numbers. Possible reasons to customize the load balancing algorithm are:
This could include compensating for different levels of training and experience between agent groups.
This could include adjusting the queue counts of distant or more highly paid agent groups.
APAR PQ35941 (PTF UQ41518) enhanced Transfer Load Balancing so that the Load Balancing Algorithm has the following additional data available to enable you to determine the least busy ACD group:
To write and use your own version of the load balancing algorithm, do the following:
Table 31. CICS Communication Data Area Between the Load Balancing Program and API/CTM (CAMC025)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) COMP VALUE +300 | In | Length in bytes of the CICS communication data area. |
| COMMAREA-DATA | N/A | N/A | 03 level name. |
| FROM-PROGRAM-NAME | PIC X(8) | In | The name of the program invoking this API. |
| TO-PROGRAM-NAME | PIC X(8) | In | The name of this API (CAMB600C). |
| RETURN-CODE | PIC X(10) | Out | Indicates the result of the attempted
operation.
If an error condition persists, refer to
CallPath CallCoordinator CICS/MVS: Inbound Problem Determination for problem determination and recovery procedures for
each return code listed here.
Data about these errors is written to the active trace log, which is either the EZPTRAV or EZPTRBV log file. This data includes the actual ACD group name. The last character of the return code indicates the severity of the error:
|
| FILLER | PIC X(110) | N/A | Spaces. Reserved for future use. |
| SWITCH-ID | PIC X(8) | In | Switch ID of the requesting agent. |
| FUNCTION | PIC X(10) | In | Function name (for example, "LIFE"). This name must be an entry in the Load Balancing Function Table. |
| FILLER | PIC X(50) | N/A | Spaces. Reserved for future use. |
| ACD-GROUP | PIC X(6) | Out | Least busy ACD group name. |
| ACD-SWITCH | PIC X(8) | Out | Switch ID of the ACD group. |
| QUEUE-COUNT | PIC 9(3) | Out | Queue count of the ACD group. |
| BPN1 | PIC X(3) | Out | Balance Point Number 1 of the ACD group. |
| BPN2 | PIC X(3) | Out | Balance Point Number 2 of the ACD group. |
| BKUP_NBR | PIC X(10) | Out | The backup number to be displayed on your business application screen. The agent calls this number if the call cannot be transferred to the reserved primary number. |
| LOGON-COUNT | PIC X(3) | Out | Number of agents logged on to ACD group |
| AVAIL-COUNT | PIC X(3) | Out | Number of agents available in ACD group |
| TOT-Q-COUNT | PIC 9(6) | Out | Cumulative number of calls that have been queued at this ACD group |
| TOT-Q-ABSTIME | PIC S9(15)
COMP-3 | Out | Cumulative amount of time that calls have been queued at this ACD group |
| FILLER | PIC X(40) | N/A | Spaces. Reserved for future use. |
Sample program source code for the load balancing algorithm is provided as a source library member in the CallCoordinator SEZPSRCE target library, member name CAMB600C.
+----------End of Product-sensitive programming interface information----------+
