PEND Terminate program unit

You use the PEND (program end) call to terminate a program unit. All UTM program units, including the event services (BADTACS, MSGTAC, SIGNON) must be exited via the PEND call (exception: event exits). Depending on the type of program involved one of the variants of the PEND call is used.

With distributed processing, the PEND calls of job-submitting services and job-receiving services have to be matched, see also chapter "Program structure in distributed processing".

The abbreviations in the KCOM field are derived from the following terms:

PS	program and sign(on)
PA/PR	program
KP	keep
RE	return
SP	synchronization point
FI	finish
FC	finish and continue
RS	roll back
ER	error
FR	finish and roll back

Setting the KDCS parameter area (1st parameter)

The table below shows the various options and the necessary entries in the KDCS parameter area.

Function of the call	Entries in the KDCS parameter area
	KCOP	KCOM	KCRN
Continue sign-on service after authorization check in follow-up program unit	"PEND"	"PS"	TAC of the follow-up program unit
Continue processing step in the follow-up program unit	"PEND"	"PA"/"PR"	TAC of the follow-up program unit
Terminate processing step without terminating trans.	"PEND"	"KP"	TAC of the follow-up program unit
Terminate processing step and transaction	"PEND"	"RE"	TAC of the follow-up program unit
Terminate transaction; continue processing step	"PEND"	"SP"	TAC of the follow-up program unit
Terminate processing step, transaction and service	"PEND"	"FI"	—
Terminate transaction and service; continue proc. step in concatenated service	"PEND"	"FC"	TAC of the follow-up program unit
Roll back transaction	"PEND"	"RS"	Blanks
Abort service, roll back the transaction, request dump and restart the application program	"PEND"	"ER"	—
Abort service and roll back the transaction no dump and no application program restart	"PEND"	"FR"	Blanks

If KCOM = PS/FC/SP/RS, all fields not used in the KDCS parameter area must be set to binary zero.

Setting the parameters
Field name in the KDCS parameter area	Contents
KCOP	"PEND"
KCOM	"PS"/"PA"/"PR"/"KP"/"RE"/"FI"/"FC"/"RS"/"ER"/"FR"/"SP"
KCRN	Follow-up transaction code/blank/—

KDCS call
1st parameter	2nd parameter
KDCS parameter area	—

C/C++ macro calls
Macro names	Parameters
KDCS_PENDER/KDCS_PENDFI/KDCS_PENDFR/KDCS_PENDRS	()
KDCS_PENDFC/KDCS_PENDKP/KDCS_PENDPA/KDCS_PENDPR/KDCS_PENDPS/KDCS_PENDRE/KDCS_PENDSP	(kcrn)

openUTM return information
Field name in the KB return area	Contents
KCRCCC	Return code
KCRCDC	Internal return code

For the PEND call you make the following entries in the KDCS parameter area:

KCOP

In the KCOP field, the PEND operation code.

KCOM

In the KCOM field, the PEND call variants:

• PS: continuation of the sign-on service in a follow-up program

• PR/PA: continuation of the processing step in a follow-up program

• KP: end of the dialog step without transaction end

• RE: end of the dialog step with transaction end

• SP: end of transaction; continuation of the processing step in a follow-up program

• FI: end of service

• FC: end of service with concatenation of services

• RS: transaction rollback (with subsequent service restart if synchronization point exists)

• ER: end of service because of error; the service is terminated abnormally, the transaction is rolled back and a dump is written

• FR: end of service because of error. The service is terminated abnormally, the transaction is rolled back (without dump).

KCRN

In the KCRN field, according to variant

• for PEND KP/RE:
  the TAC of the follow-up program unit in which processing should be continued after receiving the next input message.

• for PEND PA/PR/PS/SP:
  the TAC of the follow-up program unit in which processing of the same step should be continued.

• for PEND RS/FR:
  blanks

• for PEND ER/FI:
  irrelevant.

You specify the following for the KDCS call:

1st parameter

The address of the KDCS parameter area.

Macro names

The use of C/C++ calls is described in detail in the section "C/C++ macro interface".

openUTM returns:

KCRCCC

in the KCRCCC field: the KDCS return code, see below.

KCRCDC

in the KCRCDC field: the internal return code of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).

KDCS return codes in the KCRCCC field for the PEND call

These error codes can only to be found in the dump:

