0001 TPADVERTISE(3)
0002 ==============
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpadvertise, tpadvertise_full - advertise XATMI service
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 #define tpadvertise('_SVCNM', '_FNADDR') tpadvertise_full(_SVCNM, _FNADDR, #_FNADDR)
0016
0017 int tpadvertise_full (char \*svcnm, void (*)(TPSVCINFO *) 'func', char *'funcname');
0018
0019 Link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
0020
0021 DESCRIPTION
0022 -----------
0023 Advertise service is done by function 'tpadvertise_full'. 'svcnm' is service name,
0024 services cannot contain reserved symbol '@' and cannot start with '.', which are intended for
0025 Enduro/X system use. Service name cannot contain symbols ',' and '/'.
0026 Max service name length is defined by *MAXTIDENT* constant. If length is
0027 longer, it will be truncated. 'func' is a pointer to service function.
0028 'funcname' is name of the function that will be shown in *xadmin psc* listings.
0029 For compatibility with other systems C macro 'tpadvertise' is provided which
0030 consumes '_SVCNM' as service name, and '_FNADDR' as pointer to function.
0031 The function name is automatically generated by precompiler.
0032
0033 Function can be called during the server initialization phase (i.e. *tpsvrinit()*
0034 function) and during the runtime (i.e. for service function).
0035
0036 This function is available only for XATMI servers.
0037
0038 Function logic in case if shared memory is full (no more space for new services
0039 defined by *NDRX_SVCMAX* env variable) differs between static mode (when
0040 done within the *tpsrvinit(3)* and dynamic mode when done from booted server during the
0041 XATMI service call.
0042
0043 During the *static* mode, the real advertise to shared memory is done only
0044 after the *tpsrvinit(3)* function is finished. Thus during the tpadvertise() calls,
0045 the function does not know about SHM space available. And the only limit here
0046 is *48* services per server process. If in shared memory there are fewer slots
0047 available, then server boot process will ignore that fact, will do following:
0048
0049 - Ignore the SHM error, and do not add record to SHM.
0050
0051 - Will log corresponding message in ULOG.
0052
0053 - Report to *ndrxd(8)* full list of services.
0054
0055 - As result xadmin psc will show the ignored
0056
0057 - xadmin psvc will not show ignored services (as these are SHM scans).
0058
0059 The logic of static service advertise might change in future Enduro/X releases.
0060
0061 During the *dynamic* mode advertise, SHM space checks are performed and
0062 *TPELIMIT* error is reported correctly.
0063
0064 Race condition is possible if for last service performing *unadvertise(3)* and then
0065 tpadvertise() again. In such case *ndrxd(8)* might unlink the service queue, while following
0066 tpadveritse() call would assume that service queue was open OK. Thus some delay
0067 of few sanity cycles of ndrxd is recommended between such unadvertise and advertise.
0068
0069 RETURN VALUE
0070 ------------
0071 On success, *tpadvertise_full()* return zero; on error, -1 is returned,
0072 with *tperrno* set to indicate the error.
0073
0074
0075 ERRORS
0076 ------
0077 Note that *tpstrerror()* for returns generic error message plus custom message
0078 with debug info from last call.
0079
0080 *TPEINVAL* '_SVCNM' is empty or NULL. Service length is longer than *MAXTIDENT*.
0081 '_FNADDR' is NULL.
0082
0083 *TPELIMIT* Service count limit reached. This can be *48* services per server binary
0084 which is implied limit by Enduro/X.
0085
0086 *TPEMATCH* Service with given name is already advertised, and pointer to function
0087 is different. If pointer matches, that it is not an error.
0088
0089 *TPEOS* System failure occurred during serving. See logs i.e. user log, or
0090 debugs for more info. That could insufficient memory or other error.
0091
0092
0093 EXAMPLE
0094 -------
0095 See *atmitest/test001_basiccall/atmisv1.c* for sample code.
0096
0097
0098 BUGS
0099 ----
0100 Report bugs to support@mavimax.com
0101
0102 SEE ALSO
0103 --------
0104 *tpunadvertise(3)* *ex_env(5)* *ndrxd(8)* *xadmin(8)*
0105
0106 COPYING
0107 -------
0108 (C) Mavimax, Ltd
0109
