gtpc2m7v | C/C++ Language Support User's Guide |
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:
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.
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.
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
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