000	Operation carried out (with requested PEND ER).
70Z	Operation PEND cannot be performed (system or generation error, deadlock, timeout), see KCRCDC.
71Z	No INIT entered in this program unit run.
72Z	KCOM contains an invalid operation modifier in a call in the MSGTAC program in the sign-on service outside of the sign-on service in the server service in the asynchronous service or the operation modifier conflicts with the database transaction the communication protocol used the status of the sign-on service waiting for a DGET message
74Z	the KCRN field contains a value that is not a TAC or a follow-up TAC the user is not authorized to use the TAC a switch between a dialog TAC and an asynchronous TAC is pending a switch between program units with KDCS API and X/OPEN API is pending KCRN does not contain SPACES in a PEND RS,FR when waiting for a DGET message, the TAC specified in KCRN is not in a TAC class
81Z	KCRN entry in PEND PA/PR/FC/SP/PS (TAC of the follow-up program) conflicts with KCRN in MPUT (e.g. MPUT TAC 1 and PEND xx TAC2).
82Z	KCOM or KCRN entry in PEND conflicts with entries in the preceding MPUT: MPUT with KCRN=blanks for PEND PA/PR/PS/FC MPUT with KCRN=TAC for PEND KP/RE/FI/ER/FR MPUT with KCRN=rollback ID and no PEND RS MPUT with KCRN=service ID for PEND PA/PR/FI/ER/FR. MPUT with KCRN=blanks to an HTTP client and no PEND FI
83Z	A MPUT call is missing: a dialog program did not issue an MPUT prior to a PEND KP/RE/FI/ER/FR no rollback message was sent with MPUT RM prior to a PEND RS in a follow-up transaction no MPUT PM issued prior to a program unit terminated with PEND FI in a sign-on service with service restart.
86Z	Missing KDCS call in message queuing: job complex not terminated at the time of PEND call no job associated with DPUT NI call generated no asynchronous job sent to a service addressed with APRO AM.
87Z	PEND call conflicts with transaction or service status of a remote service.
89Z	Contents of fields not used in the KDCS parameter area are not equal to binary zero (only if KCOM = PS/FC/RS/SP).

The table below shows the PEND variants and the associated actions.

