Application Programming Guide

Chapter 4. Intelligent Answering

This chapter includes sections about the CallCoordinator application programming interfaces (APIs) related to intelligent answering. These sections are:

"Initiate With Data Interface (CAMC500)".
This interface is used to pass call-related data to a transaction.
"Inquire Call Data API (CAMI726C)" and "Inquire Party Data API (CAMI727C)".
These APIs allow programs to get call and party data from the Call Management Control Table (CMCT).

Each section explains the function of the interface and describes when it would be useful. It also explains how to use the interface and APIs and defines the CICS communication data area required for each one.

Also related to Intelligent Answering is the Set ANI ID API. It allows programs to update the ANI data associated with a call. See "Set ANI ID API (CAMI786C)" for more information about this API.

These CallCoordinator APIs are defined as general-use programming interfaces. See "Programming Interfaces" for a definition of general-use programming interfaces.

Initiate With Data Interface (CAMC500)

What This Interface Does

The Initiate With Data Interface enables CallCoordinator to pass key data about an incoming call to the initial transaction for that call. The initial transaction is the application program specified on the COR Telephony Settings panel, or the Agent Detail panel, or as specified by the CallCoordinator agent at signon. Refer to the Installation part and the Operations part of the CallPath CallCoordinator/CICS System Management Guide for details about indicating initial transactions for CallCoordinator. When the Initiate With Data Interface is indicated for an initial transaction, CallCoordinator passes the data to the Interface when it initiates the transaction.

This transaction can be initiated by an EXEC CICS START command, or an EXEC CICS RETURN IMMEDIATE command, depending on the option specified in the SPM Start Option. In order for the initial transaction to go through the CICS Dynamic Transaction Routing (DTR) exit, an EXEC CICS RETURN IMMEDIATE must be used.

See Table 18 for a complete description of the Initiate With Data interface data.

When to Use This Interface

There are several ways you can use the data of this interface in the initial transaction of an application program. Many of these are related to the Automatic Number Identification (ANI) and Dialed Number Identification Service (DNIS) numbers, which can be provided with incoming calls. The following sections provide definitions and examples of how to use these numbers.

ANI

The ANI number associated with a call is the billing number of the calling party.

Your application program(s) can use ANI numbers to:

Find other information in your customer database and display it to the agent handling the call
Collect telephone numbers of customers for whom you have no telephone number on file
Identify new customers and prompt the agent to collect data for the new customer data record
Identify what areas (by area code) calls are coming from.

The Set ANI ID API allows updating the ANI information in the CMCT record for an active call. See "Set ANI ID API (CAMI786C)".

DNIS

The DNIS number associated with a call enables identification of the specific toll free number dialed by the caller when there are multiple toll free numbers in the same routing arrangement.

Your application program(s) can use DNIS numbers to:

Determine the intent of the caller, the service desired by the caller, and the display or data needed to handle the call. For example, the 800 numbers for several mail order catalogs are routed to a single group of agents. The application program uses the DNIS number to identify the catalog related to a call and to determine the display and data needed by the agent.
Determine the language needs of the caller. For example, Spanish-speaking agents receive calls from Spanish-speaking callers on an 800 service advertised as such. The application program uses the DNIS number to determine when to present Spanish displays to agents.

Your application programs might require disabling of the CallCoordinator Initiate With Data Interface. This could be because:

The application program requires its own starting data, or
The lack of data is used to indicate the first invocation of the transaction for a call, or
The CallCoordinator Initiate With Data Interface does not provide all of the data required by transactions of the application program.

In this case, your application program can use the Inquire Call Data API, Inquire Party Data API, or Inquire Call Tracking Parameters API to get data for a transaction. (The Inquire Call Tracking Parameters API will be deleted in the next release of this product.) See "Inquire Call Data API (CAMI726C)", "Inquire Party Data API (CAMI727C)" for more information.

How to Use This Interface

To use the Initiate With Data Interface to pass data to your application program(s), do the following:

Enter Y or R in the SPM Start option field of the COR Telephony Settings or Agent Detail panels. This is usually an installation task. Refer to the installation part of the CallPath CallCoordinator/CICS System Management Guide for more information.
Alternately, the agent can indicate this when signing on to CallCoordinator. In this case, the option applies to that agent only.

Create a CICS communication data area in working storage of the program by copying the layout for this interface. The fields for this data area are described in Table 18. The layout is provided as a copy library member in the CallCoordinator SEZPCOPY target library, member name CAMC500. Refer to the library member for the actual field names.

Table 18. CICS Communication Data Area for the Initiate With Data Interface (CAMC500)

Field Attributes Description
START-DATA N/A 01 level name.
START-TIME PIC S9(07) COMP-3 The time the transaction is started. Format HHMMSS.
START-DELAY PIC S9(03) COMP-3 The maximum time (seconds) that screen transfer can be delayed before it is abandoned. This value is defined in the COR Telephony Settings panel.
CNTL-NBR PIC X(30) Control number or account number of the caller entered using the Set Control Number API. May be obtained from customer database using the ANI number. May be used to tie status of call being tracked by CallCoordinator to your application. Can be alphanumeric and in any format.
CMCT-INDEX PIC 9(04) The index number of the CMCT entry that contains the data for this call.
CALLER PIC X(10) The telephone number of an internal caller.
DNIS-TABLE PIC X(02) The number of the DNIS routing table that was configured for the trunk group and that contains the DNIS number dialed for this call. Blank if the DNIS feature is not available or a DNIS number was not dialed.
DNIS-NUMBER PIC X(32) The last 10 characters of the DNIS number dialed by the caller. Used to determine the initial transaction to be started. Optional. Blank if the DNIS feature is not available or a DNIS number was not dialed. May be used to determine the initial transaction.
ANI-TABLE PIC X(02) The source of the ANI number.

00
From switch.
Ax
The first digit, "A," indicates that the ANI number was updated using the Set ANI ID API. The second digit is a user-defined code for ANI numbers. See Table 33 for the definition of ANI-ID-CODE.
Blank
ANI not present.

