gtpc2mirC/C++ Language Support User's Guide

TPFxd_open-Fulfill Any Mount or Positioning Required

This function causes external device support to fulfill any mount or positioning required based on the positioning string provided.

Format

#include <c$tpxd.h>
long  TPFxd_open (TPFxd_extToken    **token,
                  TPFxd_locationMap  *positioningStringMap,
                  long                size,
                  long                timeout,
                  char               *message,
                  enum tpxd_mode      mode);

token
This pointer must point to the token from a previous TPFxd_archiveStart function for write requests.

positioningStringMap
A pointer to a positioning string map. If this is a TPFxd_open read request, the positioning string map will be used to position the external device to the correct location. If this is a TPFxd_open write request, on return the positioning string map will contain the current position of the external device associated with the token.

size
The approximate size of the collection to be written in 4-KB blocks. This will be ignored for read requests.

timeout
The amount of time in seconds to wait before determining that the tape is not available and an error will be returned. If a zero value is provided, the function will wait indefinitely for the request to be completed successfully.

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.

mode
The mode is one of the following:

RD
Open for a nonshared read.

RS
Open for a shared read.

WT
Open for a nonshared write.

WS
Open for a shared write.

Normal Return

The normal return is a positive value. For a TPFxd_open read request, the token parameter will be updated to the token allocated for this 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

Examples

The following example issues a TPFxd_open after a TPFxd_archiveStart request. The estimated size of the object to be written is 32 000 bytes and, if the device is not available in 60 seconds, a TPFXD_ERROR_timeout error will be reported. There will also be no error message issued from the TPFxd_open function when this happens.

#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;
 
howlongtowait = 60;
howbigitis = 32000;
message = NULL;
token = NULL;
mode = WT;
access = IMMEDIATE;
token = TPFxd_archiveStart (mode, access);
returncode = TPFxd_open (&token,
            &wherefirst,
            howbigitis,
            howlongtowait,
            message,
            mode );
printf("open return code is %i\n",returncode);

  ·
  ·
  ·
}

Related Information