Application Programming Guide

Return to Library Contents Previous Topic Bottom of Topic Next Topic Index Help

Chapter 5. Screen Control

     

This chapter includes sections about the CallCoordinator application programming interfaces (APIs) related to customizing screen control. These sections are:

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

There are other CallCoordinator APIs that can be used in conjunction with a user screen control program. They are described in the following sections of this book:

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

User Screen Control Program

   

What the Screen Control Interface Does

         

The CallCoordinator Screen Control Interface passes data from CallCoordinator processes to the screen control program. It can transfer data from a transferred-from screen transaction to a transferred-to screen transaction. The data passed in the interface includes:

See Table 21 for a complete list of field descriptions. You can code a user screen control program to make use of this data.

What the User Screen Control Program Does

     

Screen processing for agents in automatic mode (not in user mode) is controlled by the CallCoordinator default logic for screen control. For initial calls, CallCoordinator STARTs the transaction designated in the Init trans ID field of the COR Telephony Settings or Agent Detail panels, or the Initial Trans ID field of the DNIS to Application, Pilot to Application, or Trunk to Application panels. For transferred calls, it copies screens from one agent to another.

As an alternative to this logic, you can create a user screen control program for agents who need to work in user mode.         (User mode is the state in which a user-written CICS application program controls screen presentation for an agent.)

When a user screen control program is invoked by the CallCoordinator screen control program, it overrides the screens that CallCoordinator would display. It runs as a background task to determine which screens to display to agents in user mode. It uses the data from the CallCoordinator Screen Control Interface to control screen processing.

When to Use a User Screen Control Program

If calls are to be transferred between agents using the same business applications, CallCoordinator automatically uses the Screen Control Interface and its own screen control program.

If calls are to be transferred between agents using different business applications, CallCoordinator still uses the Screen Control Interface and its screen control program. It also needs a customized user screen control program that you write to pass data from one application to another.

For instance, you might want to pass key data from an auto insurance agent's screen to a home insurance agent's screen. This saves time by eliminating redundant requests for information from the caller. This is illustrated in Figure 7.

Figure 7. CallCoordinator Can Display a Different Transaction on the Transferred-to Terminal.


Getting a different application panel

The user screen control program is needed to write the data from the transferred-from screen transaction to a TSQ that will be read by the transferred-to screen transaction. To assist this transfer of data, CallCoordinator generates a unique queue name for every call transfer to an agent specified to be in user mode You can use this queue name to create the TSQ to carry the data from the transferred-from transaction to the transferred-to transaction. See field name QUEUE-NAME in Table 21. Also see "Using the CallCoordinator-Supplied TSQ Name to Pass Data between Screens" and Figure 8.

Other reasons to write a customized user screen control program include the following:

A user screen control program supplements rather than replaces the CallCoordinator screen control program. It provides an alternative method of determining which screen to display to a particular agent for a particular call.

Your system might require multiple screen control programs for its various agent groups and functions. Some agent groups might operate in user mode while others operate under CallCoordinator screen control. Your system can even have multiple user screen control programs, each customized and assigned to a particular agent function. Then, as required for call events associated with an agent (such as an agent receiving a call), CallCoordinator STARTs the user screen control transaction specified for the agent.

How to Create This Program

To customize screen control, you must write your own CICS user screen control program. The code you write determines which application transaction STARTs for an agent, what screen to display, or what other screen activity should take place for a call.

When CallCoordinator agents sign on, they can select the user screen control program by entering its Transaction ID in the User trans ID field and Y in the User control field of the Agent Sign On/Off panel.

Alternatively, the system administrator can define a default for all agents by entering the Transaction ID in the User trans ID field of the COR Telephony Settings panel. The system administrator can define user screen control programs for specific agents by entering the Transaction ID in the User trans ID field and Y in the User control field of the Agent Detail panel. When the CallCoordinator agent signs on, the agent only needs to enter Y in the User control field of the CallCoordinator Agent Sign On/Off panel.

