gtpc2miqC/C++ Language Support User's Guide

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 <c$tpxd.h>
long  TPFxd_nextVolume (TPFxd_extToken     **token,
                        TPFxd_locationMap  *positioningStringMap,
                        long               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:

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 <c$tpxd.h>
long example()
{
TPFxd_extToken    *token;
TPFxd_locationMap wherefirst;
enum              tpxd_mode mode;
enum              tpxd_opts access;
long              howbigitis;
long              howlongtowait;
char              *message;
long              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