0001 TPALLOC(3)
0002 ==========
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpalloc - Allocate XATMI buffer
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 char *tpalloc(char *'type', char *'subtype', long 'size');
0016
0017
0018 For XATMI client link with '-latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm'
0019
0020 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi
0021 -lubf -lnstd -lpthread -lrt -lm'
0022
0023 DESCRIPTION
0024 -----------
0025 Function allocates XATMI buffer by given 'type' and 'subtype'. The buffer size
0026 is indicated by 'size' argument, if it set to 0 and buffer type is 'UBF', then
0027 system allocates 1024 for new buffer. Currently subtype is not used, and it can
0028 be leaved NULL or empty string. If function succeeds, then Enduro/X registers
0029 buffer in internal registry. If user allocates the buffer, it is up to user to
0030 free it with *tpfree()*, only exception is with auto buffers which are allocated
0031 at point when when service receives request, and Enduro/X will free the buffer
0032 after doing *tpreturn()* or *tpforward()*.
0033
0034 *Valid type*
0035
0036 *UBF* Unified Buffer Format. Which is type key-value storage with extensive API.
0037 See *ubf.h* for list of functions.
0038
0039 *UBF32* The same as *UBF*.
0040
0041 *FML* Compatibility mode with Tuxedo. Same as *UBF*.
0042
0043 *FML32* Compatibility mode with Tuxedo. Same as *UBF*.
0044
0045 *STRING* String buffer. It can store any ASCII character except 0x00, which will
0046 indicate the end of the data i.e. zero terminated string.
0047
0048 *JSON* This is also string format, can hold ASCII chars, 0x00 is used for string
0049 termination. The difference between this format and *STRING*, is that JSON
0050 buffer can be used for converting it automatically to *UBF* and vice versa,
0051 either by service request or by issuing *tpjsontoubf()*, *tpubftojson()*.
0052
0053 *CARRAY* Byte array buffer. Can hold 0x00 byte.
0054
0055 *VIEW* This is view buffer, see *viewfile(5)* for view descriptor format. Basically
0056 with view the C structure is being defined (generated) which included in the code
0057 by header file. For *VIEW* buffer 'subtype' must be specified. The views must be
0058 configured by setting up 'VIEWDIR' and 'VIEWFILES' environment variables.
0059 'VIEWFILES' must contain the list of compiled 'object-files'. If attempt to allocate
0060 view that is not defined or the environment is not configured, *tpalloc* will
0061 return *TPENOENT* error. When allocating the view, the size must be specified
0062 how much space shall be allocated. How ever, it must not be less that
0063 sizeof(<generated view struct>). If size is less than 1024, then 1024 bytes are
0064 allocated. If 1024 or given size is less than structure size, then warning is
0065 printed in ULOG. If size is smaller than struct size, then any operations with
0066 structure (like *tpcall(3)* or *Bvstof(3)*) can cause segmentation fault.
0067
0068 RETURN VALUE
0069 ------------
0070 On success, *tpalloc()* return ptr to mem block; on error, NULL is returned,
0071 with *tperrno* set to indicate the error.
0072
0073
0074 ERRORS
0075 ------
0076 Note that *tpstrerror()* returns generic error message plus custom message with
0077 debug info from last function call.
0078
0079 *TPEINVAL* Invalid type parameters are given to function, possibly NULL. This
0080 error also can be generated in case if the environment is not configured for
0081 Enduro/X properly.
0082
0083 *TPENOENT* Invalid type specified to function. VIEW sub-type not found or
0084 environment is not configured.
0085
0086 *TPESYSTEM* System failure occurred during serving. See logs i.e. user log, or
0087 debugs for more info.
0088
0089 *TPEOS* System failure occurred during serving. See logs i.e. user log, or
0090 debugs for more info. In case of insufficient memory this error will be
0091 generated too.
0092
0093 EXAMPLE
0094 -------
0095 See *atmitest/test001_basiccall/atmiclt1.c* for sample code.
0096
0097 BUGS
0098 ----
0099 Report bugs to support@mavimax.com
0100
0101 SEE ALSO
0102 --------
0103 *tpfree(3)* *viewfile(5)* *tprealloc(3)*
0104
0105 COPYING
0106 -------
0107 (C) Mavimax, Ltd
0108
