gtpc2mir | C/C++ Language Support User's Guide |
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
- Any TPFxd_open request that is successful must be paired with a
TPFxd_close request before exiting the entry control block (ECB) or
a CTL-0013 system error will occur.
- On return from a successful TPFxd_open function call, the
external device is assigned to that ECB and no other ECB can read from or
write to it.
- The token that is returned will be used on all subsequent
TPFxd_ requests. The storage allocated for the token will be
returned to the system when a TPFxd_archiveEnd function is called
and must not be changed by the application.
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