Variants	Meaning	openUTM actions
PS	Sign-on service to be continued in follow-up program No synchronization point	Checks authorization data Possibly executes intermediate dialog to query password/ID card information. Provides this program unit’s MPUT for the follow-up program unit or saves it in the page pool if an intermediate dialog is required. Takes over the follow-up program unit’s TAC from the KCRN field and starts the follow-up program either immediately or on termination of the intermediate dialog.
PA or PR	Processing step to be continued in the follow-up program The transaction remains open No synchronization point	Provides MPUT of this program unit to the follow-up program Takes TAC of the follow-up program from the KCRN field. When TAC class control is used the follow-up program unit is started immediately if it belongs to the same TAC class, otherwise it is started with delay. If a DGET message is to be waited for, openUTM does not start the follow-up program unit until a message arrives for this queue or is placed back in the queue (redelivery) or if the maximum wait time has expired or if the queue was deleted (see DGET call).
SP	Termination of transaction. However, processing step should be continued in the next program unit. Synchronization point!	Closes DB transaction Executes DPUT, FPUT, LPUT, PTDA, SPUT and SREL of the transaction. Deletes the FGET message in the first transaction of an asynchronous service. Deletes messages processed with DGET from their queues. Executes MPUT of this program unit Takes TAC of the follow-up program from KCRN field. When TAC class control is used the follow-up program unit is started immediately if it belongs to the same TAC class, otherwise it is started with delay.
KP	End of the processing step without terminating the transaction. It is to be continued in the next processing step. No synchronization point	Executes MPUT of this program unit (if necessary formats message). If necessary, takes data in KB and transfers it to the follow-up program as soon as it is initialized. Takes TAC of the follow-up program from KCRN field and starts follow-up program as soon as the next message arrives.
RE	End of a processing step and simultaneous end of the transaction. The service is to be continued in a follow-up program. Synchronization point	Closes DB transaction. Executes DPUT, FPUT, LPUT, PTDA, SPUT and SREL of the transaction. Deletes the FGET message in the first transaction of an asynchronous service. Deletes messages processed with DGET from their queues. Executes MPUT of this program unit (formats message if necessary). Releases resources. Takes TAC of the follow-up program unit from KCRN field and starts follow-up program unit as soon as the next message arrives. If necessary, fetches data from KB and transfers it to the follow-up program unit as soon as it is initialized.
FI	End of service and end of the transaction. Synchronization point!	Closes DB transaction. Executes DPUT, FPUT, LPUT, PTDA, SPUT and SREL (for GSSB) of the transaction. Deletes the FGET message in the first transaction of an asynchronous service. Deletes messages processed with DGET from their queues. Releases LSSBs of the service. Executes MPUT of this program unit (formats message if necessary). Releases resources
FC	End of service and end of the transaction, the processing step is to be continued in the concatenated service Synchronization point!	Closes DB transaction. Executes DPUT, FPUT, LPUT, PTDA, SPUT and SREL (for GSSB) of the transaction. Deletes messages processed with DGET from their queues. Releases LSSBs of the service. Transfers MPUT of this program unit to the first program unit of the concatenated service. Releases resources
RS	Roll back a transaction to the last synchronization point	In the first transaction of a service: Rolls back UTM and DB transaction Terminates service (with message K034 to the client). only for terminals and TS applications: Outputs last output message of the preceding service (if available). Restart asynchronous services and follow-up services (if chained services are used) following a rollback. In a follow-up transaction of service: Rolls back UTM and DB transaction to the last synchronization point and, if necessary, restarts screen with message K034. Starts the program unit addressed at the last synchronization point. Transfers rollback message to this program unit. For all the transactions in a service: Messages processed with DGET can be processed again if the maximum number of redeliveries specified in the generation has not yet been reached. Otherwise they are deleted or, in the case of TAC queue messages, may be saved in the dead letter queue. If PGWT calls are allowed for the current TAC and the PEND RS was not called by the program unit: Restarts application program
ER (ERror)	End of service with dump and restart of the application program Rollback to last synchronization point (exception: MPUT)	Writes the UTM dump. Rolls back the UTM and DB transaction. Messages processed with DGET can be processed again if the maximum number of redeliveries specified in the generation has not yet been reached. Otherwise they are deleted or, in the case of TAC queue messages, may be saved in the dead letter queue. In the first transaction of an asynchronous service: The FGET message can be processed again if the maximum number of redeliveries specified in the generation has not yet been reached. Otherwise it is deleted or may be saved in the dead letter queue. Causes dump of the application program. Executes MPUT of this program unit (formats message if necessary) Restarts application program. Releases resources.
FR	End of service, no dump, the application program remains loaded Rollback to last synchronization point (exception: MPUT)	Rolls back the UTM and DB transaction. Messages processed with DGET can be processed again if the maximum number of redeliveries specified in the generation has not yet been reached. Otherwise they are deleted or, in the case of TAC queue messages, may be saved in the dead letter queue. In the first transaction of an asynchronous service: The FGET message can be processed again if the maximum number of redeliveries specified in the generation has not yet been reached. Otherwise it is deleted or may be saved in the dead letter queue. Executes MPUT of this program unit (formats message if necessary) Releases resources.

Features of the PEND call

• Following a PEND, no branch is made back to the calling program. Thus, the KDCS return code cannot be evaluated there.

• In case of error, if PEND executes abnormally, openUTM calls PEND ER internally.

• • With dialog processing, an error message is sent to the client. The transaction is rolled back and the service is terminated. A new service can be started.

  • An asynchronous service is aborted and a message is written to the system log file SYSLOG.

• If another call led to a KDCS return code >= 70Z, openUTM calls PEND ER internally.

• If a program unit calls PEND ER/FR in a dialog service, you must first use MPUT to send a message to the client or the job-submitting service - with one exception: This does not apply to a OSI TP job-submitting service for which KCSEND contains the value "N". If openUTM calls PEND ER internally (KCRCCC >= 70Z), a default message is issued. However, if a separate error message was created by means of MPUT ES in communication with the UPIC client, this error message is sent to the UPIC client instead.

• A rollback message has to be sent with MPUT RM prior to a PEND RS call in a follow-up transaction. Thus a PEND RS should not be issued in the first transaction of a service otherwise no rollback message can be read. Unlike PEND ER, PEND RS does not cause a dump to be written.