ANI-NUMBER PIC X(32) The last 10 characters of the telephone number (billing number) of the calling party.
SPM-START-OPTION PIC X(1) Initial transaction start option. Indicates whether CallCoordinator passes the Initiate With Data Interface data block to the initial transaction at start time. Valid values are:

Y
Send data.
N
Do not send data.
I
Return immediate without data
R
Return immediate with data
Blank
Process as defined in the COR Telephony Settings panel. To change this field to spaces, move low values into this field.

APPL-CONN-IDX PIC 9(9) Application connection index. One of the call indices. Used for call tracking and record identification. Sequence number generated by CallCoordinator Call Tracking Manager(CTM). Incremented for each new call except for call join or the first party add to an existing call. Not incremented for party adds after the first party add in the same telephony session. Value is the same as the Unit Of Work Index, except when two telephony sessions are combined.
COR-SYSID PIC X(4) CICS SysID of the COR.
RESERVED PIC X(18) An area used by CallCoordinator Screen Control Module. Do not use this field.
LENGTH PIC S9(04) COMP Value +207 Length in bytes of the data area sent from CallCoordinator to the STARTed initial transaction.
TASK-SEQ PIC X(54) The task sequencing work area used to start other programs. Do not Use this field.
CALLER-TYPE PIC X(01) The type of caller.

Field	Attributes	Description
START-DATA	N/A	01 level name.
START-TIME	PIC S9(07) COMP-3	The time the transaction is started. Format HHMMSS.
START-DELAY	PIC S9(03) COMP-3	The maximum time (seconds) that screen transfer can be delayed before it is abandoned. This value is defined in the COR Telephony Settings panel.
CNTL-NBR	PIC X(30)	Control number or account number of the caller entered using the Set Control Number API. May be obtained from customer database using the ANI number. May be used to tie status of call being tracked by CallCoordinator to your application. Can be alphanumeric and in any format.
CMCT-INDEX	PIC 9(04)	The index number of the CMCT entry that contains the data for this call.
CALLER	PIC X(10)	The telephone number of an internal caller.
DNIS-TABLE	PIC X(02)	The number of the DNIS routing table that was configured for the trunk group and that contains the DNIS number dialed for this call. Blank if the DNIS feature is not available or a DNIS number was not dialed.
DNIS-NUMBER	PIC X(32)	The last 10 characters of the DNIS number dialed by the caller. Used to determine the initial transaction to be started. Optional. Blank if the DNIS feature is not available or a DNIS number was not dialed. May be used to determine the initial transaction.
ANI-TABLE	PIC X(02)	The source of the ANI number. 00 From switch. Ax The first digit, "A," indicates that the ANI number was updated using the Set ANI ID API. The second digit is a user-defined code for ANI numbers. See Table 33 for the definition of ANI-ID-CODE. Blank ANI not present.
ANI-NUMBER	PIC X(32)	The last 10 characters of the telephone number (billing number) of the calling party.
SPM-START-OPTION	PIC X(1)	Initial transaction start option. Indicates whether CallCoordinator passes the Initiate With Data Interface data block to the initial transaction at start time. Valid values are: Y Send data. N Do not send data. I Return immediate without data R Return immediate with data Blank Process as defined in the COR Telephony Settings panel. To change this field to spaces, move low values into this field.
APPL-CONN-IDX	PIC 9(9)	Application connection index. One of the call indices. Used for call tracking and record identification. Sequence number generated by CallCoordinator Call Tracking Manager(CTM). Incremented for each new call except for call join or the first party add to an existing call. Not incremented for party adds after the first party add in the same telephony session. Value is the same as the Unit Of Work Index, except when two telephony sessions are combined.
COR-SYSID	PIC X(4)	CICS SysID of the COR.
RESERVED	PIC X(18)	An area used by CallCoordinator Screen Control Module. Do not use this field.
LENGTH	PIC S9(04) COMP Value +207	Length in bytes of the data area sent from CallCoordinator to the STARTed initial transaction.
TASK-SEQ	PIC X(54)	The task sequencing work area used to start other programs. Do not Use this field.
CALLER-TYPE	PIC X(01)	The type of caller.

Get the data into the data area using the following CICS command:

        EXEC CICS RETRIEVE INTO(CAMC500-START-DATA)
                           LENGTH(CAMC500-LENGTH)
                           END-EXEC.

Inquire Call Data API (CAMI726C)

What This API Does

This API enables an application program to get data about a call from the Call Management Control Table (CMCT). The Call Management Control Table (CMCT) is the product of CallCoordinator call tracking. It tracks the status of calls in progress, records current information about incoming calls, and supplies control functions for each telephone call. Each call in progress in CallCoordinator has an entry in the Call Management Control Table.

The CMCT data includes the following:

Call data from the switch.
Event message data created by CallCoordinator.
Data from the Agents Table.
ANI and DNIS numbers.
The Set ANI ID API allows updating the ANI information in the CMCT record for an active call. See "Set ANI ID API (CAMI786C)".
Business data from the Set Control Number API.
See "Set Control Number API (CAMI730C)" for more information about using this API.

See Table 19 for descriptions of all the data provided by the Inquire Call Data API.

To locate the correct entry in the CMCT, this API uses input from the application program. The input can be one or more of the following parameters:

CMCT Index (SRCH-CMCT-INDEX), and the SYSID of the COR (SRCH-COR-SYSID).
The ID number of the terminal of the agent handling the call (SRCH-TERM-ID)
Combination of the ID of the switch of the agent handling the call (SRCH-SWITCH-ID), the telephone number of the agent handling the call (SRCH-PARTY-NO), and the telephone number type of the agent handling the call (SRCH-PARTY-TYPE).

When more than one search field is input, they are checked to ensure agreement.

