Com-plete Servers

#### Search Results

Search

# Com-plete Servers

This document describes the Com-plete server facility.

This document covers the following topics:

- Overview

- Server Definition

- Server Initialization

- Server Termination

- Server Command Interface

- Server Invocation

- Server DSECTs

- Server Request Routine

## Overview

The modifications to Com-plete required for the implementation of the DB2 interface has resulted in the introduction of a new independent server facility to Com-plete. This facility enables Com-plete to support products which require their own subtask(s) and/or special invocation during startup and termination.

In addition to the DB2 interface, other SOFTWARE AG products such as the Natural Bufferpool Manager, the SAG EDITOR and the Com-plete JES and CONSOLE interfaces have been adapted to use this facility.

3rd party products such as TableBase (Data Connetics) and TABEX (BOI) can also use this feature.

In general, the functions to be provided by user-defined servers have no restrictions. Com-plete provides a basic framework of facilities, consisting of the following:

- Definition

- Initialization

- Termination

- Command Interface

- Invocation

These are described in more detail in the following sections. This section also illustrates server DSECTs, and provides information on the server request routine.

## Server Definition

You can define servers using the SERVER sysparm:

    SERVER=(serv-id,init-mod,p1,p2 ... pn)

where:

serv-id | is the ID for this server (1-8 characters).
init-mod | is the name of the initialization/termination routine.
p1,p2...pn | are parameters to be passed to the initialization routines.

Com-plete builds a server directory dynamically and provides a Server Directory Entry (SDE) for each server. Note that user-defined servers must be defined after the Com-plete servers.

The layout of the SDE is illustrated in the section Server DSECTs. It is mapped by the macro

    CMSRVD DDIR,LIST=YES

provided on the distributed source library.

### Server Main Routine

The server initialization/termination routine specified in the SERVER sysparm entry is loaded dynamically at Com-plete startup time and called in the key of Com-plete. In z/OS and z/VSE environments, the program is called according to the AMODE and RMODE options from the linkage editor and must return with the AMODE indicated in RE on entry (BSM instruction).

The main routine executes under control of the main Com-plete task (OC).

All operating system functions are available, except Com-plete operations (MCALLs), which are not allowed.

Registers upon entry (all calls):

R1 | parameter list pointer (see individual function).
R2 | COMREG
RD | 18F save area
RE | return address (high order bit contains AMODE of caller)
RF | entry point

## Server Initialization

The server initialization takes place after activation of any Com-plete subtasks (TAM, MSGPO, THREADn). If the user-defined server attaches any further subtask(s), you must consider the priority carefully, since the default from the ATTACH SVC will put this subtask immediately behind OC, meaning that the later activation of TAM, MSGPO etc. will put these Com-plete tasks behind the server task(s). A value of minus 2 (-2) or less for DPMOD on the ATTACH is recommended.

Parameter list for initialization:

P1 | address of function code "INIT".
P2 | address of the Server Directory Entry.
P3 | address of the parameter string from the SERVER sysparm.

The parameter string from the SERVER sysparm definitions is constructed in the following way:

    (LL(P1...........,Pn))

where:

LL | 2 bytes containing the total length of all parameters (not counting LL field itself).
P1,..Pn | parameter value(s).

### Example:

    SERVER=(TEST,TLINTEST,aaa,bbb,r=17)

The data pointed to by R1 will look like this:

    X'000C',C'aaa,bbb,r=17'

After successfull completion of the server initialization, the fields SRVEMCB and SRVESERV must be set in the SDE. The meaning of these fields is as follows:

SRVEMCB | The content and meaning of this field is up to the individual server. However, the initialization routine must ensure that this field contains a non-zero value, otherwise the server is considered to be not active.
SRVESERV | Contains the entry-point for server calls via the ALLOCATE/DEALLOC SERVER function (see below). The high-order bit of this address is used to set the AMODE.

## Server Termination

Since the termination process is basically a reverse initialization, this request is also passed to the main-routine (see above).

Termination calls are triggered either by Com-plete termination or using the operator command

    SERV TERM,serv-id

The server routine is responsible to free all obtained storage, DETACH the activated subtask(s) and to CLOSE any open datasets.

Parameter list for termination:

P1 | address of function code "TERM"
P2 | address of the Server Directory Entry

The server routine has to ensure that the SRVEMCB field is set to zero.

## Server Command Interface

Various requests can be passed to the individual server using the Com-plete operator command

    SERV serv-id,request data

Parameter list for operator interface:

P1 | address of function code "CMND"
P2 | address of the Server Directory Entry
P3 | address of request data string from the command (for format, see the section on server initialization above.)

## Server Invocation

The invocation of a user-defined server can be achieved in 2 different ways.

