The PGWT call (program wait) sets the program unit to an internal wait point without terminating the unit. You can
terminate the processing step without terminating the transaction.
neither terminate the processing step nor the transaction in order to wait for a message at a service-controlled message queue (no previous MPUT permitted).
terminate the transaction. If an MPUT message was sent previously, the processing step is terminated; otherwise, it is continued.
roll back the transaction and continue the processing step.
The program unit is always continued by the same process (process ID remains the same). The PGWT call is comparable to a PEND call followed by an implicit INIT call.
If you enter a value greater than 0 for the parameter KCLI in the KDCS parameter area, then openUTM supplies information about the application, the system and the communication partner. The PGWT call is then comparable to a PEND KP call followed by an implicit INIT PU call.
The following table shows the meaning of the PGWT call and the associated actions:
Variant | Meaning | openUTM actions |
|---|---|---|
PGWT KP | End of processing step without program unit or transaction end; |
|
PGWT PR | Wait without terminating processing step, program unit or transaction; |
|
PGWT CM | Terminate transaction without terminating the program unit; |
|
PGWT RB | Roll back transaction; |
|
Setting the KDCS parameter area (1st parameter)
Function of the call | Entries in the KDCS parameter area | ||
|---|---|---|---|
KCOP | KCOM | KCLI | |
Terminate processing step without end of program unit or transaction | "PGWT" | "KP" | 0 / Length of the message area |
Wait without terminating processing step and transaction | "PGWT" | "PR" | 0 / Length of the message area |
Terminate transaction without end of program unit | "PGWT" | "CM" | 0 / Length of the message area |
Roll back transaction and continue processing step | "PGWT" | "RB" | 0 / Length of the message area |
Setting the 2nd parameter (only necessary if KCLI > 0)
Here you enter the address of the message area into which openUTM is to write the requested information. To structure the message area you can use the same data structure as for the INIT PU call, i.e. the KCINIC COPY element for COBOL, the kcini.h. include file for C/C++.
In the header of the data structure, you specify the version number of the structure and select which information openUTM is to supply.
For a detailed description of the data structure, see the INIT PU call, "INIT Initialize program unit".
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"PGWT" | |
"KP"/"PR"/"CM"/"RB" | |
0/Length in bytes | |
Setting the header of the message area | |
Field name in message area | Contents |
Version number (7) | |
Request date and time (Y/N) | |
Request application information (Y/N) | |
Request Locale information (Y/N) | |
Request OSI TP information (Y/N) | |
Request encryption information (Y/N) | |
Request miscellaneous information (Y/N) | |
| KCHTTP/http_info | Request HTTP information (Y/N) |
KDCS call | |
KDCS parameter area | Message area (only necessary if KCLI > 0) |
C/C++ macro calls | |
Parameters | |
KDCS_PGWTKP | ( ) |
KDCS_PGWTKP_PU / KDCS_PGWTPR/ | (nb,kcli) |
openUTM return information | |
|---|---|
Contents | |
Data (only if KCLI > 0) | |
Field name in KB return area | |
Length of transferred data (only if KCLI > 0) | |
Return code | |
Internal return code | |
Format identifier/blanks | |
Service ID/Rollback ID/blanks | |
For the PGWT call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, enter the "PGWT" operation name.
KCOM
In the KCOM field, the variant of the PGWT call:
KP: End of processing step without transaction end
PR: Wait without terminating the processing step and transaction
CM: End of the transaction
RB: Rollback of the transaction
KCLI
in the KCLI field, enter the length of the message area to which openUTM is to transfer the information. Enter the length in bytes. The value entered in KCLI specifies the maximum number of bytes of information that openUTM transfers to the message area.
If KCLI is greater than zero, then you must specify the address of the message area in the 2nd parameter when you call PGWT. The information is equivalent to that for the INIT PU call.
All unused fields of the parameter area must contain binary zero.
Setting the header of the message area (only necessary if KCLI > 0):
KCVER/if_ver
In the KCVER/if_ver field, enter the version number of the data structure. The current version is version 7.
KCDATE/dattim_info
Enter Y in the KCDATE/dattim_info field if you want information on the date and time of the start of the application and the program unit run, otherwise enter N.
KCAPPL/appl_info
Enter Y in the KCAPPL/appl_info field if you want to request information about the application, system and communication partner, otherwise enter N.
KCLOCALE/locale_info
Enter Y in the KCLOCALE/locale_info field if you to want to request information about the language environment of the LTERM partner, otherwise enter N.
KCOSITP/ositp_info
Enter Y in the KCOSITP/ositp_info field if you require OSI TP-specific information, otherwise enter N.
KCENCR/encr_info
Enter Y in the KCENCR/encr_info field if you require information about the encryption methods used between the client and the UTM application, otherwise enter N. (The encryption mechanism can be coordinated. See the openUTM manual “Generating Applications”.)
KCMISC/misc_info
Enter Y in the KCMISC/misc_info field if you require miscellaneous information (e.g. number of queued messages in the user’s queue, password validity, time of last signon), otherwise enter N.
KCHTTP/http_info
Enter Y in the KCHTTP/http_info field if you require HTTP specific information, otherwise enter N.
You specify the following for the KDCS call:
1st parameter
The address of the KDCS parameter area.
2nd parameter
(only necessary if KCLI is not equal to 0): The address of the message area to which openUTM is to write information. For return information you can use the KCINIC data structure in COBOL and the kcini.h include file in C/C++ (description see "INIT Initialize program unit").
Macro names
The use of C/C++ macro calls is described in detail in the section "C/C++ macro interface".
openUTM returns:
Message area
only if KCLI > 0:
in the message area, the information in its actual length, up to a maximum length of the value specified in KCLI. The data supplied by the PGWT call corresponds to the return information of the INIT PU call and is described on "INIT Initialize program unit".
KCRLM
only if KCLI > 0:
in the KCRLM field, the length of the information actually transferred by openUTM, provided that KCRCCC = 000. In the case of 07Z, KCRLM contains the length of data which is totally available. If KCRCCC >= 40Z then KCRLM = 0.
KCRCCC
in the KCRCCC field, the KDCS return code (length 3 bytes). For possible return codes and their meaning, see below.
KCRCDC
in the KCRCDC field, the internal return code of openUTM (see openUTM manual ”Messages, Debugging and Diagnostics”).
KCRMF/kcrfn
only for PGWT CM with preceding MPUT and PGWT KP (similar to the INIT call):
for a message from a terminal:
Blanks (in line mode) or the format name (in format mode) of the last screen output, i.e. the name specified in the KCMF/kcfn field with the MPUT of the last dialog step. If the last output consisted of multiple partial formats, KCRMF/kcrfn contains the name of the first partial format into which data was entered. If no data was entered in any of the partial formats, KCRMF/kcrfn contains the name of the first partial format.
Only on BS2000 systems: If an edit profile was used in the last screen output, KCRMF/kcrfn contains this edit profile.
for a message from a TS application: Blanks
for a message from a LU6.1 partner or a UPIC client:
The format identifier of the first message segment specified by the LU6.1 partner or UPIC client on sending
Particularity in the LU6.1 job submitting service:Blanks blanks if a status flag exists for the service ID specified in KCRPI.
for distributed processing via OSI TP:
If the program unit run was started because of a distributed dialog, KCRMF/kcrfn in the job-submitting service contains the name of the abstract syntax which was allocated to the message by the job submitter; if the field contains blanks, the UTD syntax is selected as the abstract syntax.
In the job-receiving service, KCRMF/kcrfn contains the name of the abstract syntax which was allocated to the message by the job-receiving service described in KCRPI. If the field contains blanks, the UTD syntax is selected as the abstract syntax or an error message from the partner is present.
KCRPI
only for PGWT CM with preceding MPUT and PGWT KP (similar to the INIT call):
For a message from a LTERM partner: blanks.
In the job-submitting service with distributed processing:
the service ID of the job-receiving service if a message from the job receiver exists.In the job-receiving service with distributed processing:
blanks
KDCS return codes in the KCRCCC field for the PGWT call
The following codes can be analyzed in the program:
000 | Operation carried out successfully. If a message area was specified for the call (KCLI > 0), the requested information was transferred to the message area in its full length. |
07Z | Function was executed, the available message area is too short (Length in KCLI insufficient). No or incomplete information was returned. |
40Z | For PGWT CM: The function was not executed. An error that does not permit continuation of the current transaction has occurred. The transaction is rolled back implicitly with PGWT RB. |
48Z | Only when KCLI is greater than zero: Invalid data structure version. |
Additional return codes can be found in the dump:
70Z | The PGWT operation could not be performed (system or generation error, deadlock, timeout). |
71Z | In this program no INIT has yet been issued or the call was issued by an MSGTAC program. |
72Z | Entry in KCOM is invalid or KCOM = CM/RB was specified and a partner communicating with the LU6.1 protocol is involved in the current distributed transaction. |
77Z | The address of the message area specified when the call was issued is invalid. |
82Z | An MPUT was issued to a program unit run before a PGWT KP. |
83Z | The program unit did not issue an MPUT before a PGWT KP or an MPUT was issued before a PGWT PR. |
87Z | The PGWT call conflicts with the transaction or service status. |
88Z | Interface version of the data structure (for KCLI > 0) is invalid. |
89Z | When the function was called, unused parameters were not set to binary zero. |
Features of the PGWT call
Any messages or message segments which are held by openUTM for the program following INIT and which are not read by the program using MGET are lost.
PGWT KP and PR
A PGWT KP call corresponds to a PEND KP with a following INIT/INIT PU. PGWT KP is always allowed, if a PEND KP call is allowed.
A PGWT PR call corresponds to a PEND PA/PR with a following INIT/INIT PU. PGWT PR is meaningful only if preceded by a DGET call with wait and if it is necessary to wait for a message for the specified queue. After PGWT PR the program waits until a message arrives for this queue.
PGWT KP and PR do not produce a synchronization point! Dialog messages initiated by MPUT for PGWT KP calls are output. The remaining output operations LPUT, FPUT, SPUT, PTDA and the release action SREL remain stored until the next synchronization point.
PGWT KP and PR lock resources (LSSBs, GSSBs, TLS, ULS, and possibly database areas) outside the processing dialog step. Calls from other transactions (SGET, SPUT, SREL, PTDA or GTDA) that wish to access these resources are rejected with a return code (40Z and KCRCDC code). Therefore, it is recommended when using PGWT KP/PR to first allocate the global resources before use, and to release them again immediately afterwards.
If a DB transaction began prior to a PGWT KP or PR, this transaction is not terminated! The transaction is only terminated if a PEND RE, SP, FI, FC or a PGWT CM call is issued. RSET, PEND, RS FR, ER or PGWT RB roll back the transaction.
If the transaction is rolled back then any MPUT output to be performed by a PGWT 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.
PGWT CM and RB
PGWT CM with an MPUT message is always allowed whenever a PEND RE is allowed. PGWT CM then corresponds to PEND RE with a following INIT/INIT PU.
PGWT CM without an MPUT message is always allowed whenever a PEND SP is allowed. PGWT CM then corresponds to PEND SP with a following INIT/INIT PU.
PGWT CM sets a synchronization point while preserving the program context. With regard to database transactions PGWT CM behaves in the same way as PEND SP or PEND RE.
PGWT CM and PGWT RB are not allowed if the LU6.1 protocol is used for communication with a partner in the current transaction.
PGWT RB rolls back the transaction. In contrast to RSET or PEND RS the program context is preserved. The program context includes, for example, the KB program area, SPAB and local data areas.
No rollback message may be generated before PGWT RB.
No service restart is possible at a synchronization point set using PGWT CM. The follow-up transaction can therefore be rolled back only with PGWT RB without terminating the abnormal service.
If the PGWT call cannot be executed successfully, openUTM calls PEND ER internally.
Continuation of processing
After a PGWT KP call or a PGWT CM call with MPUT a return is made to the calling program as soon as all responses are available.
Processing is continued immediately after a PGWT CM without MPUT and after a PGWT RB, exception see distributed processing with OSI TP on "PGWT Set wait point in program without terminating program unit".
After a PGWT PR call processing is continued as soon as a message arrives in the queue. A DGET call must be used to read such messages.
PGWT call in a distributed OSI TP service with Commit
If the Commit functionality was selected with distributed processing via OSI TP, PGWT CM without MPUT and PGWT RB always result in a wait point, i.e.:
for PGWT CM without MPUT, processing is not continued until the transaction end has been confirmed by all partners or the transaction has been rolled back, e.g. due to an error.
for PGWT RB, processing is not continued until rollback has been confirmed by all partners.
A return is also made to the program unit if
for an PGWT KP call, a situation is detected which makes it impossible to commit the transaction.
for a PGWT CM or RB call, the current transaction was committed or rolled back and the present situation does not allow the current transaction or the follow-up transaction to be committed.
This situation is indicated to the program via the KCTARB field in the KB header:
KCTARB
In an TP service this indicates whether a situation has occurred which makes it necessary to roll back the transaction.
Blanks | No situation has occurred which makes it necessary to roll back the transaction. |
Y | A situation has occurred which makes it impossible to commit the transaction. Communication with partner services is still permitted. A call to commit the transaction results in an abnormal end of service. |