DCAM exit (075)

The DCAM exit permits the user to expand and modify DCAM functions and to add special functions. Examples of such functions are:

• data protection facilities over and above those in TRANSDATA by means of more extensive authorization checks; e.g. make the opening of applications dependent on the user ID, permit a connection to be set up for an application only with defined partners or processors

• initiation of additional actions (starting jobs, issuing messages).

The user-specific exit routine is invoked for opening and closing applications and for connection setup and cleardown. When opening applications and setting up connections, the exit routine can accept, reject or, if necessary, modify the call. The calls on closing serve only to provide the exit routine with information.

Exit cases (events)

There are currently 12 exit cases for the DCAM exit routine. A distinction is made between exit main cases and exit subcases, which are identified by means of a sequence of 3 alphabetic characters each. The 6-digit combination of the main case and subcase identifiers uniquely defines the exit case.

The expansion of exit main case and exit subcase in future DCAM versions must be taken into account.

The main cases APP and CON, together with their subcases are compared on the following pages.

Main case APP

This refers to cases concerned with opening and closing applications.

Exit subcase	Exit routine is called	Exit routine functions
APPOPN	on all YOPEN calls, after checking the user specifications prior to processing the call.	additional checks, e.g. applications may be opened by certain users only; load tables dynamically. accept YOPEN call reject YOPEN call modify YOPEN parameters initiate additional actions, e.g. start jobs; output messages etc.
APPCLS	on all YCLOSE calls, prior to clearing down the DCAM data structure.	initiate additional actions; e.g. output messages, update exit-specific tables etc.
APPSHU	on internal closure of an application after the operator has entered the BCEND, BCLOSE or SHUTDOWN command *)
APPRTM	on internal closure of an application when a program or task is terminated	initiate a substitute task
APPFCL	on unexpected closure of an application due to DCAM failure.

*)

The exit is only called on closing and not in the event of any previous warning. The exit is not called if TIAM termination precedes DCAM termination, i.e. if the DCAM program was started as an interactive task. In such a case, task termination will be initiated by TIAM, i.e. the APPTRM exit is called.

Main case CON

This refers to cases concerned with connection setup and cleardown. The exit routine is not called, however, in the case of an implicit cleardown of all existing connections when closing an application.

A distinction is made between the following subcases:

• Request connection setup (YOPNCON ACQUIRE):

  • on YOPNCON ACQUIRE call by user

  • after successful connection setup

• Accept connection request

  • on receipt of a connection setup request

  • after acceptance of the request (YOPNCON ACCEPT)

• In the case of explicit connection cleardown or after a DCAM error.

  • connection cleardown by user

  • connection cleardown forced by breakdown

  • connection cleardown by partner

  Exit subcase	Exit routine is called	Exit routine functions
  CONACQ	on sending a connection setup request (YOPNCON ACQUIRE), after checking user specifications, prior to call processing (i.e. prior to the BCAM call REQCON)	additional checks, e.g. does connection message (LOGON MESSAGE) conform to conventions? accept call reject call modify YOPNCON parameters
  CONACC	on every acceptance of a connection request (YOPNCON ACCEPT), afterverifying user specifications, prior to call processing	additional checks accept request reject request modify YOPNCON parameters
  CONCPL	after a successful connection setup, i.e. if a YOPNCON ACQUIRE request has been accepted by the partner
  CONREQ	on receipt of a connection request, after checking specifications, prior to processing the connection request.	additional checks accept connection request reject connection request
  CONCLS	on every connection cleardown by the user (YCLSCON), prior to release of the DCAM data structure
  CONFCL	on each forced connection cleardown due to an NEA logging error or an acknowledgment overflow
  CONBAD	on each connection cleardown initiated by the partner.

  The following information is passed to the exit routine:

R1 = A(YDDEXPL) = DCAM exit parameter area
R12 = A(TPR program manager)
R13 = A(save area)
R14 = A(indirect return)
R15 = A(exit routine)

The return code for the calling system component is sent via the parameter area in the YDDXRETC field:

YDDXRETC	X'00FDBKRC'
	FDBK =	Exit routine return code for the DCAM user.
	RC =	Exit routine return code for the calling DCAM component. It can have the following values:
		00 accept call
		04 reject call
		08 modify call

The FDBK field must be loaded when RC=04 is set. This specification is transferred to the DCAM user in the FDBK1/ FDBK2 field (see the “DCAM Macros” manual [1]). FDBK can either be taken from the area reserved for the exit routine ’CC00’-’CCFF’ or it can be one of the valid DCAM return codes (see the “System Messages” [15]). FDBK must not be ’0000’. If RC=08 is set, the exit routine stores the data for modification in the YDDEXPL parameter area. Due attention should be paid to the notes on programming exit routines.

