TPFxd_nextVolume: Advance to the next volume when reading or writing

This function causes external device support to advance to the next volume when reading or writing and when the TPFxd_open request has spanned several volumes.

Format

#include <tpf/c_tpxd.h>
int   TPFxd_nextVolume (TPFxd_extToken     **token,
                        TPFxd_locationMap  *positioningStringMap,
                        int                timeout,
                        char               *message);
token
This pointer must point to the token from a previous TPFxd_archiveStart function.
positioningStringMap
A pointer to a positioning string map. This must be the same positioning string map that was used when the TPFxd_open request, was issued to position the external device to the correct location. If this is an TPFxd_open write request, the positioning string, on return, will contain the current position of the external device associated with the token.
timeout
The amount of time in seconds to wait before determining the next volume is not available and an error will be returned. If a value of zero is provided, the function will wait indefinitely for the request to be completed.
message
A pointer to a message string that will be sent to the console if the function is canceled because of a timeout condition. If a NULL pointer is passed, no message will be sent.

Normal return

The normal return is a positive value. For a TPFxd_nextVolume request following a TPFxd_open request for a read, the next volume listed in the positioning string will be mounted and positioned as indicated by the positioningStringMap parameter. For a TPFxd_nextVolume request following a TPFxd_open for write request, a new volume will be allocated and the positioningStringMap parameter will be updated to indicate that this volume is now part of the set associated with this TPFxd_open request.

Error return

An error return is indicated by a negative return code. For a list of error codes applicable to this function, see Error codes.

Programming considerations

This function can be called at any time an external device is opened. The following restrictions apply:
  • If the TPFxd_nextVolume function is entered for an external device that was opened for a read or read-shared request and there are no more volumes in the TPFxd_locationMap parameter that is passed to the function, a TPFxd_ERROR_EOVerror error will be returned.
  • If TPFxd_nextVolume function is issued for an external device that was opened for write or write-shared requests and there are already archive_max_volumes (as defined in the c_tpxd.h header file) volumes in the TPFxd_locationMap parameter that were passed to the function, a TPFxd_ERROR_EOVerror error will be returned.

Examples

The following example issues a TPFxd_open function after a TPFxd_archiveStart function and if a TPFxd_ERROR_EOVwarning error occurs when attempting to write the object to the device, a request will be sent for a subsequent volume to be allocated. 
#include <tpf/c_tpxd.h>
int  example()
{
TPFxd_extToken    *token;
TPFxd_locationMap wherefirst;
enum              tpxd_mode mode;
enum              tpxd_opts access;
int               howbigitis;
int               howlongtowait;
char              *message;
int               returncode;
char              *stufftowrite;

howlongtowait = 60;
howbigitis = 32000;
message = NULL;
token = NULL;
mode = WT;
access = IMMEDIATE;
TPFxd_archiveStart (&token, mode, access);
returncode = TPFxd_open (&token,
            &wherefirst,
            howbigitis,
            howlongtowait,
            message,
            mode );

stufftowrite = malloc(howbigitis);
returncode = TPFxd_write(token,stufftowrite,&howbigitis);
if (returncode == TPFxd_ERROR_EOVwarning)
  {
  TPFxd_nextVolume (&token,
                    &wherefirst,
                    howlongtowait,
                    "Why did it timeout?");
  }
free(stufftowrite);
⋮
}

Related information

See External device support overview for more information about this function and z/TPF C/C++ language support.