1. The server directory entry for a given SERVER-ID can be found by using the
   following macro:

       CMSRVD QUERY,NAME='serv-id'

   This function needs addressability to COMREG (any register) and will return the address of the directory entry in R1 if this server is up (R15=0), otherwise R15 will be non-zero and the contents of R1 are undefined. For a description of the server diretory entry SDE see the section Server DSECTs.

   The value in the SRVEMCB field can be used to obtain the address of the specific service routine.

2. If a user-defined server requires something like session control, you can use the ALLOCATE and DEALLOCATE functions of the CMSRVD macro. These functions branch to the SRVESERV entry point of the user-defined service routine. The expected funtionality of this routine is described in the section Server Request Routine.

   This alternative ensures that Com-plete performs an invocation in cases where the application ends (normal or abnormal) and still has a pending session with a server.

   To acquire a session with a server use the macro:

       CMSRVD ALLOCATE,NAME='serv-id'

   After successfull execution (RF=0), this macro returns the address of the RQE in R1 (see the section Server DSECTs).

   R15 > 0 indicates that the request could not be satisfied and the contents of R1 are unpredictible.

   To free a session with a server, use

       CMSRVD DEALLO,NAME='serv-id', AREA=

   The AREA keyword specifies a register or storage location which contains the address of the RQE provided by the ALLOCATE function.

   The corresponding branch interface function is

       SERVER,(retcode,serv-id,function,area)

   where:

   retcode | required A fullword where Com-plete places the returncode upon completion of the request.
   serv-id | required An eight-byte character field containing the servername (as stored in SRVENAME)
   function | required An eight-byte character field containing QUERY, ALLOCATE or DEALLO
   area | required only for function DEALLO A fullword containing the address of the RQE provided by the ALLOCATE function

   More about the requirements of the branch interface can be found in Application Programming Interface in the Application Programming documentation.

## Server DSECTs

The server directory entry (SDE) is mapped in the DSRVE DSECT, which is generated by the following macro:

    CMSRVD  DDIR,LIST=YES|NO

    DSRVE        DSECT,          SERVER ENTRY
    SRVENAME     DS CL8          NAME
    SRVEINIT     DS CL8          NAME INIT ROUTINE
    SRVEINEP     DS A            EP INIT/TERM ROUTINE

    SERVER DIRECTORY available for server

    SRVEMCB      DS A            A(SERVER CONTROL BLOCK)
                                 ZERO INDICATES NOT UP
    SRVESERV     DS A            A(SERVICE ROUTINE)
                 DS A            ** RESERVED **

    SRVELEN#     EQU *-DSRVE     LEN OF ENTRY

The server request entry (RQE) is mapped in the DSRVE DSECT, which is
generated by the following macro:

    CMSRVD  DRQE,LIST=YES|NO

    DSRVR        DSECT,
    SRVRNAME     DS      CL8     ID
    SRVRLEN DS           F       len of control block
    SRVRNSRV     DS      A       A(next request element)
                                 maintained by Com-plete

    SRVRREQE     DS      A       A(SERVICE ROUTINE)
    SRVRSVFE     DS      A       A(entry for ALLOCATE, DEALLO,
                                 and EOJ function)
                 DS      2A      ** RESERVED **

The default for the LIST keyword is the setting of &CCPRNT (CCGLOBS).

## Server Request Routine

The server request routine is provided in the field SRVESERV of the SDE. The routine is invoked using ALLOCATE, DEALLOC requests via the CMSRVD macro and during EOJ processing for a user session.

Registers upon entry (all calls):

R1 | server directory entry (SDE)
R2 | COMREG
R7 | address of option (ALLOCATE, DEALLOC, EOJ)
R8 | AREA from DEALLOC
RD | 18F save area
RE | return addr (high order bit contains AMODE of caller)
RF | entry point

> ALLOCATE Request

>   The server must allocate a RQE outside the thread. Other server specific functions may also be performed during ALLOCATE processing. If the request was successfully processed R15 must be set to 0 and R1 must contain the address of the RQE.

> DEALLOCATE Request

>   Deallocate processing must be used to free all user-related resources or whatever may be necessary for the server. After return from the server request routine, Com-plete will remove the RQE from its internal chain. This will prevent any cleanup call at session end.

> EOJ Request

>   If an active server session is pending at EOJ processing for a transaction, Com-plete invokes the server request routine for cleanup processing (SRVRSVFE).

>   The option pointed to by R7 on entry indicates the type of transaction end:

>   EOJNORM | normal end of transaction
>   EOJABEND | transaction abended

### On this page

- Overview
- Server Definition
- Server Initialization
- Server Termination
- Server Command Interface
- Server Invocation
- Server DSECTs
- Server Request Routine