In a sysplex environment, if the API is searching on CMCT-INDEX the SYSID of the COR where that CMCT INDEX is active is required as input to the SRCH-COR-SYSID field. The COR-SYSID is made available in the CAMC500-START-DATA area and the TRIGGER-DATA area.

When the SRCH-CMCT-INDEX field is the only input parameter, the API output does not include the CMCT Index of a simultaneous call involving the party of this call. When the other input parameters are used (SRCH-TERM-ID or a combination of SRCH-SWITCH-ID, SRCH-PARTY-NO, and SRCH-PARTY-TYPE), the API output does include the CMCT index of a simultaneous call involving the party of this call. This field is SRCH-PREV-CMCT-INDEX. The API can use this data as input in the CMCT-INDEX field to get the call data for this associated call. This output might include another SRCH-PREV-CMCT-INDEX for a third call involving the party.

In a sysplex environment the SRCH-COR-SYSID is required.

Providing Call Related Data from Original Call

Call related data from the original call can be supplied to the business application associated with a related call.

How calls are tracked by CallPath/CICS for OS/390: As defined by the CallPath Services Architecture, a call comprises two parties (for example, caller and agent/IVR extension) each with a connection ID which represents their participation in the call. When a new, CallPath/CICS-tracked call comes into the call center, a call tracking record is created. This represents the original call between the caller and the call center agent or IVR. Associated with this call may be ANI and/or DNIS, any customer data added via the Set Control Number API, and any ANI number updated via the Set ANI API. The Application Connection ID (ACI) assigned and maintained by CallCoordinator is also always present in the call tracking record.

If the call is extended to another party, a new, related call tracking record is created which represents the call between the transferring agent/IVR and the new party (for example, a second agent). Until the transferring agent/IVR completes the transfer, two call tracking records exist: one representing the original call and a second representing the related call.

If the Call extension as transfer parameter is set to N, none of the call data from the original call is reflected in the second, related, call tracking record until the transfer is completed and the two call tracking records are joined. The combined original and the 'related' call tracking records now reflect the call between the caller and the second agent/IVR and all of the original call data information will be present in the call tracking record.

From a business application perspective the first call will be associated with the terminal of the first, transferring, agent/IVR and the second call associated with the terminal of the second, receiving, agent. The timing of the availability (and location) of the original call data will affect the processing the business application running on the second agent's terminal.

Original Call Data: Call data associated with the original call is included in the related Inquire Call Data API commarea fields prefixed with 'CAMC726-ORIGINAL' ONLY if the transfer has not completed. The CALL-PARENTAGE field indicates that this is a related(R) call tracking record. If the transfer has completed, the call data is in the normal CAMC726 commarea fields returned to the Inquire Call Data API call and the CALL-PARENTAGE field will indicate that this is a original(O) call tracking record.

See Table 19 for descriptions of the input fields of this API.

When to Use This API

You can use this API whenever an application program needs CMCT data for an initial transaction. The application program might need the data in order to provide the appropriate display and data for the agent handling a call (intelligent answering).

This API can also be used to get data for records sent to the CallCoordinator MIS log. See "Write MIS Record API (CAMI700C)" for information about writing an application program that writes its own records to the MIS Log.

The Inquire Call Data API provides the same data available in the Initiate With Data Interface as well as additional data not in the Initiate With Data Interface. An application program can use the Inquire Call Data API to add to the Initiate with Data data. Alternatively, the application program can use the Inquire Call Data API for the common data when there is a reason not to use the Initiate With Data interface. Reasons for disabling the Initiate With Data Interface include:

Some application programs require their own starting data.
The lack of starting data is used to indicate the first invocation of the transaction for a call.

How to Use This API

To use the Inquire Call Data API in your application program, do the following:

Create a CICS communication data area in working storage by copying the layout for this API. The fields for this data area are described in Table 19. A layout for this data area is provided in the CallCoordinator SEZPCOPY target library, member name CAMC726. Refer to the library member for the actual field names.

If calling the API from COBOL II or later, INITIALIZE the Communication data area (CAMC726-COMMAREA-DATA) before setting any of the fields.

Table 19. CICS Communication Data Area for the Inquire Call Data API (CAMC726)

Field Attributes In/Out Description
COMMAREA N/A N/A 01 level name.
COMMAREA-LEN PIC S9(4) COMP VALUE +1024 In The length in bytes of the CICS communication data area.
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 (CAMI726C).
RETURN-CODE PIC 9(04) Out Indicates the result of the attempted operation.

0
No errors were detected. The process completed.
1
An error was detected. The specified table entry was not found.
2
The search fields are in conflict. An entry was found that matched one field, but not another.
8
API routing error. See the reason codes under "API Router".
9
See REASON-CODE

SRCH-CMCT-INDEX PIC X(05) In The relative record number of the record in the CMCT. Primary search field. When this field is the only input parameter, output does not include SRCH-PREV-CMCT-INDEX.
SRCH-TERM-ID PIC X(08) In Identification number of agent's terminal, if the agent is signed on and terminal is not disabled. Secondary search field. When this field is input, output includes SRCH-PREV-CMCT-INDEX.
SRCH-SWITCH-ID PIC X(08) In ID of the switch of the agent handling the call. Part of the search field. The complete search field is:

SRCH-CMCT-INDEX
SRCH-TERM-ID
SRCH-SWITCH-ID
SRCH-PARTY-TYPE.
SRCH-PARTY-NO
SRCH-COR-SYSID
When the complete search field is input, output includes SRCH-PREV-CMCT-INDEX.
SRCH-PARTY-TYPE PIC X(01) In Agent's telephone number type. Part of the search field. The complete search field is:

SRCH-CMCT-INDEX
SRCH-TERM-ID
SRCH-SWITCH-ID
SRCH-PARTY-TYPE.
SRCH-PARTY-NO
SRCH-COR-SYSID
When the complete search field is input, output includes SRCH-PREV-CMCT-INDEX.

0
Unknown.
1
Extension.
3
Pilot.
4
Agent ID.
T
Trunk.

