API Conventions

#### Search Results

Search

# API Conventions

Standard conventions are used throughout this documentation in the descriptions of the various Com-plete functions.

The conventions used are categorized as follows:

- Syntax Symbols

- Argument Coding

- Interface Linkage

- Return Codes

### Syntax Symbols

In the descriptions of function statement format, arguments enclosed in square brackets, [ ], are Optional.
However, an argument enclosed in square brackets can only be omitted if it is the last argument in the argument list. Com-plete handling requires that an optional argument which is not the last argument in the list must still be included. In this situation, the argument name should reference a field that contains zeros or blanks, depending upon whether the field is numeric or alphanumeric.

The following format statement illustrates the use of square brackets to indicate optional arguments.

    function (retcode,argument1,
           [,argument2]
           [,argument3])

This means that argument3 can be omitted, and if argument2 is not required, you must give it a dummy value as described above.

If two or more options enclosed within a single set of brackets are separated by a vertical bar, |, only one of the options must be coded.

Curly braces, { }, indicate that one of the enclosed items separated by a vertical bar(s), |, is mandatory.

The following format statement illustrates the use of curly braces and vertical bars to describe mandatory items.

    WRT {C|D|R}(....)

This means that the choice of function is determined by the specified suffix (enclosed within braces) to the character string WRT (that is, function WRTC, WRTD, or WRTR).

Note
Do not type square brackets, curly braces or vertical bars as part of the function statement.

### Argument Coding

Com-plete function names and their corresponding arguments are used to specify the services and options to be performed. The following general rules summarize the coding conventions followed throughout this documentation:

Rule 1: You code CALL statements to a subroutine with the function name.

Rule 2: Arguments are positional and must be coded in the order given.

### Interface Linkage

All programs, except Natural, which use Com-plete functions must be linked with the appropriate interface routines.

Online applications:
Online applications must be linked with the Com-plete interface modules which were loaded to a data set during Com-plete installation. There is a separate interface module for each individual function.

Batch applications:
Batch applications must be linked with the module COMPBTCH, supplied on the Com-plete load library, which contains entry points for all Com-plete functions allowed from a Batch environment.Com-plete Functions For Batch And Online Programs lists the Com-plete functions which are available from Batch.

For further information on how to run Batch programs, refer to the Batch section of the Com-plete System Programming documentation.

### Return Codes

Most Com-plete functions cause a return code to be issued at completion of their operation. The return code is placed in the first argument of the CALL statement.

Return codes supply information to the application program that can be used to determine the further course of program execution. For example, the following return codes are given in response to a terminal read request:

0 | Data read equals that requested.
4 | More data is available to read.
8 | Less data was read than requested.