Previous Topic
Table Of Contents
Next Topic

Layout of the HLL Reference Pages

Related Topics

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 format.

Each HLL reference page contains a leading section which briefly explains the use of the API interface.
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).
The 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 shown.)

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 format.

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:
#pragma linkage(name,os)
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:

Address: 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 to 'pointer'.

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.

Flag-Word: (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.
Fullword: 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 full word.
Unsigned Integer: As pertains to the Web server APIs, a four-byte, unsigned binary integer, stored within a full word.

Top