A callable service allows for compilers to convert runtime options
strings specified in a source program to an options control block
(OCB). This interface also supports the runtime options that are not
part of the OCB, specifically ENV, PLIST, REDIR, EXECOPS, and ARGPARSE.
These options are returned in the Supplementary Options Control Block
(SOCB). The compiler would then create the OCB in the same format
as the CEEUOPT CSECT file. This service is loadable and requires
multiple calls, one to obtain the size of the working storage block
(which includes the size of the OCB), and subsequent calls for the
HLL to pass the runtime options string and the working storage and
receive the parsed output.
CEECOPP is called by loading the executable named CEECOPP (using
the LOAD SVC service) which resides in the SCEERUN data set. Then
call the entry point returned from the load using:
Syntax
void
CEECOPP (
function_code,
storage_size,
storage_addr,
options,
ocb_addr,
socb_addr,
roet_addr,
ocb_status,
socb_status,
rc)
INT4 *function_code;
INT4 *storage_size;
POINTER *storage_addr;
PREFIXSTR *options;
POINTER *ocb_addr;
POINTER *socb_addr;
POINTER *roet_addr;
POINTER *ocb_status;
POINTER *socb_status;
INT4 *rc;
- function_code (input)
- Indicates the type of request. The valid function codes and meanings
are:
- 1
- Obtain the size of working storage. The first call is required
to communicate to the caller how much storage is required by Language Environment to parse
the options, the size of the resulting OCB, and the size of the error
table. It is the caller's responsibility to acquire the storage and
return the address to Language Environment in the
second call.
- 2
- Initialize OCB and parse the supplied options. The second call
is used to initialize the OCB and to parse the options and save them
in the OCB.
- 3
- Parse the supplied options. Subsequent calls are used to parse
the options save them in the OCB created by function code 2.
- storage_size (output)
- The amount of storage required by Language Environment to do
the parse. This size includes the amount of working storage needed
to parse the string, the resulting OCB, and an error table. This is
used in conjunction with function_code equal
to 1.
- storage_addr (input)
- The address of storage of the length returned by Language Environment in the
first call. This is used with function_code 2
and 3.
- options (input)
- A character string containing the runtime options. This is a halfword-prefixed
length string. The string is not altered and can reside in read-only
storage. This is used in conjunction with function_code 2
and 3.
- ocb_addr (output)
- The address of the options control block that was created with
the parsed options. The compiler should convert this block into a
CEEUOPT CSECT. The storage used for the OCB is obtained from the storage
provided by the caller. The length of the OCB is found directly within
the OCB itself. The OCB is constructed so that there are no relocatable
address constants and is essentially a stream of hex information.
This is used with function_code 2 and 3.
For an example of an options control block, see Options control block and supplementary options control block.
- socb_addr (output)
- The address of a supplementary options control block (SOCB) that
was created with the parsed options. The compiler should convert this
block into a format that is suited to the caller. Language Environment does
not retain this information. The storage used for the SOCB is obtained
from the storage provided by the caller. The length of the SOCB is
found directly within the SOCB itself. The SOCB is constructed so
that there are no relocatable address constants and is essentially
a stream of hex information. This is used in conjunction with function_code 2
and 3. For an example of a supplementary options control block, see Options control block and supplementary options control block.
- roet_addr (output)
- The address of the runtime options error table created. The caller
could convert this error table into error messages as part of the
compiler output in its normal way of outputting errors. This is used
in conjunction with function_code 2 and
3. The format of the runtime options error table is shown in Figure 1.
- ocb_status (output)
- A fullword integer that contains the status of output OCB. If
zero, no OCB entries were made. If nonzero, OCB entries have been
made.
- socb_status (output)
- A fullword integer that contains the status of output SOCB. If
zero, no SOCB entries were made. If nonzero, SOCB entries have been
made.
- rc (output)
- A fullword integer that contains the return code. This is used
in conjunction with both function_code 2s.
The possible values are:
- 0
- Options parsed with no errors, OCB entries made.
- 4
- Invalid function code detected. No action performed.
- 8
- Invalid function code sequence. Function code 3 (parse only) was
received before function code 2 (initialize and parse).
Usage Notes: - In the OCB there are no address constants; therefore, no RLDs
need to be created.
- Options string length limitation is 64K bytes.
- CEECOPP is reentrant and is marked AMODE(31)/RMODE(ANY). It is
the caller's responsibility to insure the proper AMODE upon entry.
CEECOPP does not switch AMODEs.
- Invocation of CEECOPP is through BALR 14,15.
- If the OCB_status parameter is zero,
the compiler should not generate the CEEUOPT CSECT.
- If the roet_error_count field in the
ROET is not zero, errors occurred in the parse of the options string.
The errors are contained in the table.
- The roet_error_code field is in the
format of a Language Environment condition
token which is described in Figure 1. The message numbers
associated with the feedback codes that could be found in the runtime
options error table are between CEE3601I and CEE3629I. For a description
of these messages, see z/OS Language Environment Debugging Guide.
- Figure 1 shows the format of the runtime
options error table.
Figure 1. Runtime
options error table