ZLTSTORE (3X)

NAME

zltstore - Logical data storage allocation

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 zltstore (appln, label, size, offsetp
 
uint32   appln;
char     *label;
uint32   size;
int32    *offsetp;

DESCRIPTION

Routine zltstore requests a data area in the logical terminal table extension for terminals of a specific application number. Each data area is identified by the terminal application group and a user defined label. The returned offset (on successful completion) could then be used in subsequent data storing and retrieval calls (zltup). For data update and retrieval, using data storage is relatively more efficient than using a data queue. However, due to the limited usable area in the terminal tables, a data queue should be used for large amounts of data. See under zltqueue for how to allocate a data queue.

The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options "-lzcom_c -lpthread" to cc(1) or ld(1).

Threads Considerations

This routine may be called from a multi-threaded application using the POSIX (1003.1c) kernel threads API package. This routine has the following characteristics when called by a multi-threaded application:

cancellation point	Thread cancellation can occur when a thread calls this routine.
async-cancel unsafe	The calling thread's cancelability type must be PTHREAD_CANCEL_DEFERRED if cancellation is enabled.
async-signal unsafe	It cannot be called from a signal handler.
fork unsafe	It cannot be called by a child process after fork(2) but before exec(2).

PARAMETERS

appln	Application number.
label	Storage label name.
size	Storage size requested, in bytes. The size must be a multiple of 4 bytes and must not exceed the available area in logical terminal table extension (as defined by LOGICAL-SIZE in TTGEN configuration file). Otherwise, error ZEBADSIZE (-63) is returned.
offsetp (Return Param)	Starting byte offset, relative to the beginning logical terminal table, for the storage in the extension area.

NOTES

The returned offset indicates the start of the usable data area, with a size as specified in the call. The actual size of the reserved area will be silently rounded up to a multiple of 8-byte. This is to ensure all the storage areas are aligned on a 8-byte boundary, hence the storage may be used to store 64-bit entity (e.g. long long type in 32-bit mode, or long and pointer types in LP64 mode) without data alignment problem.

The data area should only be used for terminals within the specified application group. There is NO queue ownership validation when it is used in zltup. An application value of zero is used for terminals of ALL application groups. A zero application value is used to store global data for all terminals in the ZCOM subsystem.

Routine zltstore returns an already assigned area if the application number and storage label and storage size all match a previously assigned area. Otherwise, an error is returned. This provides a facility to share data areas between different programs and enables program restartability.

If bit ZCOM_ZLTSTORE_NA (0x8000) of the size parameter is set before zltstore is called, then zltstore will only return a previously assigned area. If a matching area of storage is not assigned, this will result in an error return. If this bit of the size parameter is zero, a new storage area will be allocated if it is not already assigned.

RETURN VALUE

Routine zltstore returns 0 if successful. Otherwise, a non-zero error code is returned. See /opt/acc/include/zcom/zcomsys.h for the list of ZCOM error codes and their meanings.

EXAMPLE

#include <zcom/zcomsys.h>
#include <zcom/zcomcall.h>
 
int32         ierr;
uint32        appln;
char          label[6];
uint32        size;
int32         offset;
 
if (ierr = zltstore (appln, label, size, &offset)) {
       /* error return code */
}
else {
       /* good return code */
}

FILES

/opt/acc/include/zcom/zcomsys.h	ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files.
/opt/acc/include/zcom/zcomcall.h	ZCOM routine function prototypes (requires ANSI C compilation).