Table Of Contents
Layout of the HLL Reference Pages
API Function Index
Each of the HLL API interface is documented in separate HTML page. These pages are
linked from the API Index. Each reference page is laid out in substantially the same
- Each HLL reference page contains a leading section which briefly explains the use of the
- This is followed by the Arguments Section which defines each of the parameters which can
be passed to the function. For some server functions, this section can be further broken
down into subsections (one for each of the major subfunctions of the interface).
Arguments Section describes parameter values using the terminology given below. The
argument type, for each supported language is also shown. (For C/370, the NEON-supplied
header file contains typedef statements which define the values
Additional details showing how to create and use arguments of the proper type, are
illustrated in the examples for each supported language.
- After the arguments section, the return code values are explained.
- Finally, there is an example for each of the supported languages; C, COBOL, and PL/I.
Note: All manifest constants shown
outside of the COBOL language examples are given with underbar characters (e.g.
SWS_SUCCESS). The corresponding COBOL constant definitions use the hyphen character
wherever underbars are shown (e.g. SWS-SUCCESS).
Call by Reference
Call by value
Some compilers employ a call by value mechanism. When subroutines are invoked
with this method, some parameter values are passed directly to the called program using
the 1st-level parameter list area, or a general purpose registers. Values are frequently
returned directly within a general purpose register.
Call by Reference
All Shadow OS/390 Web Server API interface routines expect to be invoked using a call
by reference mechanism which is implemented with the standard MVS parameter list
Upon entry to any server API routine, general purpose register 1 must point to a
parameter list composed of 1 to n fullwords. Bit zero of the last fullword within the
parameter list must be set to one.
Each fullword of the parameter list contains an address value referring to the main
storage location containing the actual function argument.
The method for ensuring that call by reference conventions are used for
subroutine calls varies by language.
- For C/370 each sub-routine prototype contains the specification:
- For COBOL this is automatic.
- For PL/I, each API routine is declared as:
DCL NAME ENTRY EXTERNAL OPTIONS(RETCODE, INTER, ASM);
Terminology Used in the Reference Pages
The following terminology is used within the HLL API reference page:
- A main-storage address, specified by the low-order 31-bits of a four-byte (32-bit)
fullword. In the various high-level languages, the term 'address' is generally equivalent
- Buffer Area
- An arbitrary number of contiguously located bytes in main storage. The size of the
buffer area may be a pre-defined value, as specified for the individual API interface.
Most buffer areas, however, are user created and variable in length. Either the length of
the entire buffer or the length of the data value contained within the buffer is specified
as an argument to the API function.
- (As it pertains to the Web server's APIs) A four-byte signed or unsigned integer, stored
within a fullword. The storage format is usually identical to unsigned integers, except
the fullword is not processed as an integer value. Rather, each individual bit position
specifies a parameter option value.
Usually manifest constants, are defined within the
header files, and are used to specify the value of flag-word arguments. These manifest
constants can often be added or logically OR-ed together to form the four-byte flag word.
- A four-byte storage area, generally aligned on a four-byte boundary. A fullword, may
contain either a storage address or a signed or unsigned binary integer.
- Manifest Constant
- A value defined within a NEON-supplied header file and used (possibly added or OR-ed
with other constants) as a function call argument.
Depending on the high-level
language, manifest constants can be compiler pre-processor symbols (C and PL/I) or actual
program constant data areas (COBOL and PL/I). Manifest constants may be formed as
Flag-word values or as signed or unsigned integers.
- Null-terminated String
- Within a buffer area, null terminated strings can often be used to indicate the actual
length of the data value. The end of the value (and by derivation the value length) is
delimited by a one-byte binary zero (X'00'). The value begins in the first position of the
buffer area (if non-zero), and continues up-to, but not including, the delimiting binary
zero at the end. A zero-length null-terminated string is recognized when the first byte of
the buffer is a binary zero.
- Signed Integer
- As pertains to the Web server APIs, a four-byte, signed binary integer, stored within a
- Unsigned Integer
- As pertains to the Web server APIs, a four-byte, unsigned binary integer, stored within
a full word.