SRCH-PARTY-NO PIC X(08) In Agent's telephone number. Part of the search field. The complete search field is:

SRCH-CMCT-INDEX
SRCH-TERM-ID
SRCH-SWITCH-ID
SRCH-PARTY-TYPE.
SRCH-PARTY-NO
SRCH-COR-SYSID
When the complete search field is input, output includes SRCH-PREV-CMCT-INDEX.
SRCH-PREV-CMCT- INDEX PIC 9(05) Out The CMCT index for a simultaneous call involving the same party. Only output when the input parameters include SRCH-TERM-ID or a combination of SRCH-SWITCH-ID, SRCH-PARTY-NO, and SRCH-PARTY-TYPE.
PARTY-SEQ-NO PIC 9(02) Out Sequence number of party in the call. If CMCT-INDEX is only parameter provided, PARTY-SEQ-NO will be set to blank.
SRCH-NEXT PIC X(01) N/A Reserved
SRCH-BASE PIC 9(04) N/A Reserved
REASON-CODE PIC X(04) Out

16
The length of the Commarea was specified incorrectly.
20
A table addressability error.
10xx
For IBM problem determination only.

SRCH-COR-SYSID PIC X(04) In The SYSID of the COR in which to call the API. Used with CMCT Index for sysplex environments only.
FILLER PIC X(58) N/A Spaces. Reserved for future use.
CMCT-INDEX PIC 9(05) Out The relative record number of the record in the CMCT.
MSG-DATE PIC X(8) Out Date last message was received from the switch.
MSG-TIME PIC X(9) Out Time last message was received from the switch.
CTM-SEQ PIC 9(02) Out Sequential number assigned to records in the CMCT.
CTM-CNTR PIC 9(03) Out Count of records written that are of same type as last record written.
UOW-APPLID PIC X(8) Out ID of the CallCoordinator region which initiated processing of the work unit.
UOW-NO PIC X(12) Out Sequential number assigned to an individual telephony session (call) and all related calls.
CX-APPLID PIC X(8) Out ID of the CallCoordinator region which initiated processing of the call.
CX-NO PIC X(12) Out Call index number (assigned to call using the event message time and the CTM-SEQ number).
APPL-CONN-ID PIC S9(09) Out One of the call indices. Used for call tracking and record identification. Sequence number generated by CallCoordinator Call Tracking Manager(CTM). Incremented for each new call except for call join or the first party add to an existing call. Not incremented for party adds after the first party add in the same telephony session. Value is the same as the Unit Of Work Index, except when two telephony sessions are combined.
MSG-DATE-SUB PIC X(8) Out Date in last message.
MSG-TIME-SUB PIC X(9) Out Time in last message.
MSG-TYPE PIC X(3) Out Identifies the last message type for the call. Messages from CallPath/CICS begin with C.

C00
Call alerting.
C01
Call connected.
C02
Call held.
C03
Call rejected.
C04
Call routed.
C05
Call transferred.
C06
Disconnected.
C07
Feature invoked.
C08
Request instruction.
C09
Response.
C10
Setup.
C11
Party status.
C12
Call conferenced.
C13
Call alternated.
C14
Call parked.
C15
Call picked.
C16
Network reached.
C17
Switch status.
C18
Indicator provided.
C19
Data collected
C20
Resource deleted
C21
Call parties
C22
ACD information
C23
Hardware status
C24
Call action provided
C25
Call party removed
P00
Pseudo call alerting.
P01
Pseudo call connected.
P02
Pseudo extend call.
P03
Pseudo transfer call.
P04
Pseudo conference call.
P05
Pseudo retrieve call.
P06
Pseudo disconnected.
R00
Rejected pseudo call alerting.
R01
Rejected pseudo call connected.
R02
Rejected pseudo extend call.
R03
Rejected pseudo transfer call.
R04
Rejected pseudo conference call.
R05
Rejected pseudo retrieve call.
R06
Rejected pseudo disconnected.
S02
Call tracking cleanup (CAMT205C - V205)

SWITCH PIC X(8) Out ID of the switch of the agent handling the call.
CALL-SOURCE PIC X(01) Out Indicates source of the call:

I
CallCoordinator.

CALL-PARENTAGE PIC X(01) Out Indicates call parentage:

O
Original call -- involves no previous call on hold.
R
Related call -- results from a party placing another call on hold in order to transfer, conference, or consult.

CALL-STATE PIC X(01) Out Indicates the state of the call in progress:

A
Alerting.
C
Calling.
D
Disconnected.
H
Held.
P
Pending.
Q
Queuing.
R
Routing.
T
Connected.
W
Queued.
X
Holding.
Blank
n/a.

END-CODE PIC X(01) Out Indicates how the call ended. Not applicable in an active call.

A
Abandoned.
C
Completed.
D
Deleted.
J
Joined.
L
Link lost.
S
Shutdown.
Blank
n/a (Call has not yet ended.).

PARTY-COUNT PIC 9(02) Out Number of parties in the call.
PARTY-MIX-INX PIC 9(03) Out An index that changes when there is a change in the parties participating in a call.
CNTRL-NO PIC X(30) Out Control number or account number of the caller. Entered using the Set Control Number API.
BUS-VLU PIC 9(12) Out Business value assigned to the call. Entered using the Set Control Number API.
ORIGINAL-BUS-VLU PIC 9(12) Out As for BUS-VLU except that this applies to the ORIGINAL call if one exists.
BUS-VLU-SIGN PIC X(01) Out Sign of the business value.

+
Positive.
-
Negative.
Blank
n/a.

ORIG-GROUP PIC X(10) Out Pilot number used to access the original ACD group as opposed to that of an overflow ACD group which might have answered the call.
CALL-PURPOSE PIC X(01) Out Indicates the purpose of the call:

P
Pending.
S
Service.
X
Server change.
C
Conferee Change.
U
Unknown.

