This document describes the Com-plete server facility.
This document covers the following topics:
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.
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.
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 |
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). |
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. |
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.
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.) |
The invocation of a user-defined server can be achieved in 2 different ways.
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.
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.
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).
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