Technical Reference: Base Operating System and Extensions, Volume 2

SpmiInit Subroutine

Purpose

Initializes the SPMI for a local data consumer program.

Library

SPMI Library (libSpmi.a)

Syntax

#include sys/Spmidef.h

int SpmiInit (TimeOut)
int TimeOut;

Description

The SpmiInit subroutine initializes the SPMI. During SPMI initialization, a memory segment is allocated and the application program obtains basic addressability to that segment. An application program must issue the SpmiInit subroutine call before issuing any other subroutine calls to the SPMI.

Note

The SpmiInit subroutine is automatically issued by the SpmiDdsInit subroutine call. Successive SpmiInit subroutine calls are ignored.

Note

If the calling program uses shared memory for other purposes, including memory mapping of files, the SpmiInit subroutine call must be issued before access is established to other shared memory areas.

The SPMI entry point called by the SpmiInit subroutine assigns a segment register to be used by the SPMI subroutines (and the application program) for accessing common shared memory and establishes the access mode to the common shared memory segment. After SPMI initialization, the SPMI subroutines are able to access the common shared memory segment in read-only mode.

This subroutine is part of the server option of the Performance Aide for AIX licensed product and is also included in the Performance Toolbox for AIX licensed product.

Parameters

TimeOut

Specifies the number of seconds the SPMI waits for a Dynamic Data Supplier (DDS) program to update its shared memory segment. If a DDS program does not update its shared memory segment in the time specified, the SPMI assumes that the DDS program has terminated or disconnected from shared memory and removes all contexts and statistics added by the DDS program.

The SPMI saves the largest TimeOut value received from the programs that invoke the SPMI. The TimeOut value must be zero or must be greater than or equal to 15 seconds and less than or equal to 600 seconds. A value of zero overrides any other value from any other program that invokes the SPMI and disables the checking for terminated DDS programs.

Return Values

The SpmiInit subroutine returns a value of 0 if successful. If unsuccessful, the subroutine returns a nonzero value. If a nonzero value is returned, the application program should not attempt to issue additional SPMI subroutine calls.

Error Codes

All SPMI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:

extern char SpmiErrmsg[];
extern int SpmiErrno;

If the subroutine returns without an error, the SpmiErrno variable is set to 0 and the SpmiErrmsg character array is empty. If an error is detected, the SpmiErrno variable returns an error code, as defined in the sys/Spmidef.h file, and the SpmiErrmsg variable contains text, in English, explaining the cause of the error. See the List of SPMI Error Codes for more information.

Files

/usr/include/sys/Spmidef.h

Declares the subroutines, data structures, handles, and macros that an application program can use to access the SPMI.

Related Information

For related information, see: