gtpc2m72 | C/C++ Language Support User's Guide |
This function creates a new ECB on another I-stream.
Format
#include <sysapi.h>
void swisc_create(struct swisc_create_input *create_parameters);
or
#include <sysapi.h>
void swisc_create(struct swisc_create_input *create_parameters,
TPF_DECB *decb);
- create_parameters
- A pointer to a fully initialized swisc_create_input
structure. The following fields are defined in struct
swisc_create_input:
- program
- A pointer to the name of the first program segment to be executed by the
created ECB. This can be a DLM, a BAL segment, or a TARGET(TPF) C
segment. Data can only be passed to program via the EBW work
area or via a core block (see ebw_data_length, ebw_data,
and data_level below).
- istream
- The I-stream where the new entry is to be created; either the
I-stream (1-based ordinal) number, or one of the following:
- SWISC_IS_MAIN
- Create the new entry on the main I-stream.
- SWISC_IS_MPIF
- Create the new entry on the MPIF I-stream.
- SWISC_IS_BALANCE
- Create the new entry on the least busy I-stream.
- cpu_list
- One of:
- SWISC_LIST_DEFER
- Add the new entry to the deferred list.
- SWISC_LIST_INPUT
- Add the new entry to the input list.
- SWISC_LIST_READY
- Add the new entry to the ready list.
- bypass
- One of:
- SWISC_BYPASS_NO
- The istream value is limited to the I-streams usable by
applications, as controlled by the main supervisor command ZCNIS.
- SWISC_BYPASS_YES
- The istream value is limited to all the I-streams online
(active) in the CPC.
- ebw_data_length
- The number of bytes of data to be passed to the new entry, from 0 to
104.
- ebw_data
- A pointer to void containing the address of data to be passed to the new
entry beginning at EBW000.
- data_level
- One of 16 possible values representing a valid data level from enumeration
type t_lvl, expressed as Dx, where
x represents the hexadecimal number of the level (0-F).
The data on data level Dx is passed to the new
entry. If no data level data is to be passed to the new entry, code
NO_LVL.
- decb
- A pointer of type TPF_DECB *, representing a valid data event control
block (DECB). The working storage block on the specified DECB is passed
to the new entry. If a DECB is specified, the data_level field
in create_parameters must be set to the value NO_LVL.
Normal Return
Void.
Error Return
Not applicable.
Programming Considerations
- This macro can be executed on any I-stream.
- If data_level is not set to NO_LVL, the data level
specified must have an attached block. This block will be unhooked from
the issuing ECB upon return from the swisc_create function.
- If decb is specified, the DECB must have an attached
block. This block will be unhooked from the issuing ECB on return from
the swisc_create function.
- Only a single working storage block can be passed to the new entry;
therefore, if decb is not set to NULL and data_level is not
set to NO_LVL, control is transferred to the system error routine and
the issuing ECB will be exited.
- No I/O should be outstanding when calling this function.
- System functions required to act on physical I-streams must set
bypass to SWISC_BYPASS_YES.
- If istream is set to SWISC_IS_BALANCE, the TPF
scheduler will be invoked.
- ECBs may or may not be started on the same I-stream where they are
created, depending on the options set by the programmer and whether the
scheduler is invoked.
- In addition to the normal macro trace information, the trace entry
resulting from executing swisc_create will contain the activation
type as CREATE, the name of the target program and the target I-stream
number.
- If you use this function to create an ECB that will enter a dynamic load
module (DLM) with an entry point defined by the main function, the
TPF system assumes that any core block attached to data level 0 (D0) contains
a command string that will be parsed into argc and argv
parameters for the main function. See TPF Application Programming for more information about
the main function.
- Applications that call this function using DECBs instead of ECB data
levels must be compiled with the C++ compiler because this function has been
overloaded.
- This function is implemented in dynamic link library (DLL)
CTAD. You must use the definition side-deck for DLL CTAD to link-edit
an application that uses this function.
Examples
The following example creates a new entry and adds it to the ready list for
whichever application I-stream is least active. No data is passed to
the new entry. When the new entry is gets control of the selected
I-stream, it will execute program XYZ1.
#include <sysapi.h>
·
·
·
struct swisc_create_input create_parameters;
extern void XYZ1(void);
create_parameters.program = "XYZ1";
create_parameters.istream = SWISC_IS_BALANCE;
create_parameters.cpu_list = SWISC_LIST_READY;
create_parameters.bypass = SWISC_BYPASS_NO;
create_parameters.ebw_data = NULL;
create_parameters.ebw_data_length = 0;
create_parameters.data_level = NO_LVL;
swisc_create(&create_parameters);
The following example creates a new entry and adds it to the deferred list
for the main I-stream. No data is passed to the new entry;
however, the core block attached at the specified DECB is unhooked from the
issuing ECB and passed to the new entry. When the new entry gets
control of the selected I-stream, it will run program XYZ1.
#include <sysapi.h>
·
·
·
struct swisc_create_input create_parameters;
extern void XYZ1(void);
TPF_DECB *decb;
create_parameters.program = "XYZ1";
create_parameters.istream = SWISC_IS_MAIN;
create_parameters.cpu_list = SWISC_LIST_DEFER;
create_parameters.bypass = SWISC_BYPASS_NO;
create_parameters.ebw_data = NULL;
create_parameters.ebw_data_length = 0;
create_parameters.data_level = NO_LVL;
swisc_create(&create_parameters, decb);
Related Information
creec, __CREEC-Create a New ECB with an Attached Block
For more information about DECBs, see TPF Application
Programming.