Overview of the ARCSPVS API

You can use the ARCSPVS API to define the virtual storage areas that you want AR/CTL to save during checkpoint processing and to restore automatically during initialization processing or manually on demand. You can define these areas in addition to the user areas that you can define with checkpoint (CHKP) and restart (XRST) calls. You can think of the API as a technique that complements the standard checkpoint/restart technique for managing user areas.

The ARCSPVS API works in all AR/CTL restartable environments and supports both IMS and non IMS programs.

Virtual storage areas

A virtual storage area is defined by the beginning address of the area and the delimiter of the area, which is the address of the end of the area and is not included in the area itself. Subtracting the beginning address from the delimiter provides the length of the area. Defined virtual storage areas may not overlap.

The definition of the virtual storage area persists until you explicitly delete the area (by using the Delete function of the ARCSPVS API) or the job step is cold-started. The name of each virtual storage area must be unique within a job step while the area remains defined.

Checkpoint data set

AR/CTL stores the defined virtual storage areas in the checkpoint data set with other checkpoint data. The ARCSPVS API supports an unlimited number of virtual storage areas in the application program. The amount of available space in the checkpoint data set is the only limitation on the size and number of the virtual storage areas that you can define.

Before you implement the ARCSPVS API for an application program, verify that space allocation parameters for the checkpoint data set are large enough to provide sufficient space for the virtual storage areas to be managed. For more information, see Setting-up-dynamic-allocation-options.

ARCSPVS API structures and functions

The ARCSPVS API is simple to implement in the application program. The API consists of the following elements:

  • a single entry point, ARCSPVS, to call from the application program
  • a single parameter block, $ARCSPVS, to pass with the call to ARCSPVS

  • an additional entry point, ARCSPAD, to call if your compiler does not support the SET field TO ADDRESS OF field statement

    The parameter block is common to all calls, regardless of the function.

  • The ARCSPVS API supports the following functions:

    The Define function assigns a name to a virtual storage area and defines the characteristics of the area. You can also use this function at program restart to refresh the virtual storage area automatically to its state at the last time it was saved.

  • The Refresh function manually refreshes the virtual storage area to its state at the last time it was saved. This function is valid only if you specify MANUAL for the Refresh Interval parameter when you use the Define function.
  • The Delete function removes the definition of a virtual storage area when the application program no longer requires AR/CTL to manage the area.

Program changes before restart

If you need to make program changes after an abend and before a restart, keep the following considerations in mind:

  • At restart, AR/CTL compares the length of each virtual storage area in the checkpoint data set with the length of the area that is currently defined in the program. If the lengths are different, AR/CTL uses the smaller of the two lengths.
  • The name of each virtual storage area must be the same at restart as it was during the initial Define function.



 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*