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 <tpf/c_tpxd.h>
int  TPFxd_open (TPFxd_extToken    **token,
                  TPFxd_locationMap  *positioningStringMap,
                  int                 size,
                  int                 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 <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;

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

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