TRANSID PIC X(8) Out Initial Transaction ID indicated for calls requiring screen processing by CallCoordinator Screen Control Module (Automatic mode).
USER-TRANSID PIC X(8) Out Initial Transaction ID indicated for calls requiring screen processing by a user-written screen control program (User mode).
SRVR-FUNCTION PIC X(10) Out The function of the server agent for the call.
SRVR-ID PIC X(10) Out The ID number of the agent handling the call.
ANI-SOURCE PIC X(2) Out The source of the Automatic Number Identification (ANI) data.

00
From switch.
Ax
The first digit, "A," indicates that the ANI number was updated using the Set ANI ID API. The second digit is a user-defined code for ANI numbers. See Table 33 for the definition of ANI-ID-CODE.
Blank
ANI data is not present.

ANI-NUMBER PIC X(32) Out The ANI number (the billing number of the calling party). Left-justified and filled with spaces.
ORIGINAL-APPL-CONN-ID PIC S9(09) Out One of the call indices. As for AAPL-CONN-ID except that this applies to the ORIGINAL call if one exists.
ORIGINAL-CNTRL-NO PIC X(30) Out As for CNTRL-NO except that this applies to the ORIGINAL call if one exists.
ORIGINAL-BUS-VLU-SIGN PIC X(01) Out As for BUS-VLU SIGN except that this applies to the ORIGINAL call if one exists.
ORIGINAL-ORIG-GROUP PIC X(10) Out As for ORIG-GROUP except that this applies to the ORIGINAL call if one exists.
ORIGINAL-ANI-SOURCE PIC X(2) Out As for ANI-SOURCE except that this applies to the ORIGINAL call if one exists.
ORIGINAL-ANI-NUMBER PIC X(32) Out As for ANI-NUMBER except that this applies to the ORIGINAL call if one exists.
DNIS PIC X(32) Out The dialed number identification service (DNIS) number (if any) dialed by the caller and passed by the switch. Used to determine the initial transaction to be started.

ORIGINAL-DNIS PIC X(32) Out As for DNIS except that this applies to the ORIGINAL call if one exists.
DATA-COLLECTED PIC X(512) Out The data collected as input from the telephone keypad.
PARTY-GROUP PIC X(10) Out The pilot number used to access the ACD group that is currently handling the call.
PREV-PRTY-GROUP PIC X(10) Out The pilot number used to access the ACD group that was previously handling the call.
RESERVED-1 PIC X(24) N/A Reserved for IBM use.
FILLER PIC X(47) N/A Spaces. Reserved for future use.
PROGRAM-DATA PIC X(512) Out The program data associated with this call
RESERVED-2 PIC X(84) N/A Reserved for IBM use.
FILLER PIC X(316) N/A Spaces. Reserved for future use.

Initialize the input fields in the communication data area to spaces.
Collect the input data for the API.
Required input data is one or more of the following:
- CMCT-INDEX (secondary search field) plus COR-SYSID (for sysplex)
- SRCH-TERM-ID (secondary search field)
- SRCH-SWITCH-ID, SRCH-PARTY-NO, and SRCH-PARTY-TYPE (complete primary search field).
See Table 19 for descriptions of the input fields of the API.
Move the data to the input fields of the CICS communication data area created for this API.

