This chapter includes sections about the CallCoordinator application programming interfaces (APIs) related to the Coordinated Voice and Data feature. These sections are:
This exit enables CallCoordinator to access a program that renames temporary storage queues and performs other screen processing functions. It passes the data needed by this program to perform these processes.
This exit is defined as a product-sensitive programming interface.
This API allows agents to use their terminals to initiate call and screen transfer to another agent.
The CallCoordinator APIs are defined as general-use programming interfaces.
This API allows programs to start a new transaction at the transferred-to-terminal instead of repeating the transaction of the transferred-from-terminal.
This API allows programs to set and read T-Server User Data (aka Attached Data).
User Data may also be accessed by various Genesys Framework components, including
Universal Routing Server.
These APIs are defined as general-use programming interfaces. The exit is a product-sensitive programming interface. See "Programming Interfaces" for definitions of general-use and product-sensitive programming interfaces.
There are various ways of controlling the data that appears at a transferred-to terminal. The information here is to help you select the method most appropriate for your installation.
This example is based on the one shown in Figure 7. In the example a call is transferred from the auto insurance agent to the home insurance agent:
There are various combinations of API calls that can be used to achieve the transfer, as follows:
The Re-initialize API changes the REINIT-TRANS field in the CMCT (Call Management Control Table).
A specific transaction does not need to be specified because the application may not have, or need, the information about what the transaction is or where the transferred call is going. In this case, CallCoordinator performs a normal Intelligent Answering search for a transaction to start at the target. This API is used if screen transfers are to be prevented, that is when we do not want to give the IVR or the agent and/or the caller the opportunity to transfer the call before Re-initialize issued).
+-------------Product-sensitive programming interface information-------------- +
This exit enables CallCoordinator to access a program that renames temporary storage queues and performs other screen processing functions. It passes the data needed by this program to perform these processes.
The renaming function is required when your application programs use temporary storage queues, and the associated data is subject to transfer with call transfers. It may also be necessary for you to perform application specific screen processing functions such as the removal of data subject to security regulations prior to screen transfer. This exit provides the interface to pass the required data for these processes from CallCoordinator screen presentation processing to your screen presentation processing program.
Transfers from one agent's screen to another may be direct or deferred. In both situations exits are provided at both the to-terminal and from-terminal. This exit occurs after reading of the screen image, and saving the Commarea at the from-terminal. The exit occurs before the screen image and Commarea are restored, when the exit is invoked for the to-terminal.
The interface data includes the data needed by the exit program to:
If the naming standards differ from the above standard or special screen processing functions are required, you can use the interface data to customize your application for renaming TSQs and performing application-specific screen processing.
Note: In a sysplex environment, you must manage these TSQs yourself.
To use this exit to do your own screen presentation processing, do the following:
Table 24. CICS Communication
Data Area for the Screen Presentation Manager Exit (CAMC770)
When CallCoordinator invokes the Screen Presentation Manager exit program the first time, it passes the ID of the transferred-from-terminal in the FROM-TERM-ID field of the interface. The TO-TERM-ID field is blank. The module needs to read the TSQ of the transferred-from-terminal and write it to a new TSQ. The NEXT-TRANS-ID and DT-NUMBER fields of the interface are used to identify the new TSQ.
When CallCoordinator invokes the Screen Presentation Manager exit program the second time, it passes the ID of the transferred-to-terminal in the TO-TERM-ID field of the interface. The FROM-TERM-ID field is now blank. The module needs to read the TSQ it created and identified using the NEXT-TRANS-ID and DT-NUMBER fields of the interface. It writes the data into a new TSQ for the transferred-to-terminal.
In an MRO environment, if the TSQs do not reside in main storage or in the CallCoordinator region or are not defined to CICS as remote resources, your Screen Presentation Manager exit program must get the names of the links to the terminal-owning regions (TOR) of the terminals. To do this:
01 WS-TERM-OWN-LINK-NAME PIC X(04).
EXEC CICS INQUIRE
TERMID(FROM-TERM-ID)
REMOTESYSTEM(WS-TERM-OWN-LINK-NAME)
END-EXEC.
EXEC CICS READQ TS
QUEUE(queue-name)
FROM(data-area)
LENGTH(queue-length)
SYSID(WS-TERM-OWN-LINK-NAME)
END-EXEC.
The following shows the information passed to the Screen Presentation Manager exit program for this purpose when the Screen Presentation Manager exit occurs during Transfer (save) or Save steps:
The following shows the information passed to the Screen Presentation Manager exit program for this purpose when the Screen Presentation Manager exit occurs during Transfer (save), Save, Transfer (restore) or Restore steps:
For Transfer(save) or Save the TSQ is read, modified and rewritten.
For Transfer(restore) or Restore the Commarea is used.
When running at the to-terminal, the Screen Presentation Manager exit has access to the Commarea that applies to the transaction currently running.
Table 25 shows the data values passed in the Screen
Presentation interface fields for different screen actions.
| Field Name | Transfer (Save) | Transfer (Restore) | Save | Restore | Cleanup |
|---|---|---|---|---|---|
| FROM-TERM-ID | From Term ID | Spaces | From Term ID | Spaces | Spaces |
| TO-TERM-ID | Spaces | To Term ID | Spaces | To Term ID | Spaces |
| CA-NEXT-TRANS-ID | Applcation Trans ID | Applcation Trans ID | Applcation Trans ID | Applcation Trans ID | Applcation Trans ID |
| CA-DT-NUMBER | Unique number | Unique number | Unique number | Unique number | Unique number |
| CA-APPLC-CONN-ID | Unique number | Unique number | Unique number | Unique number | Unique number |
| CA-ACTION-CODE | 02 | 02 | 03 | 04 | 05 |
| CA-TRANS- COMMAREA-PTR | Address of Commarea | Address of Commarea | Address of Commarea | Address of Commarea | zero |
| CA-TRANS- COMMAREA-LEN | Length of Commarea | Length of Commarea | Length of Commarea | Length of Commarea | zero |
| CA-KEEP- TRANS-FLAG | Space | Space | Space | Space | Space |
Sample program source code for the Screen Presentation Manager Exit is provided as a source library member in the CallCoordinator SEZPSRCE target library, member name CAMI770C.
CallCoordinator insures the accessibility of the data saved in a temporary queue (associated with a transferred-from terminal) at the transferred-to terminal during a screen transfer. It does this by changing the Terminal ID part of the name of the queue from the transferred-from Terminal ID to the transferred-to Terminal ID.
When a call is transferred, CallCoordinator invokes the Screen Presentation Manager Exit program once for the transferred-from terminal and then again for the transferred-to terminal. The first time, CallCoordinator exits to the sample exit program that reads the TSQ of the transferred-from terminal and writes it to a new TSQ. The second time, CallCoordinator exits to the sample program that reads the new TSQ and writes it to a TSQ for the transferred-to terminal. The interface data is passed in the DFHCOMMAREA to the Screen Presentation Manager exit program.
+----------End of Product-sensitive programming interface information---------- +
This API enables agents to perform the following list of telephony actions using their terminals rather than their telephones and this ability is known as hands-free telephony (for details see "Definitions"):
Note: The availability of these functions is dependent upon the telephone switch being used. For more information, see the CallPath Services Reference [Switch Name] for your switch. This IBM series of manuals gives the details for interfacing switches with the CallPath Services family of products.
When an Agent wishes to use one of these functions, the API requires that the appropriate request type and target number be entered. This provides the advance notice CallCoordinator needs for the relevant screen activity. The API sends a series of CallPath/CICS for OS/390 program calls which result in requests being sent to the switch to accomplish the requested function.
If Genesys T-Servers are in use, inter-switch transfers will be handled by the T-Servers. The T-Servers must be configured to work together. Using T-Servers to transfer inter-switch calls renders CallCoordinator's Inter-Switch Tracking numbers unnecessary. Any switch can transfer to any other switch and the call will be tracked by CallCoordinator, as long as the various T-Servers are configured properly.
Using T-Server's Inter Server Call Control to transfer calls allows CallCoordinator to utilize T-Server User Data. This User Data (aka Attached Data) will follow the call throughout the T-Server network. User Data may be set using the Access User Data API (CAMI735C).
The request types for this API are described in Table 26.
The originator of the CallCoordinator telephone call.
This is the agent signed on to CallCoordinator at the terminal identified by EIBTRMID or, if specified, TERM-ID.
This is the agent signed on to CallCoordinator and is identified by TARGET-NBR.
If the target agent is known, this field may be used in place of the TARGET-NBR and/or TARGET-SWITCH fields. TARGET-AGENT must be a signed-on CallCoordinator agent.
This is the switch to which the call is being transferred. It is used only when both the sending and receiving switches are controlled by networked T-Servers. If this field is left blank, then HIT will attempt to determine the target switch using the Switch-to-Switch Dialing Prefix table. Leave this field blank if the call is to be transferred to the same switch. If TARGET-AGENT is specified then HIT will use it to determine the target switch.
The requesting agent hangs up before the requested agent answers the telephone. From the client's perspective it will appear as follows:
Only the client and the requested agent are participants in the call from the time the requesting agent hangs up.
The call enters conference mode before the requested agent answers the telephone. From the client's perspective it will appear as follows:
The requesting agent waits until the requested agent answers the telephone before completing the transfer. The requesting and requested agents may consult with one another at this time whilst the client remains on hold, not participating in the conversation. Once the two agents have finished consulting, the following scenarios can occur:
The requesting agent waits until the requested agent answers the telephone before completing the conference. The requesting and requested agents may consult with one another at this time while the client remains on hold, not participating in the conversation. Once the two agents have finished consulting, the following scenarios can occur:
This field specifies the account code to be associated with the call. The account code can be used to provide more specific billing information than just the party to be billed. For example, in a legal environment, the account code could be associated with one of multiple cases for the same client that is being handled by the law office.
Also on the DMS100 switch, the account code can be used as the authorization code for the call.
Program Data provides the ability for CallPath programs to pass data to the CallPath subsystem on CallPath Program Calls such as Make_Call and to receive that data in the associated CallPath messages such as Call_Alerting. CallCoordinator has implemented Program Data such that the first 16 bytes are reserved for its own use and the remaining 496 bytes (subject to switch limitations) are available to the user.
CallCoordinator associates Program Data with a call whenever the user invokes the Host-Initiated Telephony API with one of the following request codes:
The first 16 bytes of Program Data will contain the following:
The Program Data ID can have one of the following values indicating how the program data was originated:
The Program Data is then associated with the Call Data record of the call that has resulted from the action performed as a result of the Host-Initiated Telephony API request and can be retrieved using the Inquire Call Data API. The CallCoordinator portion of this Program Data (16 bytes) contains the CMCT Index, Applid, the last 3 digits of the Call Index and a Reason Code from the originating call. The user portion can contain any data that the user placed in the USER-PROGRAM-DATA field.
Thus it is possible to retrieve the Program Data for a call using the Inquire Call Data API, interrogate the Reason Code and then use the CMCT Index as a search argument in another Inquire Call Data API request and obtain call-related data such as Control Number, Business Value or User Program data pertaining to the originating telephone call. It is, therefore, possible to transfer data with a telephone call between two different switches if the transport of Program Data across the switch network is supported by the switch (for example Lucent G3).
You might want your application program to use this API so that agents can initiate call transfers, call conferences, call answering, call hang up, by way of the host using an application program. This could be necessary under the following circumstances:
To use the Host-Initiated Telephony API in your application program, do the following:
If calling the API from COBOL II or later, INITIALIZE the Communication data
area (CAMC775-COMMAREA-DATA) before setting any of the fields.
Table 26. CICS Communication
Data Area for Host-Initiated Telephony API (CAMC775)
| Field | Attributes | In/Out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) COMP VALUE +256 | N/A | Length in bytes of this communications data area. |
| COMMAREA-DATA | N/A | N/A | 03 level name. |
| FROM-PROGRAM-NAME | PIC X(08) | In | The name of the program that is linking to this API. |
| TO-PROGRAM-NAME | PIC X(08) | In | The name of this API (CAMI775C). |
| RETURN-CODE | PIC S9(09) COMP | Out | The return code can
have the following values (see also "Return Code Details"):
|
| REQUEST-TYPE | PIC X(02) | In | The following requests
can be made for this API:
|
| TARGET-NBR | PIC X(32) | In | The directory number upon which the API is to operate. |
| TERM-ID | PIC X(08) | In | The Terminal ID that identifies the requesting agent. |
| EXTEND-PURPOSE | PIC X(01) | In | The purpose for which
the EXTEND request is being issued. This field can have the following values:
|
| ACCOUNT-CODE | PIC X(32) | In | The account code to be associated with the telephone call. |
| TRIGGER-NUMBER | PIC X(32) | In | The directory number specified in the Additional Monitored Resources table for Host-based routing. This number is passed to the user in CAMCTRG. |
| TRIGGER-TAG | PIC X(08) | In | The tag passed to the user in TRIGGER-TAG in data area CAMCTRG that identifies the triggered call. |
| TRIGNUM-TYPE | PIC X(01) | In | The number type of TRIGGER-NUMBER (0=unknown,1=extension,3=pilot). |
| TRIGGER-SWITCH-ID | PIC X(08) | In | The name of the switch upon which TRIGGER-NUMBER is defined. |
| COR-SYSID | PIC X(04) | In | The CICS SysID of the COR in which the API is to run. It is required if the API request is called with the CMT-INDEX input parameter, in a sysplex environment. |
| REQUEST-MODE | PIC X(01) | In | The mode in which the
API is to operate.This field can have the following values:
|
| LAST-CP-CALL | PIC X(08) | Out | The name of the last call to be executed.This field is for debugging purposes so that it is apparent which call was last executed for correlation with the CP-RETURN-CODE and CP-RR-SENSE-CODE fields or for a CallCoordinator Table addressability error, the name of the table. |
| CP-RETURN-CODE | PIC S9(09) COMP | Out | Synchronous mode only.This field will contain the Return Code from CallPath/CICS for OS/390 If the value is -111 (set by CallCoordinator) then the field CP-RR-SENSE-CODE should be inspected. See SC34-2402 for details. |
| CP-RR-SENSE-CODE | PIC S9(09) COMP | Out | Synchronous mode only.This field is used only where field CP-RETURN-CODE is -111.This field will contain the sense code returned by CallPath/CICS for OS/390 in a Response message. See SC34-2402 for details. |
| CMCT-INDEX | PIC X(5) | In | The CMCT Index of the call data record on which the API is to operate. It is used for transactions that do not have a terminal associated with them, for example in host-based routing. |
| TARGET-AGENT | PIC X(10) | In | The Agent ID to which the call will be transferred. |
| RQ-PARTY-SWITCH | PIC X(8) | In | Revertive Make Call
only. This is the Switch upon which RQ-PARTY-NUMBER exists. |
| RQ-PARTY-NUMBER | PIC X(10) | In | Revertive Make Call
only. The number on whose behalf the Revertive Make Call is being issued (the
calling party). Refer to the CallPath Services Reference manual for
your switch to find out if this function is supported and any limitations that
apply, for example this number may have to be a pilot number. |
| RMC-ALERT-TIME | PIC S9(9) COMP | In | Revertive Make Call
only. The number of seconds that the target of the Revertive Make Call should be
in Alerting state before the call is abandoned. Refer to the CallPath
Services Reference manual for your switch to find out if STLSCDA is
supported and, if so, what values can be specified. The default is 60 seconds. |
| RMC-DETECT-ACTION | PIC S9(9) COMP | in | Revertive Make Call
only. The action to be taken if it is detected that the call has been answered
by an answering machine or other automated answering equipment. Refer to the CallPath
Services Reference manual for your switch to find out if STLSDDA is
supported and, if so, what values can be specified. The default is to remain
connected. This field can have the following values:
|
| REASON-CODE | PIC S9(4) COMP | Out | For routing errors see
"API Router".
|
| FILLER | PIC X(38) | N/A | Reserved for future use. |
| SEND-CC-PD-FLAG | PIC X(1) | In | This flag enables the
user to choose whether or not CallCordinator/CICS uses the first 16 bytes of the
program data associated with the call. For Coordinated Voice and Data Transfer
across switches to work using the Program Data method, the first 16 bytes must
be used by CallCordinator/CICS. Therefore, the default is 'Y'. Values
are:
|
| USER-PROGRAM-DATA | PIC X(496) | In | User Program Data to be associated with this request. |
| TARGET-SWITCH | PIC X(8) | In | The switch ID to which the call was transferred. |
| FILLER | PIC X(263) | N/A | Reserved for future use. |
| FILLER | PIC X(08) VALUE 'ENDIHIT0' | N/A | Eye-catcher for the end of the area. |
Example for COBOL:
EXEC CICS LINK PROGRAM('CAMI775C')
COMMAREA(CAMC775-COMMAREA)
LENGTH(CAMC775-COMMAREA-LEN)
END-EXEC.
If the operation of the API was successful, the switch will have been requested to perform the appropriate telephony functions.
A CAMCTRG data area description is provided for reference. It is passed, as started data, to a transaction started as a result of a call coming to a Triggered telephony resource (that is a resource in the Additional Monitored Resources which has an associated transaction). The data passed is used by the application in conjunction with Host-Initiated Telephony API REQUEST-TYPE's Redirect-Call, Return-Control, and Reject-Call.
Note: The started routing transaction must issue a CICS Retrieve to obtain the passed data described in CAMCTRG.
The fields for this data area are described in Table 27. A layout for this data area is provided in the CallCoordinator SEZPCOPY target library, member name CAMCTRG. Refer to the library member for the actual field names.
Table 27. Data Area for
Triggered Transaction (CAMCTRG)
| Field | Attributes | In/Out | Description |
|---|---|---|---|
| TRIGGER-DATA | N/A | N/A | 01 level name. |
| TRIGGER-DATA-LENGTH | PIC S9(04) COMP VALUE +300 | N/A | Length in bytes of this data area. |
| TRIGGER-SWITCH-ID | PIC X(09) | Out | The name of the target switch of the Trigger. |
| TRIGGER-NUMBER | PIC X(32) | Out | The number of the Triggered resource. |
| FILLER | PIC X(02) | N/A | Spaces. Reserved fro future use. |
| TRIGGER-NUMBER-LEN | PIC S9(08) COMP | Out | The length of the Triggered number. |
| TRIGNUM-TYPE | PIC X(01) | Out | The type of resource
Triggered.
|
| TRIGGER-TAG | PIC X(08) | Out | A unique Tag assigned to the Trigger request. |
| FILLER | PIC X(03) | N/A | Spaces. Reserved for future use. |
| TRIGGER-TIMER-VALUE. | PIC S9(08) COMP | Out | Time to switch default action on Triggered resource |
| TRIGGER-DATE | PIC X(08) | Out | The date (YYYY/MM/DD) of the Trigger. |
| TRIGGER-TIME | PIC X(10) | Out | The time (HH/MM/SSxSSS) of the Trigger. |
| FILLER | PIC X(02) | Out | Spaces. Reserved for future use. |
| TRIGGER-DNIS-ID | PIC X(34) | Out | The DNIS (Table#/DNIS) number associated with the triggered call. |
| TRIGGER-ANI-ID | PIC X(32) | Out | The ANI (Table#/ANI) number associated with the triggered call. |
| CALLING-PARTY-NUM | PIC X(32) | Out | The number of the calling party associated with the triggered call. |
| TRIGGER-CMCT-INDEX | PIC X(05) | Out | CMCT Index of the triggered call. |
| TRIGGER-APPL-CONN-ID | PIC X(09) | Out | ACI of the triggered call. |
| TRIGGER-COR-SYSID | PIC X(04) | Out | The CICS SysID of the COR in which the trigger is active. |
| FILLER | PIC X(98) | N/A | Spaces. Reserved for future use. |
This operation is sometimes called conference without consultation.
The API uses two CallPath Program Calls:
Mandatory Input:
Optional Input:
This operation is sometimes called transfer without consultation.
The API uses two CallPath Program Calls:
Mandatory Input:
Optional Input:
This operation is sometimes called consulting.
The API uses the CallPath Program Call Extend_Call and the CallPath Set Program Call Set_Extend_Purpose with a purpose of STL_EXTEND_TRANSFER or STL_EXTEND_CONFERENCE (dependent upon user input as below). if Extend Purpose Required is set to Y in the CallCoordinator Switch Definition Panel. The Extend_Call puts the call between the client and the requesting agent (identified by TERM-ID) ON HOLD and makes a new call between the requesting agent and the agent identified by TARGET-NBR.
Mandatory Input:
Optional Input:
This operation is sometimes called conference with consultation.
This request connects the party ON HOLD (the client), the requesting agent (identified by TERM-ID), and the new agent (identified by TARGET-NBR) in a conference call. A preceding EXTEND request MUST have been issued or the API will return INVALID REQUEST.
Mandatory Input:
Optional Input:
This operation is sometimes called transfer with consultation.
This request connects the party ON HOLD (the client) with the new agent (identified by TARGET-NBR) and disconnects the requesting agent. A preceding EXTEND request MUST have been issued or the API will return INVALID REQUEST.
Mandatory Input:
Request type
Optional Input:
This request reconnects the client with the requesting agent (identified by TERM-ID). A preceding EXTEND or HOLD request MUST have been issued or the API will return INVALID REQUEST.
Mandatory Input:
Optional Input:
This API request connects the requesting agent to the client. The requesting agent's telephone must be ALERTING (ringing) or the API will return INVALID REQUEST.
Mandatory Input:
Optional Input:
This API request disconnects the call currently active on the requesting agent's telephone. If there is no active call the API will return INVALID REQUEST.
Mandatory Input:
Request type
Optional Input:
This API request puts the active call between the client and the requesting agent (identified by TERM-ID) ON HOLD. The call can be reconnected by issuing a RETRIEVE API request.
Mandatory Input:
Request type
Optional Input:
This API request will make a telephone call between the requesting agent (identified by TERM-ID) and a third party (identified by TARGET-NBR).
Mandatory Input:
Request type
Target number
Optional Input:
Note: Some switches may require the use of Position_ID rather than Directory_Number for a Make_Call. Please check the appropriate CallPath switch Reference manual and set the MAKE CALL RESOURCE TYPE parameter in the CallCoordinator Switch Detail record accordingly.
This API request will redirect a telephone call that is queued at a pilot number defined in the Additional Monitored Resources table with a Trigger transaction. The call will be redirected to the number specified in TARGET-NBR.
Mandatory Input:
Optional Input:
This API request will return control to the switch identified in TRIGGER-SWITCH-ID for a telephone call that is queued to a pilot number defined in the Additional Monitored Resources table with a Trigger transaction. The switch will then take its default action for routing calls from the triggered number.
Mandatory Input:
Optional Input:
This API call immediately transfers a call from the Requesting Agent's telephone to the telephone identified by TARGET-NBR.
Mandatory Input:
Optional Input:
This API request will reject a telephone call queued at the pilot number defined in the Additional Monitored Resources table with a Trigger transaction.
Mandatory Input:
Optional Input:
1 - If Terminal ID is not explicitly specified then the API will use the value contained the CICS EIB (EIBTRMID).
CAMI775C did not detect any errors with the user input to the API. This should be followed by successful telephony actions which produce the expected result. However it is possible that despite the user input being correct, the telephony subsystem is unable to honor the request. In such instances an error message will be written by CallCoordinator where possible.
Asynchronous mode: Since there may be many parallel invocations of this API, the issuing of the telephony subsystem requests is handled by program CAMH180C under the control of transaction V180. Each Host-Initiated Telephony API request that results in Return Code 0000, starts V180 which then issues requests to the telephony subsystem. As the user program is in no way connected to V180 and may, in fact, have completed processing, it is not possible to indicate error situations that V180 may encounter to the user program. Any errors encountered by V180 are, therefore, written by CallCoordinator as error messages to the CallCoordinator message log, or to the agent's screen, or to both.
Synchronous mode: In this mode, Return Code 0000 means that the required telephony actions have been performed by the subsystem in most cases. However, the behavior of switches varies and it cannot be fully guaranteed that this is the case. For example, some switches will give a positive response to a make call request if the target number does not exist on the switch and then send a Call_Rejected message to indicate that an error has occurred. This will result in a Return Code 0000 from the API although the operation did not actually occur.
CallCoordinator is not active.
The CallCoordinator Agent identified by CAMC775-TERM-ID (if specified) or EIBTRMID is not signed-on to CallCoordinator. This return code may also occur if the telephone switch does not support the requested API function. Check that the agent identified by the relevant terminal-id definition has been signed on to CallCoordinator.
The value specified in CAMC775-REQUEST-TYPE is not one of the supported values as defined in field CAMC775-VALID-REQUEST in the CAMC775 data area.
The value specified in CAMC775-EXTEND-PURPOSE is not one of the supported values as defined in field CAMC775-VALID-PURPOSE in the CAMC775 data area.
A synchronous request mode invocation resulted in a non-zero CallPath/CICS for OS/390 return code being returned or a non-zero sense code was returned in the Return_response message.
Field LAST-CP-CALL will contain the identifier of the last CP/CICS/MVS Program or Set Program call and can have the following values:
The field CP-RETURN-CODE contains the CallPath/CICS for OS/390 return code for the call identified in the above list. Refer to the CallPath/CICS for OS/390 Application Programming Guide for more details of these values.
If the field CP-RETURN-CODE contains the value -111, then CallCoordinator has set this field indicating that a sense code has been returned by CallPath/CICS for OS/390 in a Response message. This sense code is contained in field CP-RR-SENSE-CODE and the CallPath/CICS for OS/390 Application Programming Guide should be inspected for the meaning of this particular sense code.
The ALLOCATE SESSION CICS command issued for MRO invocation of the API failed with a condition of SYSIDERR. Check that the CallCoordinator CICS region is available.
An error occurred initializing the CallCoordinator Connect Table for MRO invocation of the API. Check that a Connect Table has been defined and contains the correct information regarding the region that contains CallCoordinator.
An error is encountered that does not fall into another category:
These errors will usually be accompanied by a CallCoordinator message written to the message log which will provide more data for problem diagnosis.
The Commarea length obtained from the CICS EIB field EIBCALEN is not the same as the value contained in CAMC775-COMMAREA-LEN. Check that the LENGTH operand of the EXEC CICS LINK PROGRAM('CAMI775C') command is correctly specified or that the CAMC775-COMMAREA-LEN field has not been overwritten.
The Party Data record was not found (the requesting agent was not a participant in an active call).
The connection ID could not be found in the Connections table.
There was no previous connection pointer in the Party Data table.
Return Code 0020 is returned by the API if CAMI775C encounters an error in trying to locate any CallCoordinator tables. The field LAST-CP-CALL will contain the name of the table that was being addressed when the error occurred. The list below gives the table name and it's description:
If this error occurs, CallCoordinator has had a catastrophic error and should be restarted.
This API enables an application program to START a new transaction for the transferred-to-terminal instead of repeating the transaction of the transferred-from-terminal. This must be an automatic mode transaction (one that uses CallCoordinator screen control) rather than a user mode transaction (one that uses a user-written screen control program).
This API also enables an application to discover what transaction would have been displayed for the transferred-to-terminal.
When an application program invokes this API, it specifies the Transaction ID for the transferred-to-terminal, or this can be set to blank.
If a Transaction ID is specified, the API does the following:
If the Transaction ID is set to blank, the IA transaction search sequence takes place for the target agent at the transferred-to-terminal to find the transaction ID that would be used for that terminal.
See Table 28 for description of input fields for this API.
This API is useful when CallCoordinator agents need to transfer calls to agents of different functional groups. The transfer can either be direct or deferred. In a direct transfer, the agent indicates the extension number of the transferred-to-agent and the call and screen content is transferred directly. In a deferred transfer, the agent indicates the pilot number of an ACD group. While the call is being routed through the pilot number and is in queue, CallCoordinator saves the screen content. When the call is assigned to an agent, CallCoordinator restores the screen content.
The API allows the transferring agent to specify a new Transaction ID. Then, instead of moving the current transaction environment, CallCoordinator can start the transaction that is appropriate for the receiving agent.
Agents responsible for screening/directing calls can use this API when transferring calls to other agent groups. This would be the case of an IVR that determines which service a caller requires and then routes the call.
To use the Re-initialize API in your application program, do the following:
Table 28. CICS Communication
Data Area for Re-initialize API (CAMC788)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) + 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 (CAMI788C). |
| RETURN-CODE | PIC 9(4) | Out | The value of the return
code indicates if the request was processed. If not, the reason is specified.
|
| TERM-ID | PIC X(8) | In | CICS terminal identification number of the CallCoordinator agent in the call. |
| CMCT-INDEX | PIC X(05) | N/A | The CMCT index of the call data record whose initial transaction is to be set by the by the REINIT-TRANS. Used with COR-SYSID. |
| COR-SYSID | PIC X(04) | In | The CICS SysID of the COR where the API is to run. Required if CMCT-INDEX is used, in a sysplex environment. |
| REASON-CODE | PIC X(4) | Out | For routing errors see
"API Router".
|
| FILLER | PIC X(41) | N/A | Spaces. Reserved for future use. |
| REINIT-FLAG | PIC X(01) | In | Defines the request for
re-initialization.
|
| REINIT-TRANS | PIC X(08) | In | CICS transaction to be started for the transferred-to-terminal. If blank, use the Transaction ID defined in CallCoordinator for the transferred-to-agent. |
| FILLER | PIC X(935) | N/A | Spaces. Reserved for future use. |
EXEC CICS LINK PROGRAM('CAMI788C')
COMMAREA(CAMC788-COMMAREA)
LENGTH(CAMC788-COMMAREA-LEN)
END-EXEC.
If operation of the API was successful, the requested Transaction ID was stored in the CMCT active call record and flagged for re-initialization.
This API enables an application program to set or read T-Server User Data aka Attached Data. User Data is available throughout the duration of the call and will follow the call to other switches, as long as the sending and receiving switches are T-Server controlled.
User Data uses Key/Value pairs to define the context of the data. Up to 10 Key/Value pairs may be used. Each key has a maximum length of 10. Each value has a maximum length of 90. The data may be read or updated at any time during the call.
The associated call is identified by providing one of the following items to the API:
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.
See Table 28 for description of input fields for this API.
Use this API when data needs to be associated with a call and either the switch does not allow Program Data or the Program Data size is too small. Also this API is useful for communication between Genesys Framework and CICS. For example, a customer information from a data base residing on the mainframe may be added to User Data and used by Universal Routing Server to determine where to route the call.
To use the Access User Data API in your application program, do the following:
Table 28. CICS Communication
Data Area for Access User Data API (CAMC735)
| Field | Attributes | In/Out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(4) 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 (CAMI735C). |
| RETURN-CODE | PIC 9(04) | Out | Indicates the result of
the attempted operation.
|
| ACTION | PIC X(01) | In | The following actions may be performed:
|
| 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-PARTY-TYPE | PIC X(01) | In | Agent's telephone
number type. Part of the search field. The complete search field is:
|
| SRCH-PARTY-NO | PIC X(08) | In | Agent's telephone
number. Part of the search field. The complete search field is:
|
| 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 |
|
| 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(13) | N/A | Spaces. Reserved for future use. |
| CMCT-INDEX | PIC 9(05) | Out | The relative record number of the record in the CMCT. |
| COR-SYSID | PICX(04) | Out | The CICS SysID of the COR where the call exists. |
| User-Data | PIC X(1200) | In/Out | The actual User data attached to the call. Input, if update. Output, if Inquire. Broken down as defined in the next 3 fields |
| Number of Entries | PIC 9(2) | In/Out | The number of Key Value pairs which make up the User Data |
| Key/Value Pairs | PIC X(1000) | In/Out | The total length represents 10 Key Value pairs. Each pair has a 10-byte key and 90-byte value |
| Filler | PIC X(198) | N/A | Reserved for future use. |
| Program-ID | PIC X(8) | Out | CallPath Application ID. |
| Profile-ID | PIC X(8) | Out | Profile for current switch. |
| Sense-Code | PIC X(4) | Out | Sense code returned from switch if request failed. |
| CP-Call | PIC X(8) | Out | Last CallPath API called. |
| CP-Retcd | PIC X(4) | Out | Return Code from CalPath call. |
| Sense-Qual-length | PIC X(4) | Out | Length of Sense-Code Qualifier. |
| Sense-Code-Qualifier | PIC X(200) | Out | Sense Code Qualifier returned from switch if request failed. |
| FILLER | PIC X(523) | N/A | Spaces. Reserved for future use. |
EXEC CICS LINK PROGRAM('CAMI735C')
COMMAREA(CAMC735-COMMAREA)
LENGTH(CAMC735-COMMAREA-LEN)
END-EXEC.
If operation of the API was successful, User Data will have been set or retrieved for the active call.
