Turns data notification on or off.
HCON LibraryC (libg3270.a)Pascal (libg3270p.a)FORTRAN (libg3270f.a)The g32_notify subroutine is used to turn notification of data arrival on or off. The g32_notify subroutine may be used only by applications in an API/3270 session mode.
If an application wants to know when the emulator receives data from the host, it turns notification on. This causes the emulator to send a message to the application whenever it receives data from the host. The message is sent to the IPC message queue whose file pointer is stored in the eventf field of the as data structure. The application may then use the poll system call to wait for data from the host. Once notified the application should clear notification messages from the IPC queue, using the msgrcv subroutine. When the application no longer wants to be notified, it should turn notification off with another g32_notify call.
HCON application programs using the Pascal language interface must include and link both the C and Pascal libraries. Application programs using the FORTRAN language for the HCON API must include and link both the C and FORTRAN libraries.
The g32_notify function is part of the Host Connection Program (HCON).
The g32_notify function requires one or more adapters used to connect to a host.
| Item | Description |
|---|---|
| as | Specifies a pointer to the g32_api structure. Status is returned in this structure. |
| note | Specifies to turn notification off (if the note parameter is zero) or on (if the note parameter is nonzero). |
| Item | Description |
|---|---|
| as | Specifies a g32_api structure. |
| note | Specifies an integer that signals whether to turn notification off (if the note parameter is zero) or on (if the note parameter is nonzero). |
| Item | Description |
|---|---|
| AS | Specifies a g32_api equivalent structure as an array of integers. |
| Note | Specifies to turn notification off (if the Note parameter is zero) or on (if the Note parameter is nonzero). |
| Item | Description |
|---|---|
| 0 | Indicates successful completion. |
| -1 | Indicates an error has occurred.
|
The example fragment illustrates, in C language, the use of the g32_notify function in an api_3270 mode program:
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/poll.h>
#include <sys/msg.h>
#include "g32_api.h"****************************************************************
Note that the following function is an example of g32_notify function use.
It is meant to be called from an API application program that has already
performed a g32_open()or g32_openx() and a g32_alloc() function call. The
function will accept the as structure, a search pattern, and a timeout
(in seconds) as arguments. The purpose for calling this function is to
search for a certain pattern on the "screen" within a given amount of
time. As soon as the host updates the screen (presentation space),the
notification is sent (the poll returns with a success). This data may
not be your desired pattern, so this routine will retry until the timeout
is reached. The function will poll on the message queue and search the
presentation space each time the API is notified. If the pattern is found,
a success is returned. If the pattern is not found in the specified timeout
period, a failure (-1) is returned. The application should pass the timeout
value in seconds.
****************************************************************/search_pres_space (as,pattern,timeout)
struct g32_api *as; /* Pointer to api structure */
char *pattern; /* Pattern to search for in
presentation space */
int timeout; /* The maximum time to wait before
returning a failure */
{
char done=0; /* Flag used to test if loop is
finished */
int rc; /* return code */
long smsg; /* message buffer */
unsigned long nfdmsgs; /* Specified number of file
descriptors and number of
message queues to check. Low
order 16 bits is the number of
elements in array of pollfd.
High order 16 bits is number of
elements in array of pollmsg.*/
struct pollmsg msglstptr; /* structure defined in poll.h
contains message queue id,
requested events, and returned
events */
timeout *= 1000 /* convert to milliseconds for
poll call */ g32_notify (as, 1); /* turn on the notify */
rc = g32_search(as,pattern); /* search the presentation space
for the pattern */
if (rc == 0) {
done = 1;
}
/*Loop while the pattern not found and the timeout has not been
reached */
/* Note that this is done in 500 ms. increments */
while ( !(done) && (timeout > 0) ) {
/* wait a max of 500 ms for a response from the host */
/* This is done via the poll system call */
nfdmsgs = (1<<16); /* One element in the msglstptr
array. Since the low order
bits are zero, they will be
ignored by the poll */
msglstptr.msgid = as->eventf; /* The message queue id */
msglstptr.reqevents = POLLIN; /*Set flag to check if input is
present on message queue */ /* poll on the message queue. A return code of 1 signifies
data from the host. An rc of 0 signifies a timeout. An
rc < 0 signifies an error */
rc = poll (&msglstptr,nfdmsgs,(long)500);
rc = rc >> 16; /* shift return code into low
order bits */ /* If the poll found something, do another search */
if (rc = 1) {
/* call msgrcv system call, retrying until success */
/* This is done to flush the IPC queue */
do {
rc = msgrcv(as->eventf,(struct msgbuf *)&smsg,
(size_t)0,(long)1,IPC_NOWAIT|IPC_NOERROR);
}
while ( rc == G32ERROR); rc = g32_search (as,pattern); /* Search for pattern */
/* if pattern is found, set done flag to exit loop */
if (rc == 0) {
done = 1;
}
}
timeout -= 500; /* decrement the timeout by 500ms */
} /* end while */
g32_notify (as,0); /* turn the notify off again */
if (done) {
return (0); /* search was successful */
}
else {
return (-1); /* failure */
}
}