This chapter includes sections about the CallCoordinator APIs related to agent operations. These sections are:
These APIs allow programs to sign agents on and off of CallCoordinator and to update entries in the Agents Table.
This API allows programs to get agent data from the Agents Table.
This API allows programs to enable or disable automatic screen display by CallCoordinator for an agent's terminal.
This API allows an application program to change the state of a telephone, instead of an agent manually changing the state. A front-end application may also be developed to allow the agent to set the state via the terminal instead of using the telephone.
This API allows programs to restore the screen environment for a call to an agent whose terminal was previously disabled for CallCoordinator screen activity.
This API allows agents to receive a copy of another agent's screen.
Each section explains the function of the API and describes when it would be useful. It also explains how to use the APIs and defines the CICS communication data area required for each one.
The CallCoordinator APIs are defined as general-use programming interfaces. See "Programming Interfaces" for a definition of general-use programming interfaces.
This API allows an application program to sign an agent on to CallCoordinator, enabling coordinated voice and data. This ensures that when calls come in or are transferred, the associated panel is displayed along with the call.
The invoking program, using the terminal status field of this API, can request the following actions:
In addition to the above actions, certain input fields in the Commarea can be updated. See Table 11 for a complete list of input data for this API.
CallCoordinator provides a Sign On/Off panel which agents can use to sign on and off of CallCoordinator. It is invoked by Transaction ID (V810). Refer to the Operations section of the CallPath CallCoordinator/CICS System Management Guide for information about this function.
You can use this API, in combination with the Sign Off API, to replace the CallCoordinator-supplied sign on/off panel.
You can use this API, in combination with the Sign Off API, to replace the CallCoordinator-supplied sign on/off function. There are two ways to do this:
The requirements for each action this API performs are as follows:
This API validates all input before applying any updates. If an input field fails an edit, the value returned in the RETURN-CODE field is a 9, the value returned in the REASON-CODE field identifies the input field that is not valid and the ERROR-MSG field contains the number of the message that explains the error (refer to the CallPath CallCoordinator/CICS Problem Determination for the message text).
To use the Sign On API in your application program, do the following:
If calling the API from COBOL II or later, INITIALIZE
the Communication data area
(CAMC710-COMMAREA-DATA)
before setting any of the fields.
Table 11. CICS Communication Data Area for the Sign On API (CAMC710)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) COMP VALUE +1024 | N/A | 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 (CAMI710C). |
| RETURN-CODE | PIC 9(04) | Out | Indicates the result of the attempted operation.
In some situations, it is necessary to examine the reason code as well
as the return code to determine the specific cause of the problem.
|
| SRCH-SWITCH-ID | PIC X(08) | N/A | This field is not used. |
| FILLER | PIC X(02) | N/A | Spaces. Reserved for future use. |
| SRCH-EXT-ID | PIC X(10) | N/A | This field is not used. |
| SRCH-TERM-ID | PIC X(08) | N/A | This field is not used. |
| SRCH-AGENT-ID | PIC X(10) | N/A | This field is not used. |
| CTM-STATUS-FLAG | PIC X(10) | Out | Status of the Call Tracking module.
|
| MIS-STATUS-FLAG | PIC X(01) | Out | Status of the MIS module.
|
| COM-STATUS-FLAG | PIC X(01) | Out | This field is set to the same value as CTM-STATUS-FLAG. |
| SAVE-CHANGES-FLAG | PIC X(01) | N/A | This field is no longer used. |
| REASON-CODE | PIC 9(04) | Out | Indicates the result of the attempted operation.
For more information, refer to the System Log.
|
| REASON-CODE (continued) | PIC 9(04) | Out | Indicates the result of the attempted operation.
For more information, refer to the System Log.
|
| ERROR-MSG | PIC X(8) | output | Message ID identifying edit error encountered with input field.
|
| FILLER | PIC X(26) | N/A | Spaces. Reserved for future use. |
| CALLPATH-COMMAREA | PIC X(40) | N/A | This space is reserved. |
| SWITCH-ID | PIC X(8) | In | Switch identification. The switch must be defined in the Switches table. Cannot be set to low values. An entry in this field is optional. |
| FILLER | PIC X(2) | N/A | Spaces. Reserved for future use. |
| EXT-ID | PIC X(10) | In | Extension identification. A 1 to 10- character field that contains the characters A through Z, 0 through 9, & and *. Cannot be set to low values. An entry in this field is optional. |
| TERM-ID | PIC X(8) | In | CallCoordinator agent's CICS terminal identification number. An entry in this field is required only for a sign-on request. Cannot be set to low values. |
| AGENT-ID | PIC X(10) | In | This field is required. |
| AGENT-FUNC | PIC X(10) | In | The CallCoordinator agent's function code. To change this field to spaces, move low values into this field. |
| TERM-STATUS-FLAG | PIC X(01) | In | The status of the CallCoordinator agent's terminal.
This field indicates the type of action to be performed.
In addition, it indicates the mode the agent will be in when
signed on.
This is referred to as Agent Mode on the panel.
|
| INIT-TRANS-ID | PIC X(08) | In | Indicates the CICS transaction invoked to display the first panel the agent uses to handle a call. To change this field to spaces, move low values into this field. |
| XFER-NTFN-IND | PIC X(01) | In | Indicates whether to notify the CallCoordinator agent when the
application panel is successfully transferred to another
agent or removed by a save operation.
Also indicates whether the panel is to be cleared
when the transfer is completed.
To change this field to spaces, move low values into this field. |
| RECOV-NTFN-IND | PIC X(01 | In | Indicates whether to send a message to the CallCoordinator agent's
terminal when the switch has been restarted.
To change this field in the Agents VSAM file and Agents Table to spaces, move low values into this field. |
| USER-MODE-TRANS-ID | PIC X(08) | In | Transaction ID of a user-written panel control
program to be used for the CallCoordinator agent.
To change this field to spaces,
move low values into this field.
Y (yes) in this field indicates use of the Transaction ID in the User transaction field of the COR Telephony Settings panel. This can also be accomplished by leaving this field blank and setting the USER-MODE-FLAG field to Y. |
| LINK-DOWN-FLAG | PIC X(01) | N/A | This field is not used. |
| LINK-UP-FLAG | PIC X(01) | N/A | This field is not used. |
| RESTART-FLAG | PIC X(10) | N/A | This field is not used. |
| START-WITH-DATA- FLAG | PIC X(01) | In | Indicates whether
CallCoordinator passes the Initiate With Data Interface data block to
the initial transaction at start time.
See "Initiate With Data Interface (CAMC500)".
Valid values are:
|
| FILLER | PIC X(03) | N/A | Spaces. Reserved for future use. |
| POSITION-ID | PIC X(08) | N/A |
The position ID that is defined on the switch
(if applicable to your switch)
that is the alternate address or identifier for the extension ID.
Used for call tracking.
This field cannot be updated with this API.
|
| AGENT-CLASS | PIC X(01) | In | A 1-character user defined sort field.
To change this field to spaces, move low values into this field. |
| AGENT-GROUP | PIC X(08) | In | A 1-to 8-character alphanumeric
customer defined field to categorize agents.
To change this field in the Agents VSAM file and Agents Table to spaces, move low values into this field. |
| SIGNON-MODE | PIC X(01) | In | Indicates the signon mode of the agent.
Referred to as the Agent Mode on panels.
This field cannot be set to low values. The updated value of this field is usually determined from the TERM-STATUS-FLAG field. For example, the value you pass in the SIGNON-MODE field is ignored if the value you pass in the TERM-STATUS-FLAG field is a Y, P, I, or blank. If the value you pass in the TERM-STATUS-FLAG field is a Y, P, I, or blank, the value of the SIGNON-MODE field is set to Y, P, and I respectively. However, if the value you pass in the TERM-STATUS-FLAG field is a U, then the value you pass in the SIGNON-MODE field is used as specified.
|
| AGENT-SIGNON- STATUS | PIC X(01) | N/A | Indicates the signon status of the agent.
Referred to on panels as Signed On.
This field cannot be updated.
|
| USER-MODE-FLAG | PIC X(01) | In | Indicates whether panel handling will be performed in User or Auto
mode.
To change this field to spaces, move low values into this field. |
| AGENT-LANGUAGE | PIC X(03) | In | The NLS language code for this agent.
The code used to determine the language to be
used when displaying panels and messages.
If not entered, the agent language code in the COR General Settings
panel will be used
(refer to
CallPath CallCoordinator/CICS System Management Guide
).
To change this field to spaces, move low values into this field. |
| PANEL-DISPLAY- FLAG | PIC X(01) | In | Indicates whether the panel ID of the panel is to be displayed.
To change this field to spaces, move low values into this field. |
| ALARM-SOUND-FLAG | PIC X(01) | In | Indicates whether the terminal alarm should be sounded when messages
are displayed to the screen.
To change this field to spaces, move low values into this field. |
| RECORD-STATUS | PIC X(01) | N/A | Indicates the status of this entry in the Agents VSAM file.
This field cannot be updated with this API.
|
| CALL-V795-FLAG | PIC X(01) | IN | Indicates whether V795 transaction is to be called during sign-on.
|
| TOR-SYSID | PIC X(4) | N/A | The CICS SYSID of the TOR where the agent is signed on. |
| COR-SYSID | PIC X(4) | N/A | The CICS SYSID of the COR where the agent is signed on. |
| USER-AREA | PIC X(100) | IN | User area. |
| FILLER | PIC X(673) | N/A | Spaces. Reserved for future use. |
EXEC CICS LINK PROGRAM('CAMI710C')
COMMAREA(CAMC710-COMMAREA)
LENGTH(CAMC710-COMMAREA-LEN)
END-EXEC.
If operation of the API is successful, the signon request is completed and the Agents Table is updated.
You can use the Inquire Agents API to validate an agent's signon request. For more information, see "Inquire Agents API (CAMI720C)".
This API instructs CallCoordinator to sign off an agent. This removes the agent's entry from the Agents Table and ends automatic terminal display for incoming calls. The sign-off request must specify the terminal ID (SRCH-TERM-ID) of the agent. See Table 12 for a list of input data for this API.
CallCoordinator provides a Sign On/Off panel that agents can use to sign on to and off of CallCoordinator. It is invoked by Transaction ID (V810). Refer to CallPath CallCoordinator/CICS System Management Guide for more information about this panel.
You can use this API, in combination with the Sign On API, to replace the CallCoordinator-supplied sign on/off function. There are two ways to do this:
In either case, your application program uses this API to send the agent sign off request to CallCoordinator.
To use the Sign Off API in your application program, do the following:
If calling the API from COBOL II or later, INITIALIZE the Communication data area (CAMC715-COMMAREA-DATA) before setting any of the fields.
Table 12. CICS Communication Data Area for the SignOff API (CAMC715)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) COMP VALUE +1024 | N/A | 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 (CAMI715C). |
| RETURN-CODE | PIC 9(4) | Out | Indicates the result of the attempted operation.
In some cases, RETURN-CODE and REASON-CODE together indicate
the cause of a problem.
|
| FILLER | PIC X(18) | N/A | Spaces. Reserved for future use. |
| SRCH-TERM-ID | PIC X(8) | In | The CICS ID of the CallCoordinator agent's terminal to be signed off. |
| REASON-CODE | PIC 9(4) | Out | This code is used in conjunction with the return code. It further
defines the results of the operation.
|
| FILLER | PIC X(48) | N/A | Spaces. Reserved for future use. |
| CALLPATH-COMMAREA | PIC X(40) | N/A | This field is reserved. |
| FILLER | PIC X(884) | N/A | Spaces. Reserved for future use. |
EXEC CICS LINK PROGRAM('CAMI715C')
COMMAREA(CAMC715-COMMAREA)
LENGTH(CAMC715-COMMAREA-LEN)
END-EXEC.
If operation of the API was successful, the specified agent is signed off of CallCoordinator.
This API retrieves an agent's entry from the CallCoordinator Agents Table or the Agents VSAM file. The Agents VSAM file contains all agents defined to CallCoordinator. Only signed on agents are in the Agents Table. Both contain the same information for a signed on agent except for the terminal ID and agent sign-on status (they are set to blank in the Agents VSAM file). Your application program finds the entry using one or more of the following search fields:
See Table 13 for a complete list of input data for this API.
Your application program can use this API to get data such as the following:
The output data provided by this API is described in Table 13.
The Agents Table has data for all signed on agents that CallCoordinator needs to coordinate terminal displays with incoming calls. Your program can update this data by first using this API to retrieve an entry, and then using the Sign On API to update it. Much of this data is provided during CallCoordinator installation. Refer to CallPath CallCoordinator/CICS System Management Guide for more information.
An entry is placed in the Agents Table when an agent signs on. This enables CallCoordinator to determine which agents currently can receive calls.
In systems where agents use different extensions each day or where CICS assigns terminals a new terminal ID at sign on (auto install), the Agents Table is updated for the time the agent is signed on. This API can retrieve the latest information indicating which terminal is assigned to which extension and agent.
Another use of this API is to enable your screen control program to do either of the following:
See Chapter 5, "Screen Control" for more information about writing user screen control programs.
To use the Inquire Agents API in your application program, do the following:
If calling the API from COBOL II or later, INITIALIZE
the Communication data area
(CAMC720-COMMAREA-DATA)
before setting any of the fields.
Table 13. CICS Communication Data Area for the Inquire Agents API (CAMC720)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) COMP VALUE +1024 | N/A | 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 (CAMI720C). |
| RETURN-CODE | PIC 9(04) | Out | Indicates the result of the attempted operation.
In some situations, it is necessary to examine the reason code as well
as the return code to determine the specific cause of the problem.
|
| SRCH-SWITCH-ID | PIC X(08) | In | Switch identification number. Switch and Extension ID combination is the first search field. |
| FILLER | PIC X(02) | N/A | Accounts for change in Switch ID field size in previous product. |
| SRCH-EXT-ID | PIC X(10) | In | Extension identification number. Required when the switch ID is specified. |
| SRCH-TERM-ID | PIC (08) | In | Agent's terminal identification number. |
| SRCH-AGENT-ID | PIC X(10) | In | Agent's identification number. |
| REASON-CODE | PIC 9(04) | Out | Further defines the return codes that contain
more than one error condition.
|
| REQUEST-TYPE | PIC X(01) | In | Indicates the type of inquiry as follows:
|
| SRCH-SYSID | PIC X(4) | IN | The CICS SysID of the COR in which you wish to invoke the API. |
| FILLER | PIC X(33) | N/A | Spaces. Reserved for future use. |
| FILLER | PIC X(18) | N/A | This space is reserved for CallCoordinator processing. Do not change it. |
| TABLE-TOKEN-9 | PIC S9(08) COMP | N/A | CallCoordinator processing uses this field to keep track of the position in the table. It is for CallCoordinator use only. |
| TABLE-TOKEN-AGSW | PIC X(08) | N/A | CallCoordinator processing uses this field to keep track of the position in the table. It is for CallCoordinator use only. |
| TABLE-TOKEN-AGENT | PIC X(10) | N/A | CallCoordinator processing uses this field to keep track of the position in the table. It is for CallCoordinator use only. |
| SWITCH-ID | PIC X(08) | Out | Switch identification number. In the previous product, this field was named CBX-ID. It was PIC X(10). |
| FILLER | PIC X(02) | N/A | Accounts for the change in the Switch ID field size from the previous product. |
| EXT-ID | PIC X(10) | Out | Extension identification number |
| TERM-ID | PIC X(08) | Out | The agent's terminal identification number |
| AGENT-ID | PIC X(10) | Out | The CallCoordinator agent's identification number |
| AGENT-FUNC | PIC X(10) | Out | The CallCoordinator agent's function code |
| TERM-STATUS-FLAG | PIC X(01) | Out | The status of the CallCoordinator agent's terminal.
This value is based on the value of SIGNON-MODE
(referred to as the Agent Mode on panels),
and the AGENT-SIGNON-STATUS.
If SIGNON-STATUS is I, then this
field is set to the value of SIGNON-MODE.
If SIGNON-STATUS
is not equal to I, this field is set to blank.
|
| INIT-TRANS-ID | PIC (08) | Out | The CICS transaction invoked to display the first screen. |
| XFER-NTFN-IND | PIC X(01) | Out | Whether to notify the CallCoordinator agent when the
application screen has been successfully transferred to another
agent or removed by a save.
Also indicates whether the screen is cleared
when the transfer has been completed.
|
| RECOV-NTFN-IND | PIC X(01) | Out | Whether to send a message to the CallCoordinator agent's
terminal when the switch has been restarted.
|
| USER-MODE-TRANS-ID | PIC X(08) | Out | The application transaction specified to handle
screen processing when the CallCoordinator agent is in user mode.
This value is based on the value of USER-MODE-FLAG and USER- TRANS-ID in the Agents Table. For example:
|
| LINK-DOWN-FLAG | PIC X(01) | Out | Valid values are:
|
| LINK-UP-FLAG | PIC X(01) | Out | Valid values are:
|
| SWITCH-RESTART- FLAG | PIC X(01) | Out | Valid values are:
In the previous product, this field was called CBX-RESTART-FLAG. |
| SPM-START-DATA- FLAG | PIC X(01) | Out | Indicates whether the system passes data (including the
caller number, target number, control number, and other data)
when the CallCoordinator Screen Control Module starts the initial transaction.
Valid values are:
|
| FILLER | PIC X(03) | N/A | Spaces. Reserved for future use. |
| POSITION-ID | PIC X(08) | Out |
The Position ID that is defined on the switch
(if applicable to your switch)
that is the alternate address or identifier for the extension ID.
|
| AGENT-CLASS | PIC X(01) | Out | User-defined class of the specified CallCoordinator agent. Used to sort records. |
| AGENT-GROUP | PIC X(08) | Out | A customer defined field used to group agents. |
| SIGNON-MODE | PIC X(01) | Out | Indicates the sign-on mode of the agent
(referred to as Agent Mode on the panels).
|
| AGENT-SIGNON- STATUS | PIC X(01) | Out | Indicates the signon status of the agent.
|
| USER-MODE-FLAG | PIC X(01) | Out | Indicates whether screen handling will be performed in User or Auto
mode.
|
| AGENT-LANGUAGE | PIC X(03) | Out | The NLS language code for this agent.
The code used to determine the language to be
used when displaying panels and messages.
If not entered, the agent language code in the COR General Settings
panel will be used,
(refer to
CallPath CallCoordinator/CICS System Management Guide
).
|
| PANEL-DISPLAY- FLAG | PIC X(01) | Out | Indicates whether the panel ID is to be displayed.
|
| ALARM-SOUND-FLAG | PIC X(01) | Out | Indicates whether the terminal alarm should be sounded when messages
are displayed to the screen.
|
| RECORD-STATUS | PIC X(01) | Out | The status of this entry.
|
| USER-AREA | PIC X(100) | Out | User area |
| TOR-SYSID | PIC X(4) | Out | The CICS SYSID of the TOR where the agent is signed on. |
| COR-SYSID | PIC X(4) | Out | The CICS SYSID of the COR where the agent is signed on. |
| AGENT-STATUS | PIC X(2) | Out |
This is the current status of the agent.
Possible values are:
'AL' Agent Logged In 'AF' Agent Logged Off 'RY' Agent Ready 'NR' Agent Not Ready 'RE' Agent Ready Explicit 'RI' Agent Ready Implicit 'BY' Agent Busy 'BC' Agent Busy with Call 'BF' Agent Busy with Follow UpFor more information on ACD status, see the section on "Feature Invoked" in CallPath/CICS for OS/390 Application Programming Guide, SC34-5393. |
| ACD-GROUP | PIC X(6) | ||
| Out | The ACD Group into which the agent is logged on. | ||
| FILLER | PIC X(666) | ||
| N/A | Spaces. Reserved for future use. |
EXEC CICS LINK PROGRAM('CAMI720C')
COMMAREA(CAMC720-COMMAREA)
LENGTH(CAMC720-COMMAREA-LEN)
END-EXEC.
If operation of the API is successful, the output fields in the CICS communication data area contain the data from the requested entry.
This API allows an application program to update the Agent Mode field of an entry in the Agents Table and Agents VSAM file. This turns CallCoordinator automatic panel activity on or off for the requesting agent for all subsequent calls. For example, when Agent Mode in the Agents Table is Y (all panels displayed) this API can change it to P (no panels displayed).
If the agent is participating in an active call and is controlling the screen, the agent can disable the screen activity for the current call by setting the REQUEST-TYPE to C (current call only), or B (both current call and subsequent calls). See Table 14 for description of the input data for this API.
CallCoordinator provides an Agent Utility menu that agents can use to enable and disable terminals for CallCoordinator automatic display. It is invoked by Transaction ID (V870). Refer to CallPath CallCoordinator/CICS System Management Guide for more information about this menu. Application programs can use this API to replace the CallCoordinator-supplied function for terminal enabling/disabling.
A CallCoordinator agent can also re-enable CallCoordinator automatic panel activity for a single call rather than for all subsequent calls. This requires using the Agent Utility menu or the Casual User Restore API. See "Casual User Restore API (CAMI760C)".
To use the Set Agent Mode API in your application program, do the following:
If calling the API from COBOL II or later, INITIALIZE the Communication data area (CAMC745-COMMAREA-DATA) before setting any of the fields.
Table 14. CICS Communication Data Area for the Set Agent Mode API (CAMC745)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) COMP VALUE +1024 | N/A | 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 (CAMI745C). |
| RETURN-CODE | PIC 9(04) | Out | Indicates the result of the attempted operation.
In some cases, RETURN-CODE and REASON-CODE together indicate
the cause of a problem.
|
| RETURN-CODE
(continued) | PIC 9(04) | Out |
|
| AGENT-MODE | PIC X(01) | In | Indicates the desired signon mode of the CallCoordinator agent and the
agent's terminal.
Used with the REQUEST-TYPE field.
|
| REQUEST-TYPE | PIC X(01) | In | Indicates desired change in Agent Mode for signon.
|
| WORK-TERM-ID | PIC X(8) | N/A | The agent's CICS terminal ID. |
| REASON-CODE | PIC 9(04) | Out | Code returned from the API that further defines the return code.
For more information, see the System Log.
|
| FILLER | PIC X(104) | N/A | Spaces. Reserved for future use. |
| FILLER | PIC X(884) | N/A | Spaces. Reserved for future use. |
EXEC CICS LINK PROGRAM('CAMI745C')
COMMAREA(CAMC745-COMMAREA)
LENGTH(CAMC745-COMMAREA-LEN)
END-EXEC.
If operation of the API was successful, the agent's terminal is set to the requested mode.
This API enables agents to change the state of their telephone from their terminals rather than from their telephones, using the features described here (see "Set Telephony Feature API Features"). This ability is known as hands-free telephony. The API also allows the Logon and Logoff of logical agents to ACD Groups or Skills which could be interrogated by logic within the switch to change its course of action. The data provided is validated and is sent to CallPath/CICS for OS/390, which verifies the syntax. If insufficient data is supplied or CallPath/CICS for OS/390, CallCoordinator or the requested switch is not active, a non-zero Return_Code will result. The API will wait up to 10 seconds for a response to the request from CallPath/CICS for OS/390. A negative response will result in a non-zero Return_Code, as will no response at all.
The request types for this API and fields required for each request are described in Table 15.
If calling the API from COBOL II or later, INITIALIZE
the Communication data area
(CAMC740-COMMAREA-DATA)
before setting any of the fields.
Table 15. CICS Communication Data Area for Set Telephony Feature API (CAMC740)
| Field | Attributes | In/Out | Required* | Description |
|---|---|---|---|---|
| COMMAREA | N/A | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) COMP VALUE +1024 | N/A | A | Length in bytes of this communications data area. |
| COMMAREA-DATA | N/A | N/A | N/A | 03 level name. |
| FROM-PROGRAM-NAME | PIC X(08) | In | A | The name of the program that is linking to this API. |
| TO-PROGRAM-NAME | PIC X(08) | In | A | The name of this API (CAMI740C). |
| RETURN-CODE | PIC S9(09) COMP | Out | N/A | The return code can have the following values:
|
| RETURN-CODE (continued) | PIC S9(09) COMP | Out | N/A | The return code can have the following values:
|
| SWITCH-ID | PIC X(08) | In | A | The switch upon which the API is to operate. |
| AGENT-ID | PIC X(20) | In | 1 | The Agent for whom the feature is invoked. |
| DIR-NUMBER | PIC X(32) | In | A | The directory number of the phone involved. |
| GROUP-ID | PIC X(32) | In | O | Not currently supported by any switch. |
| POOL-ID | PIC X(20) | In | 1 | The ACD Group or Skill. |
| CP-PROGRAM-ID | PIC X(08) | Out | N/A | The program identifier for CallPath/CICS for OS/390 - unique to this execution of API |
| CALL-PROFILE | PIC X(08) | Out | N/A | The Profile defined to CallPath/CICS for OS/390 by this API for this switch |
| FEATURE-CODE | PIC X(04) | In | A | The following Feature codes are available:
|
| AGENT-ACTIVITY | PIC X(04) | In | 1 | The following Activity codes are available:
|
| MODE | PIC X(04) | In | 2,3 | Values are:
|
| TYPE | PIC X(04) | In | 3 | Values are:
|
| FWD-DIRECTORY- NUMBER | PIC X(32) | In | 3 | The target number of the Forwarding feature. |
| ACCOUNT-CODE | PIC X(32) | In | 4 | Account code for current call. |
| PASSWORD | PIC X(20) | In | O | Used with Advanced Agent Activity |
| SENSE-CODE | PIC X(04) | Out | N/A | Returned from sub-system if Negative Response. |
| CP-CALL | PIC X(08) | Out | N/A | Last CallPath/CICS for OS/390 call issued. If RC=CPCICS error, the error was a result of this call. |
| AGENT-STATUS | PIC X(1). | In | O | Values are:
|
| Filler | PIC X(99). | N/A | N/A | Future expansion. |
| CP-RETURN-CODE | PIC X(04) | Out | N/A | The Return-Code issued from CallPath/CICS for OS/390 |
| REASON-CODE | PIC X(04) | Out | N/A | The reason code if Return-code = 9 (other)
|
| SENSE-QUAL-LENGTH | PIC X(04) | Out | N/A | Length of Sense-Qualifier, if Negative Response. |
| SENSE-QUALIFIER | PIC X(200) | Out | N/A | Sense-qualifier if Negative Response. |
| Filler | PIC X(450). | N/A | N/A | Reserved for future use. |
*Required codes for various Features:
Example for COBOL:
EXEC CICS LINK PROGRAM('CAMI740C')
COMMAREA(CAMC740-COMMAREA)
LENGTH(CAMC740-COMMAREA-LEN)
END-EXEC.
Mandatory Input:
Mandatory Input:
Note: Some switches do not support Advanced Agent Activity, although they do support Agent Activity (see "Agent Activity (0002)"). On switches that support both, either may be used, but Advanced also allows use of Password. This feature allows for the following activities:
Mandatory Input:
Mandatory Input:
Mandatory Input:
Mandatory Input:
Mandatory Input:
Mandatory Input:
Mandatory Input:
Optional Input:
Values for the following fields are contained in COBOL 01 levels following the Commarea definition. These may be moved to the corresponding fields in the Commarea. It is recommended that these fields be used in place of literals in case the values change in the future.
Agents who use non-CallCoordinator panel displays can disable automatic panel display by CallCoordinator. This prevents interruption by CallCoordinator when there is an incoming CallCoordinator call. See "Set Agent Mode API (CAMI745C)" for more information about terminal enabling/disabling for CallCoordinator panel activity.
The Casual User Restore API is for agents working with CallCoordinator automatic panel display disabled. It allows the agent to complete any non-CallCoordinator work and then display the proper panel for a single incoming CallCoordinator call. This API gets the operating environment and the application panel intended for that call. It restores the terminal environment so the agent can handle this one call. The restored environment includes the Execute Interface Block (EIB), screen buffer, communication data area, and any temporary storage queues (TSQs).
In this case, the agent would handle an incoming CallCoordinator call as follows:
This restores CallCoordinator panel processing to the agent terminal for this one call only. If the agent wants to restore CallCoordinator automatic panel display for all subsequent calls, the agent must re-enable the terminal. See "Set Agent Mode API (CAMI745C)" for more information about terminal enabling/disabling for CallCoordinator panel activity.
This API functions correctly whether the casual user is signed on in Automatic mode or User mode. In order for Casual User Restore to work correctly, invoking agents terminals must be permanently disabled (P), and must be participating in a call.
During a conference call, the Casual User Restore must be invoked immediately after the first agent invokes a conference with intent to transfer the call and then dial the next agent's telephone number. The agent will then get the initial screen. If Casual User Restore is invoked after the conference button is pressed, the agent will not be able to restore anything, and will get a return code 03.
The Casual User Restore API can only be effective if CallCoordinator has received event messages from the switch that indicate that a transfer is in progress, or has been completed. The earliest possible indication is in a Call-Routed or Call-Alerting message that contains an "intent-to-transfer" indication (call-extension-indicator set to STL-CALL-EXTENSION-TO-TRANSFER), sent when the agent's telephone is alerted. The latest indication is receipt of the Call-Transferred message. Early transfer can only occur if the "intent-to-transfer" indication is provided by the switch, and the switch generates a Call-Alerting or Call_Routed event message for the casual user agent at the time