RESYNC ENTRYNAME

Determine the disposition of in doubt units of work.

Syntax

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

RESYNC ENTRYNAME

Conditions: NOTAUTH

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations.

This command is threadsafe.

Description

The RESYNC command allows a non-CICS® resource manager to determine whether units of work about which it is in doubt were committed or backed out.

A resource manager can be in doubt about a unit of work if it has been invoked for the first phase of syncpoint, but not for the second. A failure of either the resource manager or CICS between Phase 1 and Phase 2 leaves the resource manager in doubt about that unit of work.

CICS saves or reconstructs the disposition of any such unit of work until a RESYNC command or an initial start. CICS also saves the disposition of any unit of work about which the resource manager replies remember to the second-phase syncpoint invocation, so that if the resource manager cannot commit or roll back as directed, it can request the disposition later for recovery.

To use the saved disposition information, the resource manager must have a record of which units of work are in doubt or remembered. It can then issue a RESYNC command with a list of these units of work, either in its task-related user exit program or an associated administrative transaction.

In response, CICS creates a task, CRSY, for each indoubt unit of work in the list. The CRSY task invokes the task-related user exit program once on behalf of its particular unit of work. This invocation is identified to the exit as a phase 2 syncpoint request and as such indicates whether the unit of work was committed or rolled back. The exit program can then relay this information in the form the resource manager requires.

If the resource manager does not want to resynchronize all indoubt units of work at once, it should specify PARTIAL on the RESYNC command. If it does not, CICS discards disposition information for all the indoubt units of work that are not in the supplied list, but are part of the resource manager's resynchronization set.

Note: A resource manager's resynchronization set is initialized when its task-related user exit is first enabled. It is used when the first non-partial RESYNC command is issued. On completion of the non-partial RESYNC, a new resynchronization set is initialized, for use with the next non-partial RESYNC.

A resource manager is identified by the name of its task-related user exit and, optionally, a qualifier to this name. Use of a qualifier allows multiple instances of the same resource manager to resynchronize independently.

Control is returned to the program that issued the RESYNC command as soon as the CRSY tasks have been scheduled. They run asynchronously, in parallel, according to normal CICS dispatch rules. Consequently, the exit should be enabled, started, and initialized to the point where it can process these invocations before the RESYNC command.

If the exit is not available, a CRSY task will save the disposition of its unit of work, but since this occurs later in time, no exceptional condition occurs on the RESYNC. See Writing a task-related user exit program for full details about resynchronization invocations of task-related user exits.

If CICS fails for some reason, or an immediate shutdown is performed, the forget flow log records that are written in response to a committed flow being returned from an external resource manager are lost. This is because anything other than a controlled CICS shutdown does not call the MVS logger to force the log records onto the logstream. This can lead to units of work being rebuilt on a subsequent emergency restart of CICS, if their links to the external resource managers were not seen to be forgettable at the time of the restart. To allow CICS to discard such units of work, the external resource manager can issue an EXEC CICS RESYNC command to CICS when it reconnects after the CICS system is restarted. Any units of work that are not passed on the command are treated as no longer required by CICS.

Options

ENTRYNAME(data-value): specifies the 8-character name of the task-related user exit for the resource manager. This is the ENTRYNAME value of the ENABLE command that established the exit, or, if ENTRYNAME was omitted, the PROGRAM value.
IDLIST(data-value): specifies the list of units of work to be resynchronized. Each entry in the list is the address of the 8-byte identifier of an indoubt unit of work. The end of the list may be indicated by the high-order bit turned on, or IDLISTLENGTH may be used.
Units of work are identified by the UEPURID value passed to the task-related user exit.

Note: IDLIST is optional, but if you omit it, CICS discards all of the saved disposition information for the resource manager, unless you specify PARTIAL. Not specifying a list and specifying PARTIAL is an illogical combination and results in a NO-OP.
IDLISTLENGTH(data-value): specifies a halfword binary value indicating the length (in bytes, counting 4 bytes per indoubt unit of work) of the address-list.
PARTIAL: specifies that CICS is to retain indoubt resolution data for the UOWs (for this resource manager) that are not passed in the indoubt list. PARTIAL indicates that, at this time, the resource manager wants to resynchronize only a subset of the UOWs about which it is in doubt.
If PARTIAL is not specified, CICS discards resolution data for any UOWs not passed in the indoubt list, but which are part of this resource manager's resynchronization set.
Note: A resource manager's resynchronization set is initialized when its task-related user exit is first enabled. It is used when the first non-partial RESYNC command is issued. On completion of the non-partial RESYNC, a new resynchronization set is initialized, for use with the next non-partial RESYNC.
This includes data for UOWs that CICS itself is in doubt about.

A task-related user exit program can issue multiple partial resyncs during the lifetime of a connection with its external resource manager. However, it should issue only one full (that is, non-partial) resync during the lifetime of a connection. This is typically done when the connection is first established. Full resyncs imply deletion of UOWs not mentioned in the IDLIST. Only when the external resource manager is not connected to CICS can it be sure that it has a complete list of UOWs to pass to CICS.
QUALIFIER(data-value): specifies an 8-character qualifier to the ENTRYNAME value, which identifies the particular instance of the resource manager to which the RESYNC command applies. The qualifier is optional; it is intended for systems where more than one copy of a resource manager can be in use.
When it is in use, this value is assigned to a unit of work by the task-related user exit at the time the unit of work takes place, via the UEPRMQUA value in the user exit parameter list. If the RESYNC command specifies a qualifier, CICS uses only disposition information saved with the same QUALIFIER and ENTRYNAME values. Similarly, it discards saved dispositions only if they have the same two values, were not included in the IDLIST, and PARTIAL was not specified.

Conditions

NOTAUTH

RESP2 values:

100: The user associated with the issuing task is not authorized to use this command.