With the exit events APPOPN, CONACQ and CONACC, the FDBK field is only passed to the user (equivalent to YOPEN, YOPNCON ACQ and YOPNCON ACC) but is not sent to the partner.

If the system exit of the partner rejects a connection request, the YOPNCON ACQUIRE is terminated with X'0C40' instead of the FDBK specified in that system exit.

DSECT

         YDDEXPL D
YDDEXPL  DSECT
*******************************************************************
*                                                                 *
*    DCAM  EXIT PARAMETERLISTE                                    *
*                                                                 *
*******************************************************************
*
* EINGABEPARAMETER
*
YDDXDPAR DS    A             A(DARPPAR)
*                            DCAM INTERNER ARBEITSBEREICH
YDDXMAIN DS    X             EXIT-MAIN-CASE
YDDXAPPL EQU   1               APPL
YDDXCONN EQU   2               CONN
YDDXSUB DS    X             EXIT-SUB-CASE
YDDXAOPN EQU   1               APPOPN
YDDXACLS EQU   2               APPCLS
YDDXASHU EQU   3               APPSHU
YDDXATRM EQU   4               APPTRM
YDDXAFCL EQU   5               APPFCL
YDDXCACQ EQU   6               CONACQ
YDDXCACC EQU   7               CONACC
YDDXCCPL EQU   8               CONCPL
YDDXCREQ EQU   9               CONREQ
YDDXCCLS EQU   10              CONCLS
YDDXCFCL EQU   11              CONFCL
YDDXCBAD EQU   12              CONBAD
*
* EINGABE-/RUECKGABEPARAMETER
*
YDDXLOGL DS    H             LAENGE DER LOGON MESSAGE
YDDXLOGM DS    CL80          LOGON MESSAGE
*
* RUECKGABEPARAMETER
*
YDDXPW  DS    XL4           PASSWORT
YDDXRETC DS    F             RETURNCODE '..FDBKRC'
*
YDDXL   EQU   *-YDDEXPL     LAENGE DER DCAM EXIT PARAMETERLISTE
               *,YDDEXPL    060    950330   55647211

 

Description of the YDDEXPL fields

YDDXDPAR	A(DARPPAR)
	Address of an internal DCAM work area, via which further call-specific information is passed on to the exit routine.
YDDXMAIN	Indicator for the main case
YDDXMAIN	Indicator for the main case
	YDDXAPPL	main case APP (re: applications)
	YDDXCONN	main case CON (re: connections)
YDDXSUB	Indicator for the subcase
	YDDXAOPN	exit case APPOPN
	YDDXACLS	exit case APPCLS
	YDDXASHU	exit case APPSHU
	YDDXATRM	exit case APPTRM
	YDDXAFCL	exit case APPFCL
	YDDXCACQ	exit case CONACQ
	YDDXCACC	exit case CONACC
	YDDXCCPL	exit case CONCPL
	YDDXCREQ	exit case CONREQ
	YDDXCCLS	exit case CONCLS
	YDDXCFCL	exit case CONFCL
	YDDXCBAD	exit case CONBAD
YDDXLOGL	Length of the connection message (LOGON message) in field YDDXLOGLM. It must not exceed 80 bytes. This field can be modified by the exit routine. YDDXLOGL = 0 means that there is no connection message.
YDDXLOGM	Contains the connection message (LOGON message) which can be modified by the exit routine.
YDDXPW	Contains a password, which the exit routine transfers to DCAM on returning. This password replaces the RDF password specified by the user for YOPEN or the LOGON password for YOPNCON ACQUIRE.
YDDXRETC	Return code of the exit routine.

Notes on programming DCAM exit routines

The following restrictions apply to DCAM exit routines in addition to the rules specified in “Exit routines”:

• All DCAM data structure fields (DARPPAR, control blocks, see below) are read-only. Write access is permitted only for return fields in parameter area YDDEXPL.

• No BCAM calls are permitted.

• The exit routine must not set any bourse locks.

• The exit routine must not change your task (PCB) level.

Excerpt from the DCAM data structure

Those DCAM data structure elements which are of greatest significance with regard to programming exit routines are described below.

Since compatibility for the layout of the DCAM control blocks is not guaranteed, the DCAM data structure can only be accessed via symbolic field names. Recompilation and source changes may prove necessary in the event of a DCAM version change.

Internal DCAM work area

DARPPAR

contains task-specific data, e.g. the current addresses of the DCAM control blocks (cf. the “DCAM Macros” manual [1]).

A DSECT for DARPPAR is generated by the macro:

[name] YDDDVEC D [,prefix]

Default values:	name	YDDDVEC
	prefix	YDDV

