Context parameters

APARAM is a child instance of class ACONTEXT. It implements a local cache to store the already accessed parameter values in order to avoid querying the database every time.

1. Parameter definition

The parameter definition has not changed at all. In version V12 like in version 6, the definition is based on the parameter dictionary function (GESADP).

2. Methods to retrieve parameter value

When searching a parameter value assigned to Folder, Legislation, Company, or Site levels (regardless of the level of definition), 3 methods are available :

  • AGETVALCHAR(LEVCOD,TYPVAL,PARAM) is used to get an alpha value.
  • AGETVALNUM(LEVCOD,TYPVAL,PARAM) is used to get an integer or local menu value.
  • AGETVALDATE(LEVCOD,TYPVAL,PARAM) is used to get a date value.

These 3 methods take the same parameters: LEVCOD, TYPVAL, and PARAM:

  • LEVCOD is the code of your search assignment level. It can have the following values:

    • [V]CST_ALEVFOLD : Folder.
    • [V]CST_ALEVCPY : Company.
    • [V]CST_ALEVFCY : Site.
    • [V]CST_ALEVLEG : Legislation.

  • TYPVAL is the code of Folder/Legislation/Company/Site (depending on LEVCOD).

  • PARAM is the parameter code.

Example:

#### Parameter AECLIDBG is of type Local menu and is defined at User level.
#### Here we want to assign the value to Legislation FRA:
Local Integer PARAM_VALUE
PARAM_VALUE = fmet this.ACTX.APARAM.AGETVALNUM([V]CST_ALEVLEG, "FRA", "AECLIDBG")
## To assign the value to Company ADX:
PARAM_VALUE = fmet this.ACTX.APARAM.AGETVALNUM([V]CST_ALEVCPY, "ADX", "AECLIDBG")
to find a parameter value assigned at the user level (the level of definition must be user), 3 methods are available:
  • AGETUSERVALCHAR(PARAM) is used to get an alpha value.
  • AGETUSERVALNUM(PARAM) is used to get a numerical or local menu value.
  • AGETUSERVALDATE(PARAM) is used to get a date value.

These 3 methods take the same parameter: PARAM:

  • PARAM is the parameter code.

Example:

#### Parameter SSODOMAIN is of Alphanumeric and is defined at User level.
#### To assign the value to the current User:
#### The usual inheritance logic is applied when retrieving X3 parameter values
Local Char PARAM_VALUE
PARAM_VALUE = fmet this.ACTX.APARAM.AGETUSERVALCHAR("SSODOMAIN")
For more information about how the parameter values are retrieved, see the appendix.

3. Method for error handling

The returned value of the above six methods will be empty in case of problem (for example if the given Company code does not exist). Sometimes developers may need more information about the execution status; the Context cache provides the following method to get the error code (or status code) of the last call of one of these methods:

  • AGETVALERROR() returns an error code of the last call of method 'GET_PARAM_xxx', and 0 if no error happened.

Example:

Local Char    VALUE_CHAR
Local Integer VALUE_NUM
Local Integer ERROR_CODE
  VALUE_CHAR = fmet this.ACTX.APARAM.AGETUSERVALCHAR("SSODOMAIN")
  # If the value returned is empty, it might be an error
  If VALUE_CHAR = ""
    ERROR_CODE = fmet this.ACTX.APARAM.AGETVALERR()
    If ERROR_CODE = 0
      # value of "SSODOMAIN" is retrieved successfully, but is empty
    Else
      # let's manage the error
    Endif
  Endif
  VALUE_NUM = fmet this.ACTX.APARAM.AGETVALNUM([V]CST_ALEVLEG, "FRA", "AECLIDBG")
  ERROR_CODE = fmet this.ACTX.APARAM.AGETVALERR()
  If ERROR_CODE = 0
    # value of "AECLIDBG" is retrieved successfully
  Endif

Error code descriptions

CodeSignification
0Successful.
1error: LEVCOD invalid.
2error: PARAM empty.
3error: You are looking for a parameter value not defined in the current folder.
4error: TYPVAL empty.
5error: PARAM does not exist.
6error: PARAM is not the right type for the method you called.
7error: PARAM can only be assigned at User level.
8error: TYPVAL invalid.
9error: Incorrect Date format.
10error: PARAM is not defined at User level.

4. Appendix: How X3 manages the parameters

  • In the parameter dictionary (function GESADP), parameters are defined at different levels: Folder, Legislation, Company, Site, or User.
  • At parameter setup, depending on the level definition, values can be defined at different scope levels.
    • If the parameter is defined at the Folder level, a unique value can be defined.
    • If the parameter is defined at the Legislation level, a value can be given for each legislation code, but a Folder level value can also be given.
    • If the parameter is defined at the Company level, values can be assigned to Company codes, Legislation codes, and globally... and so on.
  • As soon as a parameter value is requested at a given scope level (for instance, the value parameter for site S1), the value stored at S1 level will be delivered; but if no value is found, an inheritance principle is managed to get a value from the upper level.
    • If this is the case for S1, the value associated to C1 (the company that belongs to the S1 site) will be used.
    • If no value is found on C1, the value found on L1 (the legislation the company C1 is associated with) will be used.
    • And finally, if no value is found for L1, the global default value will be used.
  • When a parameter value is searched at the user level, the inheritance principle is based on the default site associated with the module the parameter belongs to. Thus, a site, company, legislation, or global value (in this order of priority) can be used.