Setting up the interface for preinitializable programs
The interface for preinitializing programs is shown in Figure 1.
The LL field is a halfword containing the value of 16. The halfword that follows must contain 0 (zero).
- 'INIT '
- Initializes the C environment and, returns two tokens that represent the environment, but does not run the
program. Token 1 and token 2 must both have the value of zero on an INIT call;
otherwise, preinitialization fails.
You can initialize only one C environment at a time. However, you can make the sequence of calls to INIT, CALL, and TERM more than once.
- 'CALL '
- Runs the C program using the environment established by the INIT request,
and exits from the environment when the program completes. The CALL request
uses the two tokens that were returned by the INIT request
so that C can recognize the proper environment.
You can also initialize and call a C program by passing the CALL parameter with two zero tokens. The C program processes this request as an INIT followed by a CALL. You can still call the program repeatedly, but you should pass the two zero tokens only on the first call. Once the C environment is initialized, the values of the tokens are changed, and must not be modified on any subsequent calls.
Calling a C program other than the one used to initialize the C environment is not supported, especially if write-able static is needed by the program being called. This is because write-able static was allocated and initialized based upon the program used to initialize the C environment.
- 'TERM '
- Terminates the C environment but does not run the program. The program used to terminate the C environment should be the same as the program used to initialize the C environment. Usage of a different program to terminate the C environment is unsupported.
- 'EXECUTE '
- Performs INIT, CALL, and TERM in succession.
- Length of extended parameter list
- The length includes the 4 bytes for the length field. Valid decimal values are 20, 28, and 32.
- First and second C environment tokens
- These tokens are automatically returned during initialization; or, you can use zeros for them when requesting a preinitialized CALL, and the effect is that both an INIT and a CALL are performed.
- Pointer to your program parameters
- The layout of the parameters is shown in Figure 1, Interface for Preinitialization Programs. If no parameter is specified, use a fullword of zeros.
- Pointer to your runtime options
- To point to the character string of runtime options, refer to Figure 1. The character string consists of a halfword LL field that contains the length of the list of runtime options, followed by the actual list of runtime options.
- Pointer to an alternative main
- This field is not supported in C. However, if you want to use the seventh or eighth fields, use a full word of zeros as a place holder.
- Pointer to the service vector
- If you want certain services (such as load and delete) to be carried out by other code supplied by you (instead of, for example, by the LOAD and DELETE macros), use this field to point to the service vector. See Figure 1.
- Request modifier code
- When your request is INIT, CALL, or EXECUTE, you
can specify any of the following request modifier codes:
- 0
- Does not change the request.
- 1
- Loads all common library modules as part of the preinitialized environment.
- 2
- Loads all common and C library modules as part of the preinitialized environment.
- 3
- Reinitializes the environment. If the environment is already established, frees all HEAP storage and any ISA overflow segments. Do not use this code if subsequent calls depend on storage that is still being allocated by previous calls.
- 4
- Allows you to create more than one environment. The new environment
is chained with existing request modifier 4 environments or a batch
environment, where possible, so that C memory file sharing among
the environments is possible. Details on chaining and C memory file
sharing support are covered in Multiple preinitialization compatibility interface C environments.
The user-supplied service routine vector is not supported when you use request modifier value 4 in the extended parameter list. Do not code this if you are using the service routine vector. If you do, an abnormal end will occur.
- 5
- Allows you to create more than one environment. The new environment is separated from other environments which may already exist. This environment does not support sharing of C memory files with other preinitialization compatibility interface environments.
When your request is TERM, you can specify either of the following request modifier codes:
- 0
- Does not change the request.
- 1
- Forces termination. Ends the C environment without any of the usual checks. Code this field only when you cannot request normal termination. You must ensure that the environment you are forcing to end is not in use.
The length you specify in the first field of the extended parameter list makes it known whether you have specified a request modifier code or not.
Runtime options are applied only at initialization and remain until termination. You must code PLIST(MVS) in the called C program in order for the preinitialization to work.
The options ARGPARSE|NOARGPARSE have no effect on preinitialized programs. The assembler program has to provide parameters in the form expected by the C program. Thus, if the C program is coded for the NOARGPARSE option, the argc should be set to 2, and parameters passed as a single string.