• If the PEND RS call is used for communication with a UPIC client, you must note the following:
  If the preceding transaction was terminated with PEND SP or PEND FC, then the local transaction is rolled back and the service with the follow-up program unit specified in PEND SP or PEND FC continues execution when PEND RS is called.(local service restart) 
  If the preceding transaction was not terminated with PEND SP/FC and the service is running under a user ID with the restart property, then the service is rolled back to the last synchronization point and the dialog with the UPIC client is terminated. A new 
  OSI TP dialog can be started under the user ID and the service restart requested.
  In all other cases, openUTM terminates the service with PEND FR.

• If PEND RS is used for distributed processing via the OSI TP protocol without commit functionality, you must note the following:

• • if called in a job-receiving service:
    If the preceding transaction was terminated with PEND SP, then the local transaction is rolled back and the service with the follow-up program unit specified in PEND SP continues execution when PEND RS is called (local service restart). If the preceding transaction was not terminated with PEND SP and the service is running under a user ID with the restart property, then the service is rolled back to the last synchronization point and the dialog with the UPIC client is terminated. A new OSI TP dialog can be started under the user ID and the service restart requested.
    In all other cases, openUTM terminates the service with PEND FR.

  • if called in a job-submitting service, all job-receiving services of this service are terminated using PEND FR.

• If a PEND RS call is issued in a transaction previously terminated with PGWT CM, the service is terminated with PEND FR.

• Any messages or message segments which openUTM maintained for the program following INIT, but which were not read in the program with MGET or FGET, are lost with PEND (likewise with PEND PA or PR).
  The same applies when no all of a DGET message is read: the remaining parts of the message that were not read are lost.

• If a DB transaction was terminated prior to a PEND RE/SP/FI/FC, execution is delayed until PEND RE/SP/FI/FC.

• PEND KP locks resources (LSSBs, GSSBs, TLS, ULS and, if applicable, database areas) beyond a dialog step.
  Except in the case of distributed processing, it is therefore advisable

• • to use the PEND KP sparingly in order to keep global resource occupancy times short

  • not to reserve the global resources until the final dialog step when using PEND KP.

• If the transaction is rolled back then any MPUT output to be performed by a PEND KP is lost. The service is rolled back to the last synchronization point. A service restart is performed immediately provided that the user is still signed on.

  If the user is signed off, e.g. because the connection to the client has been lost, then a service restart is performed when the user signs on provided that the user ID (in applications without user IDs, the LTERM partner) has been generated with the restart property (generation operand RESTART=YES in the LTERM or USER statement, see openUTM manual “Generating Applications”).
  Following the end of an application then, in the case of standalone UTM applications, a service restart is only possible in UTM-S applications.

• PEND SP is only permitted in distributed processing via LU6.1 if no partner services with open transactions are available.

• If a message to an HTTP client has been issued, the service has to be terminated with PEND FI because a service for an HTTP client may only consist of one dialogue step.

• A PEND PA/PR or SP can cause a task switch in a dialog or asynchronous service if the follow-up program unit is in a different TAC class than the program unit run calling PEND (see the openUTM manual “Generating Applications”, TAC classes), or if the application was generated with the TAC-PRIORITIES statement.

• A PEND PS call may only be specified in the sign-on service and only if the status of the sign-on service allows this.

• If the PEND PA/PR or PS call is executed without calling MPUT beforehand in the signon service for a UPIC client after receiving a message from the client, then the follow-up program unit can still read unread message (segments) from the UPIC client.

• PEND FC terminates the UTM service, but not the UPIC conversation.If the PEND PA/PR or PS call is executed without calling MPUT beforehand in the signon service for a UPIC client after receiving a message from the client, then the follow-up program unit can still read unread message (segments) from the UPIC client. In this case the first program unit of the chained service receives the value F (first), and not C (chained) as its service indicator in the KBKOPF because it contains a message from the client.

• If an asynchronous service or a follow-up service concatenated with PEND FC is interrupted during the first transaction, then openUTM restarts the service.

• Program unit runs in asynchronous services can only use PEND KP and RE if they have previously supplied a message for a job-receiving service with MPUT.

• Note that, if PEND ER/FR is called in the job-receiving service, you cannot send a message to the job-submitting service (as with PEND ER/FR to the terminal). Nevertheless, you have to issue an MPUT call before a PEND ER/FR as otherwise openUTM terminates the service. The job-submitting service then receives status information with service status Z (instead of E).

• When using distributed processing, you have to take account of the service and transaction status of the partner when calling PEND. For further information see chapter "Program structure in distributed processing".

• If a DGET message is to be waited for, PEND PA/PR or PGWT PT must follow.