gtpc2m7vC/C++ Language Support User's Guide

tpf_cresc-Create Synchronous Child ECBs

This function creates an ECB for immediate processing by the requested program. The ECB is created in the same subsystem and subsystem user as the parent ECB.

When exiting, the child ECB will notify the parent by posting an event on which the parent is waiting for completion. Posting the event gives the child ECB the ability to pass the return code value back to the parent ECB.

The tpf_cresc function can be used to allow the parent ECB to create and then wait for multiple child ECBs to be completed by coding it multiple times, setting tci.wait = TPF_CRESC_WAIT_YES on in the last entry. This will result in the creation of the child ECBs and will place the parent ECB in a wait state until all child ECBs have been completed or until they time out.

Format

#include <tpfapi.h>
struct tpf_evobk_list_data *tpf_cresc(const struct tpf_cresc_input *tci);

The tpf_cresc_input structure consists of the following members:

program
A pointer to the name of the program that will be activated with the created entry control block (ECB).

istream
The I-stream number on which the child ECB will be dispatched. The following symbols are defined in the tpfapi.h file for use in the istream member:
TPF_CRESC_IS_MAIN     Create the child ECB on the main I-stream.
TPF_CRESC_IS_MPIF     Create the child ECB on the MPIF I-stream.
TPF_CRESC_IS_SAME     Create the child ECB on the same I-stream as the
                      parent.
TPF_CRESC_IS_BALANCE  Create the child ECB on the least busy I-stream.

timeout
A value, from 0 to 32 768, which determines how many seconds the parent ECB waits for the child ECBs to end. If a 0 value is given, the parent will wait indefinitely until the child ECBs exit. This member is ignored unless the wait member is set to TPF_CRESC_WAIT_YES. This value will be in effect in 1052 state.

wait
Determines if the child ECBs should be created and if the parent ECB should wait the length of the value specified for them to be completed. The following symbols are defined in the tpfapi.h header file for use in the wait member:
TPF_CRESC_WAIT_NO     Do not create the child ECBs, just initialize the
                      creation information of the child ECB.
TPF_CRESC_WAIT_YES    Create and dispatch the child ECBs and wait for
                      them to be completed.

data
A pointer to the data to be passed to the child ECB. If no data will be passed to the child ECB, set a NULL pointer.

data_length
The number of bytes of data to be passed to the child ECB. If no data will be passed to the child ECB, set this field to zero.

Normal Return

A pointer to the event block with list item data (see the tpf_ev0bk_list_data structure) is returned following a tpf_cresc call that specifies tci.wait = TPF_CRESC_WAIT_YES. The tpf_ev0bk_list_item structure will point to the start of the list where all child ECB return codes will be stored. The application must set up the child ECB return codes that are used.

A NULL pointer is returned following a tpf_cresc call that specifies tci.wait = TPF_CRESC_WAIT_NO.

Error Return

If any of the following conditions are met, a SNAPC error is issued and the ECB exits:

Programming Considerations

Note:
Limit the use of this function to prevent storage depletion.

Examples

The following example creates two child ECBs and places the parent ECB in a wait state until both child ECBs have completed processing or until 100 seconds have elapsed.

When the parent ECB has been reactivated, it interrogates the list item data that has been appended to the event block to determine the value returned by the child ECBs.

#include <stdio.h>
#include <stdlib.h>
#include <tpfapi.h>
 
int QXQZ(void)
{
 
/********************************************************************/
/* Variable definitions                                             */
/********************************************************************/
 
struct tpf_cresc_input tci;            /* tpf_cresc I/P parameter   */
                                       /* structure                 */
 
struct tpf_ev0bk_list_data *ebptr;     /* Pointer to Event block    */
                                       /* with list item data       */
 
tpf_ev0bk_list_item *liptr;            /* Pointer to list item data */
 
int index;                             /* Index for accessing list  */
                                       /* item data                 */
 
/********************************************************************/
/* Initialize parameters for CRESC WAIT=NO call.                    */
/********************************************************************/
 
char data[11] = "Sample data";         /* Data to be passed         */
 
tci.program = "QPM1";                  /* Pgm for child to enter    */
tci.istream = 1;                       /* I/S for child to run on   */
tci.wait = TPF_CRESC_WAIT_NO;          /* Don't create ECB yet      */
tci.data_length = 11;                  /* Pass 11 bytes of data     */
tci.data = data;                       /* Pass data assigned to     */
                                       /* variable data             */
 
/********************************************************************/
/* Issue CRESC WAIT=NO call.                                        */
/********************************************************************/
 
ebptr = tpf_cresc(&tci);              /* Issue WAIT=NO call which   */
                                      /* returns a NULL pointer     */
 
/********************************************************************/
/* Initialize parameters for CRESC WAIT=YES call.                   */
/********************************************************************/
 
tci.program = "QPM1";                 /* Pgm for child to enter     */
tci.istream = TPF_CRESC_IS_MAIN;      /* I/S for child              */
tci.timeout = 300;                    /* Timeout value for parent   */
                                      /* Parent will wait forever   */
tci.wait = TPF_CRESC_WAIT_YES;        /* Create all children        */
tci.data_length = 0;                  /* No data being passed       */
tci.data = NULL;                      /* No data being passed       */
 
 
/********************************************************************/
/* Issue CRESC WAIT=YES call. All child ECBs requested to date will */
/* now be created and dispatched.                                   */
/********************************************************************/
 
ebptr = tpf_cresc(&tci);               /* Issue WAIT=YES call which */
                                       /* will return a pointer to  */
                                       /* the Event block created   */
 
/********************************************************************/
/* Invoke the TPF_EVENT_LIST_ITEM macro to access the list items    */
/* appended to the Event block created for this event.              */
/*                                                                  */
/* The list item, one for each child created, will contain          */
/* information on whether the item has been posted (child has       */
/* exited), the item has been posted with an error (child exited    */
/* due to a system error), and the return code set by the child ECB.*/
/*                                                                  */
 
/* exit(4);                                   This is how the child */
                                       /* ECB exits and returns a   */
                                       /* value to the parent ECB.  */
 
/* If the item has been posted, check to see if an error has been   */
/* posted. If so, issue the message 'Child exited with error'. If   */
/* no error has been posted, check the return code set by the child.*/
/* If the return code = 4, issue the message 'Test case successful'.*/
/* If the return code ^= 4, issue the message 'Test case            */
/* unsuccessful.' If the item has not been posted, issue the        */
/* message 'The item is not posted because the timeout value was    */
/* exceeded.'                                                        */
/********************************************************************/
 
for (index = 0; index < ebptr->evnbklc; index = index+1)
{
liptr = TPF_EVENT_LIST_ITEM(ebptr,index); /* Call macro to return   */
                                       /* address of list item data */
 
if ((liptr->evnbklif & TPF_EVNBK_POST) != 0)  /* Item posted?       */
     if ((liptr->evnbklif & TPF_EVNBK_ECDE) != 0) /* Yes, posted    */
                                              /* with error?        */
     {
     printf("Child exited with error");  /* Yes, issue msg.         */
     }
     else
     {
           if (liptr->evnbkvls == 4)   /* No, check RC = 4          */
           {
           printf("Test case successful"); /* Yes, successful       */
           }
                                       /* No, unsuccessful          */
           else printf("Test case unsuccessful.");
     }
else
      printf("The item is not posted because the timeout value was exceeded.");
}
 
exit(0);                               /* Exit                      */
return 0;                              /* Avoid compiler warning    */
}

Related Information