g32_notify Function

Purpose

Turns data notification on or off.

Libraries

HCON Library
C (libg3270.a)
Pascal (libg3270p.a)
FORTRAN (libg3270f.a)

C Syntax

#include <g32_api.h>

g32_notify ( as note)

struct g32_api *as;
int note;

Pascal Syntax

subroutine g32note (var  as : g32_api;
  note : integer) : integer; external;

FORTRAN Syntax

EXTERNAL G32NOTIFY

INTEGER  AS(9),  Note, G32NOTIFY

RC = G32NOTIFY(ASNote)

Description

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.

C Parameters

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).

Pascal Parameters

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).

FORTRAN Parameters

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).

Return Values

Item Description
0 Indicates successful completion.
-1 Indicates an error has occurred.
  • The errcode field in the g32_api structure is set to the error code identifying the error.
  • The xerrinfo field can be set to give more information about the error.

Examples

Note: The following example is missing the required g32_open and g32_alloc functions, which are necessary for every HCON Workstation API program.

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 */
      }
}