DCAM application control block

DACB

contains application-specific data, e.g. application name, attributes,... . The DACB is created on YOPEN and remains in existence until the application is closed.

A DSECT is generated by means of the macro:

[name] YDDDACB D [,prefix]

Default values:	name	YDDDACB
	prefix	YDDH

DCAM connection control block

DCCB

contains connection-specific data, e.g. partner name, processor name. One DCCB is set up for each connection.

A DSECT is generated by means of the macro:

[name] YDDDCCB D [,prefix]

Default values:	name	YDDDCCB
	prefix	YDDL

DCAM request parameter block

DRPB

contains the call-specific information from the RPB in the case of asynchronous calls.

A DSECT is generated by means of the macro:

[name] YDDDRPB D [,prefix]

Default values:	name	YDDDRPB
	prefix	YDDD

Field contents when calling exit routines

The contents of the fields of the exit parameter area and of the internal work area shown in the following table are dependent on the exit case. Fields and addresses which are not set have the default value X’00’.

YDDEXPL - exit parameter area

Field name

Field contents

Exit Case

APP

CON

OPN

CLS

SHU

TRM

FCL

ACQ

ACC

CPL

REQ

CLS

FCL

BAD

YDDXMAIN

Exit Main Case

x

x

x

x

x

x

x

x

x

x

x

x

YDDXSUB

Exit Sub Case

x

x

x

x

x

x

x

x

x

x

x

x

YDDXDPAR

A(DARPPAR)

x

x

x

x

x

x

x

x

x

x

x

x

YDDXLOGL

L of LOGON Mess.

x

x

x

x

YDDXLOGM

A(LOGON Message)

x

x

x

x

YDDDVEC - internal DCAM work area

Feldname

Feldinhalt

Exit Case

APP

CON

OPN

CLS

SHU

TRM

FCL

ACQ

ACC

CPL

REQ

CLS

FCL

BAD

YDDVXTID

A(TID)

x

x

x

x

x

x

x

x

x

x

x

x

YDDVADAC

A(DACB)

x

x

x

x

x

x

x

x

x

x

x

x

YDDVADCC

A(DCCB)

x

x

x

x

x

YDDVADRP

A(DRPB)

x

x

x

YDDVARPB

A(RPB)

x

x

x

x

YDDVAPCN

A(PCN) *)

x

x

YDDVAPTN

A(PTN) *)

x

x

*)

If the exit is initiated by the CONREQ exit case, there is no connection control bloc(DCCB). The user can obtain information about the partner address by means of YDDVAPTN, but cannot make any modifications.

PCN	CL8	PROCESSOR NAME
PTN	CL8	PARTNER NAME

Return code for the exit routine

For the exit cases APPCLS, APPSHU, APPTRM, APPFCL, CONCPL, CONCLS, CONFCL and CONBAD, the exit routine must set the rightmost byte in the YDDXRETC field to zero (RC = X’00’). These exit cases only pass information to the exit routine; DCAM processing cannot be affected by the exit routine.

In the case of exit cases APPOPN, CONACQ, CONACC and CONREQ, the exit routine can influence DCAM processing via the return code in the YDDXRETC field. The table below shows which return codes can be set.

Return codes (1)

		Condition	Exit Case
			APPOPN	CONACQ	CONACC	CONREQ
YDDXRETC	RC = 00		x	x	x	x
	RC = 04		x	x	x	x
	RC = 08		x	x	x	-
	FDBK	RC = 04	+	+	+	+
YDDEXPL	YDDXPW	RC = 08	*	*	-	-
	YDDXLOGL	RC = 08	-	*	*	-
	YDDXLOGM	YDDXLOGL > 0	-	*	*	-

x: the value/field can be specified
-: the value/field cannot be specified
+: the field must be specified if the condition applies.
*: if RC=08 is set, the field can be modified and returned to DCAM.

Cases marked with an asterisk (*) in the table above are explained in greater detail in the following table:

Return codes (2)

Exit case	Field in YDDEXPL	Modification
APPOPN	YDDXPW	In the event of a BCAM call the RDF password (USEPW parameter in ACB) is replaced by the password transferred. If YDDXPW = 0, the password remains unchanged.
CONACC CONACQ	YDDXLOGL	YDDXLOGL = 0 means the connection message remains unchanged. YDDXLOGL = X' 7FFF' means the connection message is deleted.
CONACC CONACQ	YDDXLOGM	The connection message (LOGON message) of the user (contents of AREA) is replaced by the transferred data prior to the BCAM call.
CONACQ	YDDXPW	The LOGON password (LOGPW parameter in CCB) is replaced prior to the BCAM call by the password transferred. If YDDXPW = X' 00' , the password is not replaced.