Field	Attributes	In/Out	Description
COMMAREA	N/A	N/A	01 level name.
COMMAREA-LEN	PIC S9(4) COMP VALUE +1024	In	The length in bytes of the CICS communication data area.
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 (CAMI726C).
RETURN-CODE	PIC 9(04)	Out	Indicates the result of the attempted operation. 0 No errors were detected. The process completed. 1 An error was detected. The specified table entry was not found. 2 The search fields are in conflict. An entry was found that matched one field, but not another. 8 API routing error. See the reason codes under "API Router". 9 See REASON-CODE
SRCH-CMCT-INDEX	PIC X(05)	In	The relative record number of the record in the CMCT. Primary search field. When this field is the only input parameter, output does not include SRCH-PREV-CMCT-INDEX.
SRCH-TERM-ID	PIC X(08)	In	Identification number of agent's terminal, if the agent is signed on and terminal is not disabled. Secondary search field. When this field is input, output includes SRCH-PREV-CMCT-INDEX.
SRCH-SWITCH-ID	PIC X(08)	In	ID of the switch of the agent handling the call. Part of the search field. The complete search field is: SRCH-CMCT-INDEX SRCH-TERM-ID SRCH-SWITCH-ID SRCH-PARTY-TYPE. SRCH-PARTY-NO SRCH-COR-SYSID When the complete search field is input, output includes SRCH-PREV-CMCT-INDEX.
SRCH-PARTY-TYPE	PIC X(01)	In	Agent's telephone number type. Part of the search field. The complete search field is: SRCH-CMCT-INDEX SRCH-TERM-ID SRCH-SWITCH-ID SRCH-PARTY-TYPE. SRCH-PARTY-NO SRCH-COR-SYSID When the complete search field is input, output includes SRCH-PREV-CMCT-INDEX. 0 Unknown. 1 Extension. 3 Pilot. 4 Agent ID. T Trunk.
SRCH-PARTY-NO	PIC X(08)	In	Agent's telephone number. Part of the search field. The complete search field is: SRCH-CMCT-INDEX SRCH-TERM-ID SRCH-SWITCH-ID SRCH-PARTY-TYPE. SRCH-PARTY-NO SRCH-COR-SYSID When the complete search field is input, output includes SRCH-PREV-CMCT-INDEX.
SRCH-PREV-CMCT- INDEX	PIC 9(05)	Out	The CMCT index for a simultaneous call involving the same party. Only output when the input parameters include SRCH-TERM-ID or a combination of SRCH-SWITCH-ID, SRCH-PARTY-NO, and SRCH-PARTY-TYPE.
PARTY-SEQ-NO	PIC 9(02)	Out	Sequence number of party in the call. If CMCT-INDEX is only parameter provided, PARTY-SEQ-NO will be set to blank.
SRCH-NEXT	PIC X(01)	N/A	Reserved
SRCH-BASE	PIC 9(04)	N/A	Reserved
REASON-CODE	PIC X(04)	Out	16 The length of the Commarea was specified incorrectly. 20 A table addressability error. 10xx For IBM problem determination only.
SRCH-COR-SYSID	PIC X(04)	In	The SYSID of the COR in which to call the API. Used with CMCT Index for sysplex environments only.
FILLER	PIC X(58)	N/A	Spaces. Reserved for future use.
CMCT-INDEX	PIC 9(05)	Out	The relative record number of the record in the CMCT.
MSG-DATE	PIC X(8)	Out	Date last message was received from the switch.
MSG-TIME	PIC X(9)	Out	Time last message was received from the switch.
CTM-SEQ	PIC 9(02)	Out	Sequential number assigned to records in the CMCT.
CTM-CNTR	PIC 9(03)	Out	Count of records written that are of same type as last record written.
UOW-APPLID	PIC X(8)	Out	ID of the CallCoordinator region which initiated processing of the work unit.
UOW-NO	PIC X(12)	Out	Sequential number assigned to an individual telephony session (call) and all related calls.
CX-APPLID	PIC X(8)	Out	ID of the CallCoordinator region which initiated processing of the call.
CX-NO	PIC X(12)	Out	Call index number (assigned to call using the event message time and the CTM-SEQ number).
APPL-CONN-ID	PIC S9(09)	Out	One of the call indices. Used for call tracking and record identification. Sequence number generated by CallCoordinator Call Tracking Manager(CTM). Incremented for each new call except for call join or the first party add to an existing call. Not incremented for party adds after the first party add in the same telephony session. Value is the same as the Unit Of Work Index, except when two telephony sessions are combined.
MSG-DATE-SUB	PIC X(8)	Out	Date in last message.
MSG-TIME-SUB	PIC X(9)	Out	Time in last message.
MSG-TYPE	PIC X(3)	Out	Identifies the last message type for the call. Messages from CallPath/CICS begin with C. C00 Call alerting. C01 Call connected. C02 Call held. C03 Call rejected. C04 Call routed. C05 Call transferred. C06 Disconnected. C07 Feature invoked. C08 Request instruction. C09 Response. C10 Setup. C11 Party status. C12 Call conferenced. C13 Call alternated. C14 Call parked. C15 Call picked. C16 Network reached. C17 Switch status. C18 Indicator provided. C19 Data collected C20 Resource deleted C21 Call parties C22 ACD information C23 Hardware status C24 Call action provided C25 Call party removed P00 Pseudo call alerting. P01 Pseudo call connected. P02 Pseudo extend call. P03 Pseudo transfer call. P04 Pseudo conference call. P05 Pseudo retrieve call. P06 Pseudo disconnected. R00 Rejected pseudo call alerting. R01 Rejected pseudo call connected. R02 Rejected pseudo extend call. R03 Rejected pseudo transfer call. R04 Rejected pseudo conference call. R05 Rejected pseudo retrieve call. R06 Rejected pseudo disconnected. S02 Call tracking cleanup (CAMT205C - V205)
SWITCH	PIC X(8)	Out	ID of the switch of the agent handling the call.
CALL-SOURCE	PIC X(01)	Out	Indicates source of the call: I CallCoordinator.
CALL-PARENTAGE	PIC X(01)	Out	Indicates call parentage: O Original call -- involves no previous call on hold. R Related call -- results from a party placing another call on hold in order to transfer, conference, or consult.
CALL-STATE	PIC X(01)	Out	Indicates the state of the call in progress: A Alerting. C Calling. D Disconnected. H Held. P Pending. Q Queuing. R Routing. T Connected. W Queued. X Holding. Blank n/a.
END-CODE	PIC X(01)	Out	Indicates how the call ended. Not applicable in an active call. A Abandoned. C Completed. D Deleted. J Joined. L Link lost. S Shutdown. Blank n/a (Call has not yet ended.).
PARTY-COUNT	PIC 9(02)	Out	Number of parties in the call.
PARTY-MIX-INX	PIC 9(03)	Out	An index that changes when there is a change in the parties participating in a call.
CNTRL-NO	PIC X(30)	Out	Control number or account number of the caller. Entered using the Set Control Number API.
BUS-VLU	PIC 9(12)	Out	Business value assigned to the call. Entered using the Set Control Number API.
ORIGINAL-BUS-VLU	PIC 9(12)	Out	As for BUS-VLU except that this applies to the ORIGINAL call if one exists.
BUS-VLU-SIGN	PIC X(01)	Out	Sign of the business value. + Positive. - Negative. Blank n/a.
ORIG-GROUP	PIC X(10)	Out	Pilot number used to access the original ACD group as opposed to that of an overflow ACD group which might have answered the call.
CALL-PURPOSE	PIC X(01)	Out	Indicates the purpose of the call: P Pending. S Service. X Server change. C Conferee Change. U Unknown.
TRANSID	PIC X(8)	Out	Initial Transaction ID indicated for calls requiring screen processing by CallCoordinator Screen Control Module (Automatic mode).
USER-TRANSID	PIC X(8)	Out	Initial Transaction ID indicated for calls requiring screen processing by a user-written screen control program (User mode).
SRVR-FUNCTION	PIC X(10)	Out	The function of the server agent for the call.
SRVR-ID	PIC X(10)	Out	The ID number of the agent handling the call.
ANI-SOURCE	PIC X(2)	Out	The source of the Automatic Number Identification (ANI) data. 00 From switch. Ax The first digit, "A," indicates that the ANI number was updated using the Set ANI ID API. The second digit is a user-defined code for ANI numbers. See Table 33 for the definition of ANI-ID-CODE. Blank ANI data is not present.
ANI-NUMBER	PIC X(32)	Out	The ANI number (the billing number of the calling party). Left-justified and filled with spaces.
ORIGINAL-APPL-CONN-ID	PIC S9(09)	Out	One of the call indices. As for AAPL-CONN-ID except that this applies to the ORIGINAL call if one exists.
ORIGINAL-CNTRL-NO	PIC X(30)	Out	As for CNTRL-NO except that this applies to the ORIGINAL call if one exists.
ORIGINAL-BUS-VLU-SIGN	PIC X(01)	Out	As for BUS-VLU SIGN except that this applies to the ORIGINAL call if one exists.
ORIGINAL-ORIG-GROUP	PIC X(10)	Out	As for ORIG-GROUP except that this applies to the ORIGINAL call if one exists.
ORIGINAL-ANI-SOURCE	PIC X(2)	Out	As for ANI-SOURCE except that this applies to the ORIGINAL call if one exists.
ORIGINAL-ANI-NUMBER	PIC X(32)	Out	As for ANI-NUMBER except that this applies to the ORIGINAL call if one exists.
DNIS	PIC X(32)	Out	The dialed number identification service (DNIS) number (if any) dialed by the caller and passed by the switch. Used to determine the initial transaction to be started.
ORIGINAL-DNIS	PIC X(32)	Out	As for DNIS except that this applies to the ORIGINAL call if one exists.
DATA-COLLECTED	PIC X(512)	Out	The data collected as input from the telephone keypad.
PARTY-GROUP	PIC X(10)	Out	The pilot number used to access the ACD group that is currently handling the call.
PREV-PRTY-GROUP	PIC X(10)	Out	The pilot number used to access the ACD group that was previously handling the call.
RESERVED-1	PIC X(24)	N/A	Reserved for IBM use.
FILLER	PIC X(47)	N/A	Spaces. Reserved for future use.
PROGRAM-DATA	PIC X(512)	Out	The program data associated with this call
RESERVED-2	PIC X(84)	N/A	Reserved for IBM use.
FILLER	PIC X(316)	N/A	Spaces. Reserved for future use.

