SAPGetChangedServers(3sapd)


SAPGetChangedServers -- get changed server information

Synopsis

#include <sap_app.h> 

int SAPGetChangedServers(uint16 ServerType, int *ServerEntry, SAPI *ServerBuf, int MaxEntries, uint32 RevisionStamp, uint32 *NewRevisionStamp);

Description

SAPGetChangedServers returns information about servers that have changed since the last time the function was called.


NOTE: This function is supported only when the SAP daemon is running.

Each server entry in the mapped memory region is stamped with a revision or change stamp. Server entries are returned that have a value greater than the value of RevisionStamp passed on the function call. Information about servers that are no longer alive (HOPS >= 16) will also be returned if the server RevisionStamp value is greater than the function RevisionStamp value. Dead servers are never purged from the mapped memory region. When that server is reactivated, the same entry is updated to show the new status.

All server entries are maintained in the mapped memory region by server name and server type.

Parameters

(IN) ServerType
Specifies either the type of server desired or ALL_SERVER_TYPE to obtain information on all servers. Server types are defined in the include file.

(IN/OUT) ServerEntry
Pointer to an index value that indicates position in SAP responses from which the next MaxEntries will be returned. Modified on return. Should initially be set to zero (0).

(OUT) ServerBuf
Pointer to the address of a buffer whose size is calculated as follows:
sizeof(SAPI * MaxEntries) 
which will be filled with SAPI entries.

(IN) MaxEntries
Specifies the maximum number of SAPI entries which can be put in ServerBuf.

(IN) RevisionStamp
Address of the NewRevisionStamp value returned by the previous series of calls to SAPGetChangedServers.

(IN/OUT) NewRevisionStamp
Pointer to the value returned to be used in the next series of calls.

Usage

The ServerEntry argument must be set to zero on the first call and is updated by SAPGetChangedServers function. The updated value should be passed on subsequent calls. You should not modify the contents of ServerEntry except to set the initial value to zero.

The MaxEntries argument specifies the maximum number of SAPI entries which can be put in ServerBuf.

The RevisionStamp argument is the NewRevisionStamp value returned by the previous series of calls to SAPGetChangedServers. Server entries with a revision stamp greater than the function's RevisionStamp are copied to ServerBuf. This includes services that are no longer active (HOPS = SAP_SHUTDOWN). If the function's RevisionStamp is set to zero, all server information is returned. This field is not updated until you update its value. This allows you to make a series of calls to retrieve all changed servers.

The NewRevisionStamp argument returns a value to be used in the next series of calls. The value of NewRevisionStamp should be set to zero (0) before the first function call in a series is made. Its value will be updated by calling SAPGetChangedServers. Subsequent function calls will not alter the value. This allows multiple function calls to be used to retrieve all the changed servers. After all changed servers are retrieved, the process can be notified when additional changes are available. At this time, the value of NewRevisionStamp returned on the last set of calls is used for RevisionStamp and NewRevisionStamp is set to zero.

If successful, the function returns the number of SAPI entries returned in ServerBuf. The ServerEntry argument is set to the index of the next server entry to be read when the next function call is made. All server entries have been returned when the function return value is less than the MaxEntries or zero. The NewTimeStamp returns the current time stamp value if the field is set to zero; otherwise, its value is not changed.

Return values

If an error occurs, the function returns a negative number which is the negative of the error code.

>=0
successful

-10
not supported (SAP daemon not running)

Examples

   ServerType = FILE_SERVER_TYPE; 
   ServerEntry = 0; 
   MaxEntries = 1; 
   RevisionStamp = 0; 
   NewRevisionStamp = 0; 
   ret=SAPGetChangedServers(ServerType, &ServerEntry, &ServerBuf, 
       MaxEntries, RevisionStamp, &NewRevisionStamp); 

References

SAPNotifyOfChange(3sapd)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.