This document covers the following topics:
Due to the logic of the new dispatching mechanism, the Com-plete Application Programming Interface (API) had to be redesigned for Com-plete 5.1. While the internal logic of the interface has changed significantly, the usage of the interface has not. This was done to encourage users to convert their existing applications to use the new interface.
While Software AG strongly recommends that all applications be converted to use the new interface as soon as possible, in order to facilitate conversion to new Com-plete versions, a bridging mechanism has been provided which enables application programs which worked under Com-plete 4.6 to function unchanged under later Com-plete versions. However, note that this bridging mechanism costs more in terms of resources than the new interface.
Prior to this new interface being introduced, all Com-plete API calls entered the Com-plete nucleus using a pseudo Supervisor Call (SVC) which was trapped by Com-plete. Changes made in versions 4.5 and 4.6 of Com-plete have facilitated the introduction of a branch entry mechanism to the API routines. Branch entry to the nucleus is the major change which will effect currently running assembler applications programs which used the MCALL interface. Applications correctly using the High Level Language Interface (HLLI) as previously documented will not have to be changed at all as you will see later.
Note:
The term 'correctly' above relates to the provision of an 18F
savearea to the HLLI routine. Please refer to the migration notes for Com-plete
5.1 for details of API functions that previously worked even if an 18F savearea
was not provided. All API functions now require an 18F savearea.
To use the branch entry interface, the following must be taken into account.
Register 13 must point to a standard 18F savearea which will be used to save and restore the application program's savearea.
Registers 14, 15, 0 and 1 will be changed by the call to the application programming interface. Registers 2 to 13 will not be altered.
Access Registers 1 to 15 will be returned unaltered to the application program.
As you will see from the above, applications using the HLLI interface will not have to be changed as they already have taken the above requirements into account. The changes that assembler programs must take into account are as follows:
Registers 14 and 0 were generally returned intact to the application issuing the MCALL functions. This will no longer be the case.
Register 13 did not have to point to a standard 18F savearea when issuing an MCALL function.
Programs which are relocatable and use branch entry to the new API will have to be aware of the following.
Register 13 will always be relocated as it must be located in the application's thread.
Register 14 will be relocated if it is located inside the application's thread.
In order to use branch entry to the API, two new parameters (SAVEAREA and COMREGA) have been added to the MCALL macro to determine how it will enter the Com-plete API. Note that an unchanged program will always expand to use the SVC entry as branch entry will only be used if explicitly requested on the MCALL or if globally set using the CMOPBE macro described later.
The functions to get and free storage (i.e. MCALL GETMAIN and MCALL FREEMAIN) also require a savearea to use the branch entry interface which leaves the programmer in a catch 22 situation when trying to maintain re-entrancy in an assembler program. How can storage be acquired for a savearea if no savearea exists? This is addressed through the provision of two macros called CMOPGETM and CMOPFREM which are described below. Software AG recommends that these macros are only used when absolutely necessary, i.e. to get working storage at the start of a program and free it at the end of the program. In all other cases, the standard MCALL or HLLI functionality should be used.
It is possible to mix branch entry calls to the interface with SVC entry calls, though this is not recommended. While it is technically possible, it will lead to confusion in modules. You are recommended to totally change a module to use the branch entry interface when it is being converted.
Where a module has been written according to normal IBM standards, it will generally comply with the conditions for branch entering the API. For this case, a macro (CMOPBE) has been provided to change the default for the entire module or for entire sections of a module. CMOPBE sets global indicators to cause MCALLs following the invocation of this macro to expand based on the global specifications of the CMOPBE macro. It is possible to invoke this macro a number of times to have different options for different sections of the module, however, be aware that the MCALL will take it's defaults from the last invocation of the macrophysically preceding it in the assembler source.
- CMOPBE - Set global indicators
- Syntax:
- Parameters
For a Description of SAVEAREA and COMREGA refer to the section How to use the Branch Entry Interface.
- CMOPGETM - Get storage
This macro will acquire storage for the requested length if it is available.
- Syntax:
- Parameters
LEN Required Amount of required storage. (see Note 1) COMREGA Optional (See Note 3) LOC Optional Location of storage requested. The default depends on the setting of AMODE. With AMODE=24, the default is BELOW. With AMODE=31, the drfault is ANY. - Return Codes:
- CMOPFREM - Free storage
Free storage previously acquired by a CMOPGETM request.
- Syntax
- Parameters
LEN Required Amount of storage to free. (see Note 1). ADDR Required Address of the storage to free (see Note 2). COMREGA Optional (See Note 3) - Return Codes:
0 Storage freed successfully 4 Should not occur 8 Space to be freed was not allocated 12 Either the request is invalid or the FQE chain in the thread is corrupted Notes:
- "length" can be specified as a numeric constant, a numeric equate, as register content or a field containing the value.
Examples:
LEN=200 specifies a length of 200 Bytes
LEN=(R3) length is contained in R3
LEN=(*,LENGTH) length is contained in field LENGTH- "address" is the name of a field at the start of the area to be freed. As "length" It can also be specified in register or indirect field notation.
Examples:
ADDR=START free storage from label START
ADDR=(R5) free storage addressed by R5
ADDR=(*,STOR) free storage addressed in field STOR- For a Description of COMREGA refer to the section How to use the Branch Entry Interface.
Any programs using this interface to date will have fully compiled with the requirements for using branch entry and therefore require no changes to their source code. To use the branch entry interface, they must simply be linked with the stub module called TLOPUSER provided in the APS library. You should make sure that you always use the latest version of the module, which can be found in the latest APS cumulative fix pack loadlib.
Note that it is not possible to simply re-link a load module with TLOPUSER as the HLLI interface routines previously included must first be deleted using the linkage editor REPLACE statement. While simply linking in the new TLOPUSER will function correctly, the linkage editor will NOT delete references which were previously resolved using the older HLLI interface routines unless it is explicitly told to do so.
Programs which are not re-linked will continue to function normally, however, as the older HLLI routines used SVC entry to the nucleus, these routines will continue to experience the overhead of using this entry to the interface.