Code the following CICS command into your application program:

      EXEC CICS LINK PROGRAM('CAMI726C')
                     COMMAREA(CAMC726-COMMAREA)
                     LENGTH(CAMC726-COMMAREA-LEN)
                     END-EXEC.

Test the value returned in the return code field in the CICS communication data area to determine if operation of the API was successful.
If operation of the API was not successful, take action applicable to the error indicated by the return code.

If operation of the API was successful, the output fields of the communication data area contain the CMCT data for the requested call.

Inquire Party Data API (CAMI727C)

What This API Does

This API enables an application program to get data about a party in a call. The party data is part of the CMCT data for a call. This data includes the following:

If the party is the server for the call (the agent who has responsibility for the call)
Party index (a counter incremented for each party in a call)
Switch ID of the party
The party's telephone number and telephone number type
The connection state of the party
Agent status of the party
Agent's class, function code, and identification number.

To locate the correct entry in the CMCT, this API uses input from the application program. The required input is:

CMCT Index (SRCH-CMCT-INDEX), and the SYSID of the COR (SRCH-COR-SYSID). CMCT Index is the relative record number of the record
The party sequence number (consecutive numbers assigned to each party in a call [for example, 1=caller, 2=called, and so on.]).

For complete descriptions of the input and output fields of this API, see Table 20.

When to Use This API

You can use this API whenever an application program needs CMCT data about the parties in a call.

This API can be used to:

Provide the appropriate display and data for the agent handling a call (intelligent answering).
Create records for the CallCoordinator MIS log.
See "Write MIS Record API (CAMI700C)" for information about writing an application program that writes its own records to the MIS Log.
Verify an agent is a party in a call when the agent is requesting a copy of the screen display for the call. After verification, the program uses the Screen Copy API to provide the screen copy for the requesting agent. See "Screen Copy API (CAMI750C)" for more information.

How to Use This API

To use the Inquire Party Data API in your application programs, do the following:

Create a CICS communication data area in working storage of the program by copying the data area for this API. The fields for this data area are described in Table 20. The layout for this data area is provided in the CallCoordinator SEZPCOPY target library, member name CAMC727. Refer to the library member for the actual field names.

If calling the API from COBOL II or later, INITIALIZE the Communication data area (CAMC727-COMMAREA-DATA) before setting any of the fields.

Table 20. CICS Communication Data Area for the Inquire Party Data API (CAMC727)

Field Attributes In/out Description
COMMAREA N/A N/A 01 level name.
COMMAREA-LEN PIC S9(04) COMP VALUE +2048 In The length in bytes of the CICS communication data area.
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 (CAMI727C).
RETURN-CODE PIC 9(04) Out Indicates the result of the attempted operation.

0
No errors were detected. The process completed.
1
An error was detected. The specified table entry was not found.
2
The party number in search field was greater than the number of parties in the call.
8
API routing error. See the reason codes under "API Router".
9
See REASON-CODE.

SRCH-CMCT-INDEX PIC X(05) In The relative record number of the record in the CMCT. Primary search field. For sysplex users SRCH-COR-SYSID is required.
SRCH-PARTY-NO PIC X(02) In The sequence number of a party in a call (1 = caller, 2 = called party, etc.). Second search field.
SRCH-COR-SYSID PIC X(04) In The SYSID of the COR in which to call the API. Used with CMCT Index for sysplex environments only.
REASON-CODE PIC X(4) Out For Routing see Reason Codes at Start.

16
The length of the Commarea was specified incorrectly.
20
A table addressability error.

FILLER PIC X(107) N/A Spaces. Reserved for future use.
CMCT-INDEX PIC 9(05) Out The relative record number of the record in the CMCT.
PARTY-SEQ-NO PIC 9(02) Out The sequence number of a party in a call (1 = caller, 2 = called party, etc.).
PARTY-ROLE PIC X(01) Out The role of the party.

A
Agent.
B
Trunk backward.
C
Client.
F
Trunk forward.
P
Pilot.
R
Referrer.
U
Unknown.
Blank
N/A.

