Guardian Procedure Calls Reference Manual

USEREVENTFILE_REGISTER_ Procedure
Summary
Syntax for C Programmers
Syntax for TAL Programmers
Parameters
Returned Value
Considerations
Summary
The USEREVENTFILE_REGISTER_ procedure is used to establish a file number to access an
application-defined user event set for an application that intends to use user events in combination
with the common wait and I/O completion procedures. You can use the returned file number later
as an input to the AWAITIO/FILE_COMPLETE_ family of procedures.
USEREVENTFILE_REGISTER_ has two output parameters: userEventFileNum and errorDetail.
On successfully establishing a file number to access a defined user-event set,
USEREVENTFILE_REGISTER_ populates the file number in the userEventFileNum parameter. If
USEREVENTFILE_REGISTER_ is unsuccessful in establishing the file number, the errorDetail
parameter is populated with the file-system error.
USEREVENTFILE_REGISTER_ must always be used in conjunction with the USEREVENT_SET_
procedure and the AWAITIO/FILE_COMPLETE_ family of procedures as follows:
1. Call USEREVENTFILE_REGISTER_ to establish a file number (userEventFilenum) to map
to the user event set.
2. Call USEREVENT_SET_ to set the user event set for the process. USEREVENT_SET_ can be
invoked multiple times as necessary.
3. Call AWAITIO[X|XL], FILE_AWAITIO64_, or FILE_COMPLETE[L]_ to wait for both user events
and file I/O completions. If these procedures return userEventFilenum, the tag parameter
contains the completed event. The completed event is removed from the pending user event
set of this process.
NOTE: Applications do not have to call USEREVENT_REGISTER_ before calling
USEREVENT_SET_; the two procedures are independent operations and can be called in either
sequence. However, both procedures must be called before the eventual file-oriented wait.
USEREVENTFILE_REGISTER_ returns the outcome of the call in the return value.
NOTE: The USEREVENTFILE_REGISTER_ procedure is supported on systems running H06.27 and
later H-series RVUs and J06.16 and later J-series RVUs.
Syntax for C Programmers
#include <cextdecs(USEREVENTFILE_REGISTER_)>
int16 USEREVENTFILE_REGISTER_ ( int16 *userEventFilenum
,int16 *errorDetail );
Syntax for TAL Programmers
error := USEREVENTFILE_REGISTER_ ( userEventFilenum ! o
,errorDetail ); ! o
USEREVENTFILE_REGISTER_ Procedure 1473