If you want to write services similar in form and description to Language Environment callable
services, follow the guidelines listed below.
- Callable service parameters must follow the data type descriptions outlined in z/OS Language Environment Programming Reference.
- Argument passing is by one level of indirection, either “by reference” or “by value”. See Passing arguments between routines for these argument passing styles.
- Avoid the use of operating system services and macros. Use Language Environment services whenever possible.
- Always use the prototype definition or the entry declaration whenever possible.
- Avoid using the CEE3SPM callable service (see z/OS Language Environment Programming Reference). CEE3SPM can change the condition handling semantics of the HLLs supported by Language Environment.
- Language Environment assumes
the following defaults for character strings:
- For input arguments, a length-prefixed string (with the length of the 2-byte prefix not included in the length value)
- For output arguments, a fixed-length string of 80 bytes, padded on the right with blanks as necessary.
- Allow a feedback code area to be optionally passed as the last parameter to the callable service. The feedback code must be a FEED_BACK data type and conform to the layout described in Using condition tokens.
- If omitted arguments are permitted by the HLL, a zero or NULL
pointer must be used to
indicate the omitted parameter in the parameter list that is passed
to the callable service. For example:
The last parameter passed in the list must have the high-order bit on to indicate that it is last. If the last parameter is omitted, the zero value that the user passes in the parameter list must have the high-order bit on, for example X'80000000'. Therefore, you must allow the user of the callable service to check for this bit when the last parameter passed to the service is omitted.
- When documenting callable services, follow the same general format
used to document each of the callable services in this information.
Each callable service description should contain (in this order):
- A general description of what the service does
- A diagram indicating the syntax of the call to the service
- A complete description of each callable service parameter and an identification of the required data type
- A list of possible feedback codes that can be returned by the service to its caller
- Usage notes that provide additional needed information to the user, such as a list of related callable services
- An example or examples of usage