IOS_$LOCATE Domain/OS IOS_$LOCATE
NAME
ios_$locate - get a pointer to data in a stream
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/ios.h>
long ios_$locate(
ios_$id_t &stream_id,
ios_$put_get_opts_t &get_options,
char **data_ptr,
long &data_size,
status_$t *status)
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/ios.ins.pas';
function ios_$locate(
in stream_id: ios_$id_t;
in get_options: ios_$put_get_opts_t;
out data_ptr: univ_ptr;
in data_size: integer32;
out status: status_$t): integer32;
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/ios.ins.ftn'
integer*2 nbytes
parameter (nbytes=12)
integer*2 stream_id, get_options
integer*4 ret_length, data_size, status
character*1 data(nbytes)
integer*4 data_ptr
pointer /data_ptr/ data
ret_length = ios_$locate(stream_id, get_options, data_ptr,
& data_size, status)
DESCRIPTION
Ios_$locate gets a pointer to the next record or to the next data_size
unread bytes on the stream specified by stream_id. Ios_$locate returns
the number of bytes of valid stream data that data_ptr points to. If the
next record is more than data_size bytes long, ios_$locate returns a
pointer to only data_size bytes of the record, and puts the
ios_$buffer_too_small error code in status.
Normally, ios_$locate just gets a pointer to the next unread byte in a
stream. However, if the manager of the stream does not support the
internal buffering necessary for ios_$locate to work this way, then
ios_$locate must create a buffer and call ios_$get to move data from the
stream to the buffer. After the ios_$get completes, ios_$locate returns
a pointer in data_ptr to the buffer it created. The size of the buffer
that ios_$locate creates is either data_size bytes or 1024 bytes, which-
ever is smaller, though a larger buffer size can be set via a call to
ios_$set_locate_buffer_size. If the created buffer is too small to hold
an entire record, ios_$locate puts the ios_$buffer_too_small error code
in status.
stream_id
The ID of the stream.
get_options
A set of options affecting ios_$locate's behavior. Specify a combi-
nation of the following elements:
ios_$cond_opt
Locate only if the stream can support the operation immedi-
ately. If the stream is empty and the call would be blocked,
return with a ios_$get_conditional_failed completion status.
ios_$no_put_get_opts
Locate the next record. This is the default and is included
for languages that lack Pascal set types. It is equivalent to
specifying [] in Pascal.
ios_$no_rec_bndry_opt
Ignore boundaries in the input stream while locating data. The
caller can use this option if it is not interested in any data
groupings supported by the object type. For example,
ios_$no_rec_bndry_opt will cause ios_$locate to ignore
ios_$newline characters in an unstructured (uid_$unstruct)
object.
ios_$preview_opt
Do not update the stream marker after the operation.
data_size
The maximum number of bytes that data_ptr must point to. If there
are more than data_size bytes remaining in the current record,
ios_$locate will return a number of bytes read equivalent to
data_size, and the completion status will indicate an
ios_$buffer_too_small error. A process can find out how many bytes
remain to be read in the current record by calling
ios_$inq_rec_remainder.
data_ptr
A pointer to the located data. This pointer remains valid only
until the next input or output call on the stream. After the next
input or output call, data_ptr may not point to the same data, but
the details depend on the type manager.
status
The completion status.
NOTES
Both ios_$locate and ios_$get can access data in a stream. Ios_$get
copies the data into a buffer, while ios_$locate returns a pointer to the
data. Use ios_$locate to access data that is needed only once and not
modified because ios_$locate does not always copy the data and so is
often faster. Of course, if ios_$locate must call ios_$get to complete
the read, then using ios_$locate is no more efficient than using
ios_$get.