PARTY-SRVR PIC X(01) Out Indicates whether this party is the server of the call.

Y
This party is the server of the call.
N
This party is not the server of the call.
Blank
N/A.

PARTY-INDEX PIC X(10) Out A counter that is incremented and unique for each party in a call.
PARTY-SWITCH-ID PIC X(08) Out The switch identification number of the party.
PARTY-NO-TYPE PIC X(01) Out Party telephone number type.

0
Unknown.
1
Extension.
3
Pilot.
4
Agent ID.
T
Trunk.
C
Connection.

PARTY-NO PIC X(08) Out Party's telephone number.

?
Unknown (party type is "C").

PARTY-CONN-STATE PIC X(01) Out The current connection state of the party.

A
Alerting.
C
Calling.
D
Disconnected.
H
Held.
P
Pending.
Q
Queuing.
R
Routing.
T
Connected.
W
Queued.
X
Holding.
Blank
N/A.

PARTY-AGENT-STATUS PIC X(01) Out Agent status of the party (if an agent).

Blank
Inactive or Not signed on to CallPath CallCoordinator
Y
Signed on to CallPath CallCoordinator
P
Disabled
I
Initial screen not displayed
Q
Original Queue
T
Pilot
V
Overflow queue

Note: Agent status is stored on the CMCT table. It does not change during a currently active call. Changes take effect for new calls only.
PARTY-AGENT-CLASS PIC X(01) Out User-supplied value to indicate the class of the agent. Used in MIS reporting.
PARTY-AGENT-FN PIC X(10) Out Agent function code of the party (if an agent).
PARTY-AGENT-ID PIC X(10) Out Agent identification number of the party (if an agent).
FILLER PIC X(827) N/A Spaces. Reserved for future use.

Initialize input fields to spaces.
Collect the input data for the API.
Required input data is the SRCH-CMCT-INDEX and/or the SRCH-PARTY-NO. See Table 20 for descriptions of input fields of the API.
Move the data to the input fields of the CICS communication data area created for this API.

Field	Attributes	In/out	Description
COMMAREA	N/A	N/A	01 level name.
COMMAREA-LEN	PIC S9(04) COMP VALUE +2048	In	The length in bytes of the CICS communication data area.
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 (CAMI727C).
RETURN-CODE	PIC 9(04)	Out	Indicates the result of the attempted operation. 0 No errors were detected. The process completed. 1 An error was detected. The specified table entry was not found. 2 The party number in search field was greater than the number of parties in the call. 8 API routing error. See the reason codes under "API Router". 9 See REASON-CODE.
SRCH-CMCT-INDEX	PIC X(05)	In	The relative record number of the record in the CMCT. Primary search field. For sysplex users SRCH-COR-SYSID is required.
SRCH-PARTY-NO	PIC X(02)	In	The sequence number of a party in a call (1 = caller, 2 = called party, etc.). Second search field.
SRCH-COR-SYSID	PIC X(04)	In	The SYSID of the COR in which to call the API. Used with CMCT Index for sysplex environments only.
REASON-CODE	PIC X(4)	Out	For Routing see Reason Codes at Start. 16 The length of the Commarea was specified incorrectly. 20 A table addressability error.
FILLER	PIC X(107)	N/A	Spaces. Reserved for future use.
CMCT-INDEX	PIC 9(05)	Out	The relative record number of the record in the CMCT.
PARTY-SEQ-NO	PIC 9(02)	Out	The sequence number of a party in a call (1 = caller, 2 = called party, etc.).
PARTY-ROLE	PIC X(01)	Out	The role of the party. A Agent. B Trunk backward. C Client. F Trunk forward. P Pilot. R Referrer. U Unknown. Blank N/A.
PARTY-SRVR	PIC X(01)	Out	Indicates whether this party is the server of the call. Y This party is the server of the call. N This party is not the server of the call. Blank N/A.
PARTY-INDEX	PIC X(10)	Out	A counter that is incremented and unique for each party in a call.
PARTY-SWITCH-ID	PIC X(08)	Out	The switch identification number of the party.
PARTY-NO-TYPE	PIC X(01)	Out	Party telephone number type. 0 Unknown. 1 Extension. 3 Pilot. 4 Agent ID. T Trunk. C Connection.
PARTY-NO	PIC X(08)	Out	Party's telephone number. ? Unknown (party type is "C").
PARTY-CONN-STATE	PIC X(01)	Out	The current connection state of the party. A Alerting. C Calling. D Disconnected. H Held. P Pending. Q Queuing. R Routing. T Connected. W Queued. X Holding. Blank N/A.
PARTY-AGENT-STATUS	PIC X(01)	Out	Agent status of the party (if an agent). Blank Inactive or Not signed on to CallPath CallCoordinator Y Signed on to CallPath CallCoordinator P Disabled I Initial screen not displayed Q Original Queue T Pilot V Overflow queue Note: Agent status is stored on the CMCT table. It does not change during a currently active call. Changes take effect for new calls only.
PARTY-AGENT-CLASS	PIC X(01)	Out	User-supplied value to indicate the class of the agent. Used in MIS reporting.
PARTY-AGENT-FN	PIC X(10)	Out	Agent function code of the party (if an agent).
PARTY-AGENT-ID	PIC X(10)	Out	Agent identification number of the party (if an agent).
FILLER	PIC X(827)	N/A	Spaces. Reserved for future use.

Code the following CICS command into your application program:

      EXEC CICS LINK PROGRAM('CAMI727C')
                     COMMAREA(CAMC727-COMMAREA)
                     LENGTH(CAMC727-COMMAREA-LEN)
                     END-EXEC.

Test the value returned in the return code field in the CICS communication data area to determine if operation of the API was successful.
If operation of the API was not successful, take action applicable to the error indicated by the return code.

If operation of the API was successful, the output fields of the communication data area contain the party data from the CMCT.