0001 CCONFSRV(8)
0002 ===========
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 cconfsrv - Common configuration server
0009
0010 SYNOPSIS
0011 --------
0012 *cconfsrv*
0013
0014 DESCRIPTION
0015 -----------
0016 This is special XATMI server shipped with Enduro/X in order to provide
0017 common-configuration (ini file) parsing facilities to all programming languages
0018 which are provided by Enduro/X. The idea behind the configuration server is that
0019 it uses XATMI API (exposed as service) in order to get configuration section or
0020 list all configuration that is used by application. Configuration service name advertised
0021 by this server is *@CCONF*.
0022
0023 This server is optional and can be used by third party application in
0024 oder to read the configuration files via standard
0025 XATMI service calls.
0026
0027
0028 VARIABLE SUBSTITUTION
0029 ---------------------
0030 cconfsrv engine processes environment variables or special functions
0031 in the placeholders. Placeholder is defined as ${ENV_VARIABLE} for environment
0032 variables and ${FUNC=[PARAMETER]} for functions. The value can be escaped with
0033 \${some_value}. For list of functions please refer to *ndrxconfig.xml(5)* manpage.
0034
0035 Substitution functions in values for the ini parameters (keys).
0036
0037 API - get section
0038 -----------------
0039 Get mode ('EX_CC_CMD' UBF buffer set to 'g' (default)). In this mode the
0040 request for configuration is made for particular section. The config files
0041 (or directories) for which to do the lookup can be set in 'EX_CC_RESOURCE' field,
0042 you may use multiple occurrences. If field is not set, then lookup is done in all
0043 files which are loaded into configuration library. This includes Enduro/X own
0044 config files, which are set in *NDRX_CCONFIG* environment variables
0045 (see ex_env(5)). The get request must contain 'EX_CC_LOOKUPSECTION'
0046 field, which indicates the section to lookup.
0047
0048 'EX_CC_LOOKUPSECTION' can be set to lookup the sub-sections, for example
0049 if you have in config files:
0050
0051 /paht/to/test1.ini:
0052 --------------------------------------------------------------------------------
0053 [TEST1]
0054 PARAM1=value1
0055 PARAM2=value2
0056
0057 [TEST1/SUB1]
0058 PARAM3=value3
0059 PARAM5=value5
0060 --------------------------------------------------------------------------------
0061
0062 /path/to/test2.ini:
0063 --------------------------------------------------------------------------------
0064 [TEST1/SUB1/SUB2]
0065 PARAM3=value4
0066 --------------------------------------------------------------------------------
0067
0068 Then by doing lookup to 'TEST1/SUB1/SUB2' section, you will get following result:
0069
0070 Request buffer:
0071 --------------------------------------------------------------------------------
0072 EX_CC_CMD g
0073 EX_CC_LOOKUPSECTION TEST1/SUB1/SUB2
0074 EX_CC_RESOURCE /paht/to/test1.ini
0075 EX_CC_RESOURCE /paht/to/test2.ini
0076 --------------------------------------------------------------------------------
0077
0078 Response buffer:
0079 --------------------------------------------------------------------------------
0080 EX_CC_SECTION test1
0081 EX_CC_KEY PARAM1
0082 EX_CC_VALUE value1
0083 EX_CC_SECTION test2
0084 EX_CC_KEY PARAM2
0085 EX_CC_VALUE value2
0086 EX_CC_SECTION TEST1/SUB1/SUB2
0087 EX_CC_KEY PARAM3
0088 EX_CC_VALUE value4
0089 EX_CC_SECTION TEST1/SUB1
0090 EX_CC_KEY PARAM5
0091 EX_CC_VALUE value5
0092 --------------------------------------------------------------------------------
0093
0094 Mention that 'PARAM3' value is set to 'value4' and not 'value3', because
0095 'TEST1/SUB1/SUB2' closer matched the lookup request.
0096 The principle is that all parent variables are gathered. If any variable is
0097 common between parent and child, then child element
0098 will be returned, as it is with higher priority.
0099
0100 When doing requests to configuration server it is possible to request for
0101 mandatory field keys checking. The must-have keys are loaded into 'EX_CC_MANDATORY'
0102 field occurrences. If during section lookup key is not found,
0103 then error '6' is returned.
0104
0105 It is possible request format verification. The key-format fields are
0106 used into 'EX_CC_FORMAT_KEY' + 'EX_CC_FORMAT_FORMAT' occurrences.
0107 If the format does not match field, error code '7' is returned.
0108
0109 *'EX_CC_FORMAT_FORMAT' field can have following values:*
0110
0111 *t* - Boolean field, valid values starts with on of the following
0112 symbols: 'TtFfYyNn10'.
0113
0114 *sX..Y* or *s..Y* (e.g. s10..20, s..5) - String field, min length X and
0115 max length Y. If X is not set (second format), then X is assumed to be 0.
0116
0117 *iX..Y* or *i..Y* (e.g. i1..2, i..3) - Integer field, min len (measured as
0118 string) X and max len (measured as string Y.
0119
0120 *nX..Y* or *n..Y* (e.g. n2..5, n..3) - Numeric field (can be floating
0121 point format). Min length X (measured as string) and max length Y (measured as string).
0122
0123 API - list sections
0124 -------------------
0125 It is possible to enter in conversational mode in request sections which begins
0126 with certain phrase or it is possible to list all sections for given resources.
0127 To enter is list mode you need to call the configuration server with 'EX_CC_CMD'
0128 UBF buffer field set 'l'. If this is the only field then all sections from default
0129 Enduro/X configuration files will be returned.
0130
0131 The sections which starts with phrase can be set in 'EX_CC_LOOKUPSECTION'
0132 UBF field occurrences. Resource to lookup can be specified in 'EX_CC_RESOURCE'.
0133
0134 EXIT STATUS
0135 -----------
0136 When error occurs, the configuration service returns *TPESVCFAIL*,
0137 and 'EX_NERROR_CODE' is set to corresponding error code. 'EX_NERROR_MSG' have
0138 some additional information about error condition.
0139
0140 *EX_NERROR_CODE* values:
0141
0142 *1* Invalid INI file(s).
0143
0144 *2* Malloc failed (system have low of memory or some kind of other system
0145 related problem).
0146
0147 *3* Unix error occurred.
0148
0149 *4* Invalid arguments passed.
0150
0151 *5* System failure.
0152
0153 *6* Mandatory field is missing. 'EX_NERROR_MSG' specifies the exact problematic field.
0154
0155 *7* Field value format error. 'EX_NERROR_MSG' specifies the exact problematic field.
0156
0157 EXAMPLE
0158 -------
0159 See *atmitest/test030_cconfsrv/atmiclt30.c* for sample code.
0160
0161 BUGS
0162 ----
0163 Report bugs to support@mavimax.com
0164
0165 SEE ALSO
0166 --------
0167 *ex_env(5)*, *ndrxconfig.xml(5)*
0168
0169 COPYING
0170 -------
0171 (C) Mavimax, Ltd
0172