Refer to the Installation section of CallPath CallCoordinator/CICS System Management Guide for information about configuration settings for user mode.

To create your own user screen control program, do the following:

  1. Create a CICS communication data area in working storage by copying the layout for the CallCoordinator Screen Control Interface.       The fields for this data area are described in Table 21. This layout is provided in the CallCoordinator SEZPCOPY target library, member name CAMSUSER. Refer to the library member for the actual field names.


    Table 21. CICS Communication Data Area for the Screen Control Interface (CAMSUSER)
      
    Field Attributes Description
    USER-MODE-QUEUE N/A 01 level name.
    QUEUE-LEN PIC S9(04) COMP VALUE +388 The length of this CICS communication data area in bytes.
    FROM-PROGRAM-NAME PIC X(08) The name of the program invoking this API.
    TO-PROGRAM-NAME PIC X(08) Name of the screen control program.
    FILLER PIC X(120) Spaces. Reserved for future use.
    QUEUE-NAME PIC X(08) The screen transfer queue name. CallCoordinator generates this name to identify a TSQ you can use for this screen control activity. The transferred-from transaction can use this name to create a TSQ to be read by the transferred-to transaction. You can use it to pass data gathered during the initial transaction that is applicable to the transferred-to transaction. See "Using the CallCoordinator-Supplied TSQ Name to Pass Data between Screens".      
    Format CXXXXXnn where:

    • C is the queue name header

    • XXXXX are the last five digits of the Application Connect Id (ACI)

    • nn starts at 0 and is incremented each time the user screen control program is STARTed for that call. It resets to 0 when the call is transferred to an agent who is in automatic mode.
    TIME PIC S9(07) COMP-3 Time of day the screen control program was STARTed.
    DELAY PIC 9(03) COMP-3 Maximum time that screen transfer can be delayed before it is abandoned. Defined in the Screen delay field of the COR Telephony Settings panel. Refer to the Installation section of CallPath CallCoordinator/CICS System Management Guide.
    TO-TERM PIC X(08) Terminal ID of the target terminal. Use this value in the START command that you code in the user screen control program to invoke the transaction selected by that program. Example: 
          EXEC CICS START
                TRANSID(name)
                TERMID(CAMSUSER-TO-TERM)
                END-EXEC.
    FROM-TERM PIC X(08) Terminal ID of the transferred-from terminal (if any).
    TRANS PIC X(08) The Transaction ID of the transferred-from application program. The first time, this contains the Transaction ID of the CallCoordinator screen control program. You can use the Get Next CICS Transaction API to get the return Transaction ID. See "Get Next CICS Transaction ID API (CAMS515C)"
    ACI PIC 9(09) Application connect ID assigned to this call by CallCoordinator. One of the call indices. See "Write MIS Record API (CAMI700C)".
    CUST-CNTL-NBR PIC X(30) Customer control number (if any). Can be alphanumeric and in any format. Added from your business application programs. See "Set Control Number API (CAMI730C)".
    DNIS PIC X(32) The last 12 characters of the dialed number identification service (DNIS) number. Used for determining the initial transaction to be STARTed on a call received on a DNIS number. Contains data if the DNIS feature is installed and a DNIS number was dialed.
    CALLER PIC X(10) Originating caller's telephone number.
    CMCT-INDX PIC 9(04) CallCoordinator Call Management Control Table(CMCT) index number. Index number of the record that contains the CallCoordinator Call Management Control Table entry.
    QUEUE-FLAG PIC X Reserved for future use.
    ACTION-CODE

    Note: ACTION-CODE is continued on the next page.

    		PIC X(02) The reason the user screen control transaction was STARTed and the processing required when that was the reason.

    01
    The user screen control transaction was STARTed as the result of a new call.

    START the transaction you select for the agent at the transferred-to terminal (TO-TERM field). Then if the screen cannot be displayed because the target agent is not signed on to CallCoordinator, or is signed on but has a disabled or non-functional terminal, do as instructed in 03 below.

    02
    The user screen control transaction was STARTed as a result of a request to transfer a call. There are two possibilities:

    • Transfer the screen from the transferred-from terminal (FROM-TERM field) to the transferred-to terminal (TO-TERM field).

      See "Transferring an Entire Screen From Terminal to Terminal".

    • Or START a transaction you select for the agent at the transferred-to terminal (TO-TERM field). You can optionally select data from the transferred-from screen transaction and apply it to the transferred-to screen transaction. * This is usually the faster method.

      See "Using the CallCoordinator-Supplied TSQ Name to Pass Data between Screens".

      * Then if the screen cannot be displayed because the target agent is not signed on to CallCoordinator, or is signed on but has a disabled or non-functional terminal, do as instructed in 03 below.

    03
    The user screen control transaction was STARTed as a result of a request to save the terminal environment because the target agent was unable to receive the screen. (The agent is not signed on or the agent's terminal is disabled or not functional.) The call is to be directed to a call queue or another agent.

    Save the terminal environment on temporary or transient data storage. See "Save Transaction" for more information.

    You can store this data in the TSQ whose name is passed by CallCoordinator in the interface field QUEUE-NAME. See Table 21. You can do so even if you are already using this queue to pass data between applications. (The queue stores both.) For more information, see "Using the CallCoordinator-Supplied TSQ Name to Pass Data between Screens".

    ACTION-CODE (continued) PIC X(02) Continued from previous page.

    04
    The user screen control transaction was STARTed as a result of a request from the agent to receive a screen that would have been displayed earlier if the agent had been signed on, or if the agent's terminal had been enabled or otherwise functional.

    Restore the previously saved terminal environment for this call from temporary or transient data storage. See 03 above. Display the screen at the transferred-to terminal (TO-TERM field). If no screen was saved, START the transaction you select for the agent at the transferred-to terminal (TO-TERM field). Then if the screen cannot be displayed because the target agent is not signed on to CallCoordinator, or is signed on but has a disabled or non-functional terminal, do as instructed in 03 above.

    To code the restore operation, include the instructions for putting the saved environment on another terminal. See "Restore Transaction".

    05
    The user screen control transaction was STARTed as the result of a call being terminated or transferred from an agent in user mode to an agent who is not in user mode.

    Delete the saved terminal environment (if any) or the saved environment of an unsuccessful attempt to restore a previous environment for this call See 03 above. For more information, see "Using the CallCoordinator-Supplied TSQ Name to Pass Data between Screens".

    ANI-TABLE PIC X(02) The source of the Automatic Number Identification (ANI) number.

    00
    From the 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 number is not present.
    ANI-NUMBER PIC X(32) The last 10 characters of the ANI number. Contains data if ANI data is supported and present. The telephone number of the calling party (billable number). Up to 10 digits AAAOOONNNN where:
    • AAA = area code
    • OOO = office code
    • NNNN = number.
    If there are fewer than 10 digits, the number is left-justified and filled with spaces. In other words, the field might contain only the area code (format AAA       ) or just the area code and office code (format AAAOOO    ).
    REINIT-FLAG PIC X

    Y
    The Reinit Flag was set on by the Re-initialize API.

    Spaces
    The Reinit Flag was set off by the Re-initialize API.

    REINIT-INITIAL- TRANS PIC X(08) Initial Transaction ID set by the Re-initialize API.
    DNIS-EXT PIC X(32) DNIS number. The number dialed that the switch passed. Used to determine the initial Transaction ID.
    ANI-EXT PIC X(32) The complete ANI number. The telephone number of the calling party (billable number), left-justified and filled with spaces. Contains data if ANI data is supported and present.
    TASK-SEQUENCE- CONTROL-BLOCK PIC X(54) Task sequencing control block.
    CALLER-TYPE PIC X(1) Caller type.
    0
    Unknown.
    1
    Extension.
    3
    Pilot.
    4
    Agent ID.
    T
    Trunk.
    TO-COR-SYSID PIC X(4) CICS SYSID of the COR in which the TO-TERM is active.
    TO-TOR-SYSID PIC X(4) CICS SYSID of the TOR in which the TO-TERM is signed-on.
    FROM-COR-SYSID PIC X(4) CICS SYSID of the COR in which the FROM-TERM is active.
    FROM-TOR-SYSID PIC X(4) CICS SYSID of the TOR in which the FROM-TERM is signed-on.
    FILLER PIC X(10) Spaces. Reserved for future use.
    (Ref #1.)

  2. Get the data into the data area using the following CICS command: 
            EXEC CICS RETRIEVE INTO(CAMSUSER-USER-MODE-QUEUE)
                         LENGTH(CAMSUSER-QUEUE-LEN)
                         RESP(RESP-CODE)
                         END-EXEC.

  3. Take appropriate action for the call activity indicated by the ACTION-CODE field. For more information, see the ACTION-CODE field descriptions in Table 21.

  4. Add code to determine which CICS transaction the user screen control program STARTs for the agent at the initial or transferred-to terminal.

    The processing implications of your own applications determine the actual specifications of your user screen control program. The following situations can help you consider the requirements of your program:

  5. Add code to START the selected transaction at the transferred-to terminal. The following code is an example.

    In working storage: 

           01 LINK-TO-TERM-OWN-REGION PIC X(04).           /* MRO only */
       01 RESP-CODE PIC S9(08) COMP.

    In the procedure division: 

           EXEC CICS INQUIRE                               /* MRO only */
                 TERMID(CAMSUSER-TO-TERM)              /* MRO only */
                 REMOTESYSTEM(LINK-TO-TERM-OWN-REGION) /* MRO only */
                 RESP(RESP-CODE)                       /* MRO only */
       END-EXEC.                                       /* MRO only */
       IF RESP-CODE NOT EQUAL ZEROES                   /* MRO only */
          PERFORM ERROR-GET-REGION.                    /* MRO only */
 
       EXEC CICS START TRANID (selected Transaction ID)
                 TERMID(CAMSUSER-T0-TERM)
                 SYSID(LINK-TO-TERM-OWN-REGION)        /* MRO only */
                 RESP(RESP-CODE)
       END-EXEC.
       IF RESP-CODE NOT EQUAL ZEROES
          PERFORM ERROR-START-TRAN.

  6. Modify the source to include your requirements. Compile it and test the results.

Transferring an Entire Screen From Terminal to Terminal

     

To do this, include instructions in your user screen control program to save the terminal environment of the transferred-from terminal and display it on the other terminal.      

These two transactions are part of screen control and must both run in the CallCoordinator region.

In a SYSPLEX environmnet, the following information is supplied: 

     CAMSUSER-TO-COR-SYSID
     CAMSUSER-TO-TOR-SYSID
     CAMSUSER-FROM-COR-SYSID
     CAMSUSER-FROM-TOR-SYSID
For a description of the above fields, see the final rows of table Table 21 on page reference #1. This information, together with the start code, should enable the user to perform User-Mode Coordinated Voice and Data Transfer.

Save Transaction:        

In the save transaction (abcd), include instructions to do the following:

  1. Code a CICS RECEIVE BUFFER ASIS command to capture the screen image and screen image length and put them into a save area.

  2. Move EIBCPOSN from the Execute Interface Block (EIB) to a save area to capture the cursor position.

    You can create a temporary storage queue (TSQ) using the CallCoordinator supplied queue name and use it as the save area. (The Screen Control Interface field name is QUEUE-NAME.)

  3. Define an area for the DFHCOMMAREA in the linkage section of your program.

    Notes:

    1. If you don't know the size of the COMMAREA, define the area as 32K bytes (the maximum communication data area size). You do not waste space by defining such a large area, because this is linkage and no storage is reserved.

    2. Transaction abcd has access to the communication data area created by the last task that ran there. This is because the communication data area specified on a RETURN command passes to the next command level program that runs at the terminal.

  4. Move EIBCALEN to a save area to capture the length of the DFHCOMMAREA.

  5. Move DFHCOMMAREA to a save area that is defined as large as EIBCALEN.

  6. Get the next CICS Transaction ID from the Terminal Control Table Terminal Entry (TCTTE) using the Get Next CICS Transaction ID API. See "Get Next CICS Transaction ID API (CAMS515C)".

  7. Terminate the task. Do this in either of the following ways:

Restore Transaction:        

In the restore transaction (wxyz), include these instructions:

  1. Get the saved screen information from the save area created for transaction abcd.

  2. Code a CICS SEND TEXT MAPPED command using the saved screen image and screen image length.

  3. Code a CICS SEND CONTROL CURSOR command to place the cursor back where it was on the original screen.

  4. Code a CICS RETURN command at the end of the task using the values from the saved data for the Transaction ID, COMMAREA, and LENGTH parameters.

Using the CallCoordinator-Supplied TSQ Name to Pass Data between Screens

         

CallCoordinator generates and passes a TSQ name to the transaction of the user screen control program. See field name QUEUE-NAME in Table 21. You can apply this name to a TSQ used to pass data from a transferred-from screen transaction to a transferred-to screen transaction. See Figure 8.

You can use this TSQ to:

Figure 8. Using the CallCoordinator-Supplied TSQ Name to Pass Data Between Screens

Data transfer using TSQ name

 

To use the TSQ name to pass data between screens, include instructions to do the following:

  1. Code the user screen control program to pass the TSQ name (CAMSUSER-QUEUE-NAME) to an application program when it STARTs the transaction of the program. For example, in working storage: 
         01 PASS-TSQ-NAME PIC X(08).
     01 LINK-TO-TERM-OWN-REGION PIC X(04).           /* MRO only */
     01 RESP-CODE PIC S9(08) COMP.

    In the procedure division: 

         EXEC CICS INQUIRE                        /* MRO  only */
     TERMINAL(CAMSUSER-TO-TERM)           /* MRO  only */
               REMOTESYSTEM(LINK-TO-TERM-OWN-REGION)/* MRO  only */
               RESP(RESP-CODE)                      /* MRO  only */
               END-EXEC.                            /* MRO  only */
     IF RESP-CODE NOT EQUAL ZEROES                  /* MRO  only */
       PERFORM ERROR-INQUIRE-REGION.                /* MRO  only */
 
     MOVE CAMSUSER-QUEUE-NAME TO PASS-TSQ-NAME.
     EXEC CICS START TRANID (selected Transaction ID)
               SYSID(LINK-TO-TERM-OWN-REGION)       /* MRO  only */
               FROM(PASS-QUEUE-NAME)
     TERMINAL(CAMSUSER-T0-TERM)
               RESP(RESP-CODE)
     END-EXEC.
     IF RESP-CODE NOT EQUAL ZEROES
       PERFORM ERROR-START-TRAN.

  2. Modify all application programs that can have transactions STARTed by a user screen control program as follows:

    1. Code a CICS RETRIEVE command to get the queue name passed by the user screen control program. For example, in working storage: 
           01 PASSED-TSQ-NAME PIC X(08).
        05 NAME         PIC X(06).
        05 COUNTER      PIC 9(02).
     01 QUEUE-LENGTH  S9(04) COMP VALUE +08.
     01 RESP-CODE PIC S9(08) COMP.

      Note: The queue name has two parts. The first 6 bytes are unique to the call. The last 2 bytes are a counter. CallCoordinator increments this counter by 1 each time it invokes the user screen control program for the same call.

      In the procedure division: 

           EXEC CICS RETRIEVE
               INTO(PASSED-QUEUE-NAME)
               LENGTH(QUEUE-LENGTH)
               RESP(RESP-CODE)
     END-EXEC.
     IF RESP-CODE NOT EQUAL ZEROES
       PERFORM ERROR-RETRIEVE.

    2. Write to a TSQ (using the passed TSQ name) any pertinent data that can be used in transferred-to transactions.

      For example, in working storage: 

            01 RESP-CODE PIC S9(08) COMP.

      In the procedure division: 

           EXEC CICS WRITEQ TS
               QUEUE(PASSED-TSQ-NAME)
               FROM(data-area)
               RESP(RESP-CODE)
     END-EXEC.
     IF RESP-CODE NOT EQUAL ZEROES
       PERFORM ERROR-WRITE-QUEUE.

      Note: If the value of the counter portion of the queue name is greater than zero, such a queue might have already been created for a previous transaction for this call. You can copy this queue and add data to it if needed. See the example in the following item.

    3. Read the TSQ created by the application program transaction running at the transferred-from terminal and apply the data to the program transaction STARTed at the transferred-to terminal.

      Subtract one from the counter portion (last 2 bytes) of the passed queue name. Then transfer the data.

      For example, in working storage: 

           01 PASSED-TSQ-NAME PIC X(08).
        05 NAME         PIC X(06).
        05 COUNTER      PIC 9(02).
     01 RESP-CODE PIC S9(08) COMP.

      In the procedure division: 

           SUBTRACT 1 FROM COUNTER.
 
     EXEC CICS READQ TS
               QUEUE(PASSED-TSQ-NAME)
               INTO(data-area)
               RESP(RESP-CODE)
     END-EXEC.
     IF RESP-CODE NOT EQUAL ZEROES
       PERFORM ERROR-READ-QUEUE.

    4. Delete the TSQ when finished.

      For example, in the procedure division: 

           EXEC CICS DELETEQ TS
               QUEUE(PASSED-TSQ-NAME)
               RESP(RESP-CODE)
     END-EXEC.
     IF RESP-CODE NOT EQUAL ZEROES
       PERFORM ERROR-DELETE-QUEUE.

      Because all of your applications can run as either the transferred-to or transferred-from screen transaction, you need to modify each application to both read and write the TSQ.

Get Next CICS Transaction ID API (CAMS515C)

       

What This API Does

This API allows an application program to get the next Transaction ID from the Terminal Control Table Terminal Entry (TCTTE) for the transferred-from terminal. After execution, the next transaction in the the TCTTE for the transferred-from terminal is reset to low values.

When to Use This API

A user screen control program can use this API to get the Transaction ID of the transferred-from terminal. This would be appropriate when the user screen control program determines that it needs to START the same transaction for the transferred-to terminal. See "User Screen Control Program" and "Save Transaction".

How to Use This API

To use the Get Next CICS Transaction ID API in your application program, do the following:

  1. Create a CICS communication data area in working storage. The fields for this data area are described in Table 22.      

    Table 22. CICS Communication Data Area for the Get Next CICS Transaction ID API
    Field Attributes In/out Description
    COMMAREA-DATA N/A N/A 01 level name.
    NEXT-CICS-TRANS-ID PIC X(04) Out The Transaction ID that is to be run at the target terminal.

  2. Initialize the NEXT-CICS-TRANS-ID field to low values.

  3. Start a transaction at the transferred-from terminal.

  4. Code the following CICS command into your application program: 
          EXEC CICS LINK PROGRAM('CAMS515C')
                     COMMAREA(COMMAREA-DATA)
                     LENGTH(04)
                     END-EXEC.

  5. Test the value of the NEXT-CICS-TRANS-ID field to determine if operation of the API was successful. If it contains low values, the application running at the transferred-from terminal executed a RETURN command without specifying a return Transaction ID. If it does not contain low values, operation of the API was successful and the field contains the return Transaction ID from the application running at the transferred-from terminal.

  6. If operation of the API is not successful, take applicable action.

Task Sequencing API (CAMI784C)

       

What This API Does

This API allows a user screen control program to control the sequence of execution of asynchronous tasks associated with a particular telephony session. The agents involved in the telephony session might both be in user mode. Alternatively, one agent might be in automatic mode and the other one in user mode.

The asynchronous tasks can use this API in two ways:

See Table 23 for descriptions of all input and output fields of this API.

When to Use This API

CICS is designed to control the sequencing of tasks that involve a single terminal and also control the dialog between that terminal and the host computer. For the user screen control program to transfer the screen environment from one terminal to another, two tasks must be STARTed on two different terminals. One task saves the environment of the transferred-from terminal and the other task restores that saved environment to the transferred-to terminal.

In this case, it is possible that the save task might not finish its processing before the restore task begins its processing.

You can use this API to sequence the tasks so that the saving task and the restoring task are performed in the proper sequence. This ensures a successful screen transfer between the two terminals.

Other uses of this API are the following:

How to Use This API

To use the Task Sequencing API in your user screen control program, do the following:

  1. Enter Y (yes) in the UM task seq field of the System Settings panel. If this field is set to N (no) or is blank, no task sequencing processing will be performed, even if the appropriate code is included in your program.

  2. Create a CICS communication data area in working storage of the user screen control program by copying the communication data area for this API.     The fields for this data area are described in Table 23. The layout is provided as a copy library member in the CallCoordinator SEZPCOPY target library, member name CAMC784. Refer to the library member for the actual field names.

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

    Table 23. CICS Communications Data Area for the Task Sequencing API (CAMC784)
    Field Attributes In/out Description
    COMMAREA N/A N/A 01 level name.
    COMMAREA-LEN PIC S9(04) value +195 In/out 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 (CAMI784C).
    COR-SYSID PIC X(4) In In a sysplex environment this is required. The CICS SYSID of the COR in which the API is to execute.
    FILLER PIC X(114) N/A Spaces. Reserved for future use.
    RETURN-CODE PIC S9(04) COMP out

    1
    Request not valid.

    8
    Routing error. See REASON-CODE

    9
    System error.

    REASON-CODE PIC S9(04) COMP Out For routing errors see "API Router".

    16
    The length of the Commarea was specified incorrectly.

    20
    A table addressability occurred.
    TSQ-REQUEST PIC X In The function requested is:

    R
    Request Execution permission.

    P
    Post task completion.

    C
    Cancel request.
    TASK-CONTROL-BLOCK PIC X(54) In The TSTCB passed from the CallCoordinator Screen Presentation Manager or the previous transaction in an execution chain.

  3. Collect the input data for the API.   The required input is the function being requested (FUNCTION-CODE) of the API and the contents of TASK-CONTROL-BLOCK. See Table 23 for descriptions of these fields.

  4. Move the data to the input fields on the CICS communication data area.

  5. Code the following COBOL statements into your application program. 
      EXEC CICS LINK PROGRAM ('CAM1784C')
       COMMAREA(CAMC784-COMMAREA)
       LENGTH(CAMC784-COMMAREA-LEN)
       END-EXEC.

  6. Test the value returned in the return code field of the CICS communication data area, to determine if the operation of the API was successful.

  7. If operation of the API was successful, determine the appropriate application program actions, based upon the value in the return code. See Table 23 for a description of this field.

  8. If the return code indicates operation of the API was not successful, take action applicable to the error indicated in the return code.

  9. Repeat API execution for other transactions as needed by the user screen control program.

If your user screen control program uses a chain of CICS transactions to perform its function, their sequence should be indicated by the program. Each transaction should do the following:

  1. Invoke the API using the code for the Request Execution Permission function and the data received from the CallCoordinator Screen Control Program.

  2. START the next task in the chain and pass the TSTCB to the transaction.

If this transaction is the last in the chain of transactions specified by the user screen control program, it should invoke the API using the code for the Post Task Completion function.

Return to Library Contents Previous Topic Top of Topic Next Topic Index Help