Quick Reference

Broker Attributes

The Broker attribute file contains a series of parameters (attributes) that control the availability and characteristics of clients and servers, as well as of the Broker itself. You can customize the Broker environment by modifying the attribute settings.

Note:
This section lists EntireX Broker parameters applicable to operating system BS2000 only. For attributes applicable to all operating systems, see Broker Attributes in the platform-independent Administration documentation.

This document covers the following topics:

Name and Location of Attribute File

The name and location of the broker attribute file is platform-dependent.

Platform File Name/Location
BS2000 File ETB-ATTR in library EXX103.JOBS.

Attribute Syntax

Each entry in the attribute file has the format:

ATTRIBUTE-NAME=value

The following rules and restrictions apply:

  • A line can contain multiple entries separated by commas.

  • Attribute names can be entered in mixed upper and lowercase.

  • Spaces between attribute names, values and separators are ignored.

  • Spaces in the attribute names are not allowed.

  • Commas and equal signs are not allowed in value notations.

  • Lines starting with an asterisk (*) are treated as comment lines. Within a line, characters following an * or # sign are also treated as comments.

  • The CLASS keyword must be the first keyword in a service definition.

  • Multiple services can be included in a single service definition section. The attribute settings will apply to all services defined in the section.

  • Attributes specified after the service definition (CLASS, SERVER, SERVICE keywords) overwrite the default characteristics for the service.

  • Attribute values can contain variables of the form ${variable name} or $variable name:

    • Due to variations in EBCDIC codepages, braces should only be used on ASCII (Linux or Windows) platforms or EBCDIC platforms using the IBM-1047 (US) codepage.

    • The variable name can contain only alphanumeric characters and the underscore (_) character.

    • The first non-alphanumeric or underscore character terminates the variable name.

    • Under Linux and Windows, the string ${variable name} is replaced with the value of the corresponding environment variable.

    • On z/OS, variable values are read from a file defined by the DD name ETBVARS. The syntax of this file is the same as the attribute file.

    • If a variable has no value: if the variable name is enclosed in braces, error 00210594 is given, otherwise $variable name will be used as the variable value.

    • If you encounter problems with braces (and this is quite possible in a z/OS environment), we suggest you omit the braces.

Broker-specific Attributes

The broker-specific attribute section begins with the keyword DEFAULTS=BROKER. It contains attributes that apply to the broker. At startup time, the attributes are read and duplicate or missing values are treated as errors. When an error occurs, the broker stops execution until the problem is corrected.

Tip:
To avoid resource shortages for your applications, be sure to specify sufficiently large values for the broker attributes that define the global resources.

Attribute Values Opt/
Req 		Operating System
z/OS Linux Windows BS2000
ABEND-LOOP-DETECTION YES | NO O z u w b
YES Stop broker if a task terminates abnormally twice, that is, the same abend reason at the same abend location already occurred. This attribute prevents an infinite abend loop.
NO Use only if requested by Software AG Support. This setting may make sense if a known error leads to an abnormal termination, but a hotfix solving the problem has not yet been provided. Reset to YES when the hotfix has been installed.
ABEND-MEMORY-DUMP YES | NO O z u w b
YES Print all data pools of the broker if a task terminates abnormally. This dump is needed to analyze the abend.
NO If the dump has already been sent to Software AG, you can set to NO to avoid the extra overhead.
ACCOUNTING NO | 128-255 O z      
NO | YES[SEPARATOR=char] O   u w b
Determines whether accounting records are created.
NO Do not create accounting records.
nnn The SMF record number to use when writing the accounting records.
YES Create accounting data.
char= separator character(s). Up to seven separator characters can be specified using the SEPARATOR suboption, for example:
ACCOUNTING = (YES, SEPARATOR=;)
If no separator character is specified, the comma character will be used.

See also Accounting in EntireX Broker under z/OS | Linux | Windows | BS2000.

ACCOUNTING-VERSION 1 | 2 | 3 | 4 | 5 O z u w b
Determines whether accounting records are created.
1 Collect accounting information. This value is supported for reasons of compatibility with EntireX Broker 7.2.1 and below.
2 Collect extended accounting information in addition to that available with option 1.
3 Create accounting records in layout of version 3.
4 Create accounting records in layout of version 4.
5 Create accounting records in layout of version 5.

This parameter applies when ACCOUNTING is activated.

ACI-CONVERSION YES | NO O z u w b
Determines the handling of ACI request and response strings of USTATUS.
YES Convert ACI request and response strings with ICU. See ICU Conversion in the Internationalization documentation.
NO Translate ACI request and response with internal translation table without support of national characters. See Translation User Exit in the Internationalization documentation.

Note:
This attribute was undocumented in EntireX versions prior to 10.3 and had default value NO. This meant that a translation user exit was used instead; this is no longer recommended.

APPLICATION-MONITORING
or
APPMON		 YES | NO O z u w b
Enable application monitoring in EntireX Broker.
YES Enable application monitoring.
NO Disable application monitoring.

See Application Monitoring.

AUTOLOGON YES | NO O z u w b
YES LOGON occurs automatically during the first SEND or REGISTER.
NO The application has to issue a LOGON call.
BLACKLIST-PENALTY-TIME 5M | n | nS | nM | nH R z u w b
Define the length of time a participant is placed on the PARTICIPANT‑BLACKLIST to prevent a denial-of-service attack.
n Same as nS.
nS Non-activity time in seconds (max. 2147483647).
nM Non-activity time in minutes (max. 35791394).
nH Non-activity time in hours (max. 596523).

See Protecting a Broker against Denial-of-Service Attacks under z/OS | Linux | Windows | BS2000.

BROKER-ID A32 R z u w b
Identifies the broker to which the attribute file applies. The broker ID must be unique per machine.

Note:
The numerical section of the BROKER-ID is no longer used to determine the DBID in the EntireX Broker kernel with Entire Net-Work transport (NET). To determine the DBID, use attribute NODE in the DEFAULTS=NET section of the attribute file.

CLIENT-NONACT 15M | n | nS | nM | nH R z u w b
Define the non-activity time for clients.
n Same as nS.
nS Non-activity time in seconds (max. 2147483647).
nM Non-activity time in minutes (max. 35791394).
nH Non-activity time in hours (max. 596523).

A client that does not issue a broker request within the specified time limit is treated as inactive and all resources for the client are freed.

CMDLOG NO | YES O z u w b
NO Command logging will not be available in the broker.
YES Command logging features will be available in the broker.
CMDLOG-FILE-SIZE 1024 | n O z u w b
Defines the maximum size of the file that the command log is written to, in kilobytes. The value must be 1024 or higher. The default value is 1024. When one command log file grows to this size, broker starts writing to the other file. For more details, see Command Logging in EntireX.
CONTROL-INTERVAL 60S | n | nS | nM | nH O z u w b
Defines the time interval of time-driven broker-to-broker calls.

  1. It controls the time between handshake attempts.

  2. The standby broker will check the status of the standard broker after the elapsed CONTROL-INTERVAL time.

n Same as nS.
nS Interval in seconds (max. 2147483647).
nM Interval in minutes (max. 35791394).
nH Interval in hours (max. 596523).
The minimum value is 16 seconds. We strongly recommend the default value (60 seconds), except for very slow machines.
CONV-DEFAULT UNLIM | n O z u w b
Default number of conversations that are allocated for every service.
UNLIM The number of conversations is restricted only by the number of conversations globally available. Precludes the use of NUM‑CONVERSATION.
n Number of conversations.

This value can be overridden by specifying a CONV-LIMIT for the service.
A value of 0 (zero) is invalid.

DEFERRED NO | YES O z u w b
Disable or enable deferred processing of units of work.
NO Units of work cannot be sent to the service until it is available.
YES Units of work can be sent to a service that is not up and registered. They will be processed when the service becomes available.
DYNAMIC-MEMORY-MANAGEMENT YES | NO O z u w b
YES An initial portion of memory is allocated at broker startup based on defined NUM-* attributes or internal default values if no NUM-* attributes have been defined. More memory is allocated without broker restart if there is a need to use more storage. Unused memory is deallocated. The upper limit of memory consumption can be defined by the attribute MAX-MEMORY. See Dynamic Memory Management.
NO All memory is allocated at broker startup based on the calculation from the defined NUM-* attributes. Size of memory cannot be changed. This was the known behavior of EntireX 7.3 and earlier.

If you run your broker with attribute DYNAMIC-MEMORY-MANAGEMENT=YES, the following attributes are not needed:

  • CONV-DEFAULT

  • HEAP-SIZE

  • LONG-BUFFER-DEFAULT

  • SERVER-DEFAULT

  • SHORT-BUFFER-DEFAULT

  • NUM-CLIENT

  • NUM-CMDLOG-FILTER

  • NUM-COMBUF

  • NUM-CONV[ERSATION]

  • NUM-LONG[-BUFFER]

  • NUM-SERVER

  • NUM-SERVICE-EXTENSION

  • NUM-SERVICE

  • NUM-SHORT[-BUFFER]

  • NUM-UOW|MAX-UOWS|MUOW

  • NUM-WQE

Caution:
However, if one of these attributes is defined, it determines the allocation size of that particular broker resource.

DYNAMIC-WORKER-MANAGEMENT NO | YES O z u w b
NO All worker tasks are started at broker startup. The number of worker tasks is defined by NUM-WORKER. After this initial step, no further worker tasks can be started. This is default and simulates the behavior of EntireX version 8.0 and earlier.
YES As above, the initial portion of worker tasks started at broker startup is determined by NUM-WORKER. However, if there is a need to handle an increased workload, additional worker tasks can be started at runtime without restarting broker. Conversely, if a worker task remains unused, it is stopped. The upper and lower limit of running worker tasks can be defined by the attributes WORKER-MIN and WORKER-MAX.

If you run broker with DYNAMIC-WORKER-MANAGEMENT=YES, the following attributes are useful to optimize the overall processing:

The attribute NUM-WORKER defines the initial number of worker tasks started during initialization. See Dynamic Worker Management.

ETBCOM NO | YES O z u w  
YES | NO O       b
Bundles the output of the various broker tasks in task ETBCOM.
HEAP-SIZE 1024 | n O z u w b
Defines the size of the internal heap in KB. Not required if you are using DYNAMIC‑MEMORY‑MANAGEMENT. If you are not using dynamic memory management, we strongly recommend specifying - as a minimum - the default value of 1024 KB.
ICU-CONVERSION YES | NO O z u w b
Disable or enable ICU conversion.
YES ICU is loaded and available for conversion. It is a prerequisite for CONVERSION=SAGTCHA and CONVERSION=SAGTRPC.
NO ICU is not loaded and not available for conversion. CONVERSION=SAGTCHA and CONVERSION=SAGTRPC cannot be used.

If any of the broker service definitions uses the character conversion approach ICU Conversion, that is, CONVERSION=SAGTCHA or CONVERSION=SAGTRPC, ICU-CONVERSION must be set to YES. If you are using only a user exit (see User Exits) or CONVERSION=NO as character conversion approach for all your broker service definitions, ICU-CONVERSION can be set to NO.

ICU requires additional storage to run properly. If ICU conversion is not needed, setting ICU-CONVERSION to NO will help to avoid unnecessary storage consumption.

IPV6 YES | NO O z u w b
YES Establish SSL and TCP/IP transport in IPv6 and IPv4 networks according to the TCP/IP stack configuration.
NO Establish SSL and TCP/IP transport in IPv4 network only.

This attribute applies to EntireX version 9.0 and above.
LONG-BUFFER-DEFAULT UNLIM | n O z u w b
Number of long buffers to be allocated for each service.
UNLIM The number of long message buffers is restricted only by the number of buffers globally available. Precludes the use of NUM‑LONG‑BUFFER.
n Number of buffers.

This value can be overridden by specifying a LONG-BUFFER-LIMIT for the service. A value of 0 (zero) is invalid.

MAX-MEMORY 0 | n | nK | nM | nG | UNLIM O z u w b
Defines the upper limit of memory allocated by broker if DYNAMIC-MEMORY-MANAGEMENT=YES has been defined.
0, UNLIM No memory limit.
others Defines the maximum limit of allocated memory. If limit is exceeded, error 671 "Requested allocation exceeds MAX-MEMORY" is generated.
MAX-MESSAGE-LENGTH 2147483647 | n O z u w b
Maximum message size that the broker kernel can process. This value is transport-dependent. The default value represents the highest positive number that can be stored in a four-byte integer.
MAX-MESSAGES-IN-UOW 16 | n O z u w b
Maximum number of messages in a unit of work.
MAX-MSG See MAX‑MESSAGE‑LENGTH.
MAX-UOW-MESSAGE-LENGTH See MAX‑MESSAGE‑LENGTH.
MAX-UOWS 0 | n O z u w b
The maximum number of UOWs that can be concurrently active broker-wide. The default value is 0 (zero), which means that the broker will process only messages that are not part of a unit of work. If UOW processing is to be done by any service, a MAX-UOWS value must be 1 or larger for the broker.

The MAX-UOWS value for the service will default to the value set for the broker. NUM‑UOW is an alias of this parameter.

MESSAGE-CASE NONE | UPPER | LOWER O z u w b
Indicates if certain error message texts returned by the broker to its clients or written by the broker to its log file are to be in mixed case, uppercase, or lowercase.
NONE No changes are made to message case.
UPPER Messages are changed to uppercase.
LOWER Messages are changed to lowercase.
MUOW See NUM‑UOW.
NEW-UOW-MESSAGES YES | NO O z u w b
YES New UOW messages are allowed.
NO New UOW messages are not allowed.

This applies to UOW when using Persistence and should not be used for non-persistent UOWs. A usage example could be the following:

The broker persistent store reaches capacity and the broker shuts down. You can set NEW-UOW-MESSAGES to NO to prevent new UOW messages from being added after a broker restart. This action allows only consumption (not production) of UOWs to occur after broker restart. After the persistent store capacity has been sufficiently reduced, the EntireX Broker administrator can issue a CIS command, see ALLOW-NEWUOWMSGS. This action allows new UOW messages to be sent to the broker. Reset attribute NEW-UOW-MESSAGES to YES, which permits new UOW messages to be produced in subsequent broker sessions.

NUM-BLACKLIST-ENTRIES 256 | n O z u w b
Number of entries in the participant blacklist. Default value is 256 entries. Together with BLACKLIST‑PENALTY‑TIME and PARTICIPANT‑BLACKLIST, this attribute is used to protect a broker running with SECURITY=YES against denial-of-service attacks. See Protecting a Broker against Denial-of-Service Attacks under z/OS | Linux | Windows | BS2000.
NUM-CLIENT n R z u w b
Number of clients that can access the broker concurrently. A value of 0 (zero) is invalid.
NUM-CMDLOG-FILTER 1 | n O z u w b
Maximum number of filters that can be specified simultaneously.

Tip:
We recommend you limit this value to the number of services that are being monitored. Minimum value is 1. A value of zero is invalid when the attribute CMDLOG is set to YES. See Command Logging in EntireX for more information.

NUM-COMBUF 1024 | 1-999999 R z u w b
Determines the maximum number of communication buffers available for processing commands arriving in the broker kernel. The size of one communication buffer is usually 16 KB split into 32 slots of 512 bytes, but it ultimately depends on the hardware architecture of your CPU. A value of 0 (zero) is invalid.
NUM-CONVERSATION or
NUM-CONV		 n | AUTO R z u w b
Defines the number of conversations that can be active concurrently. The number specified should be high enough to account for both conversational and non-conversational requests. (Non-conversational requests are treated internally as one-conversation requests.)
n Number of conversations.
AUTO Uses the CONV-DEFAULT and the service-specific CONV-LIMIT values to calculate the number of conversations.
Do not set the values used in the calculation to UNLIM.

Notes:

  1. A value of 0 (zero) is invalid. If a wildcard service is defined in the service-specific section of the attribute file, the value of AUTO is invalid.
  2. See Wildcard Service Definitions.
NUM-LONG-BUFFER or
NUM-LONG		 4096 | n | AUTO R z u w b
Defines the number of long message containers. Long message containers have a fixed length of 4096 bytes and are used to store requests that are larger than 2048 bytes. Storing a request of 8192 bytes, for example, would require two long message containers.
n Number of buffers.
AUTO Uses the LONG-BUFFER-DEFAULT and the service-specific LONG-BUFFER-LIMIT values to calculate the number of long message buffers.
Do not set the values used in the calculation to UNLIM.

A value of 0 (zero) is invalid.

In non-conversational mode, message containers are released as soon as the client receives a reply from the server. If no reply is requested, message containers are released as soon as the server receives the client request.

In conversational mode, the last message received is always kept until a new one is received.

Notes:

  1. If a catch-all service is defined in the service-specific section of the attribute file, the value of AUTO is invalid.
  2. See Wildcard Service Definitions.
NUM-PARTICIPANT-EXTENSION n O z u w b
Defines the number of participant extensions to link participants as clients and servers.
n Number of participant extensions.
not specified If this attribute is not set, the default value is calculated based on NUM-CLIENT and NUM-SERVER.

A value of 0 (zero) is invalid.
NUM-SERVER n | AUTO R z u w b
Defines the number of servers that can offer services concurrently using the broker. This is not the number of services that can be registered to the broker (see NUM‑SERVICE).
n Number of servers.
AUTO Uses the SERVER-DEFAULT and the service-specific SERVER-LIMIT values to calculate the number of servers.
Do not set the values used in the calculation to UNLIM.

Notes:

  1. Setting this value higher than the number of services allows the starting of server replicas that provide the same service.
  2. A value of 0 (zero) is invalid. If a wildcard service is defined in the service-specific section of the attribute file, the value of AUTO is invalid.
  3. See Wildcard Service Definitions.
NUM-SERVICE n R z u w b
Defines the number of services that can be registered to the broker. This is not the number of servers that can offer the services (see NUM‑SERVER). A value of 0 (zero) is invalid.
NUM-SERVICE-EXTENSION n | AUTO O z u w b
Defines the number of service extensions to link servers to services.
n Number of service extensions.
AUTO Uses the value specified or calculated for NUM-SERVER + NUM-CLIENT, plus an extra cushion.
not specified If this attribute is not set, the default value is NUM-SERVER multiplied by NUM-SERVICE.

The minimum value is NUM-SERVER.
The maximum value is NUM-SERVER multiplied by NUM-SERVICE.

Caution is recommended with this attribute:

  • Set this attribute only if the storage resources allocated for service extensions need to be restricted.

  • Note that the value n allows only the specified number of server instances of n to be used.

  • Value AUTO will calculate the number of allowed server instances from NUM-SERVER, which itself might be set to AUTO. In this case, this also considers the value of SERVER-DEFAULT and even the individual SERVER-LIMIT for each service definition.

NUM-SHORT-BUFFER or
NUM-SHORT		 n | AUTO R z u w b
Defines the number of short message containers. Short message containers have a fixed length of 256 bytes and are used to store requests of no more than 2048 bytes. To store a request of 1024 bytes, for example, would require four short message containers.
n Number of buffers.
AUTO Uses the SHORT-BUFFER-DEFAULT and the service-specific SHORT-BUFFER-LIMIT values to calculate the number of short message buffers.
Do not set the values used in the calculation to UNLIM.

Notes:

  1. In non-conversational mode, message containers are released as soon as the client receives a reply from the server. If no reply is requested, message containers are released as soon as the server receives the client request.
  2. In conversational mode, the last message received is always kept until a new one is received.
  3. If a wildcard service is defined in the service-specific section of the attribute file, the value of AUTO is invalid.
  4. See Wildcard Service Definitions.
NUM-UOW 0 | n O z u w b
The maximum number of UOWs that can be concurrently active broker-wide. The default value is 0 (zero), which means that the broker will process only messages that are not part of a unit of work. If UOW processing is to be done by any service, a NUM-UOW value must be 1 or larger for the broker. (MAX-UOWS is an alias for this attribute.)

The NUM-UOW value for the service will default to the value set for the broker.

NUM-WORKER 1 | n (max. 64) R z u w b
Number of worker tasks that the broker can use. The number of worker tasks determines the number of functions (SEND, RECEIVE, REGISTER, etc.) that can be processed concurrently. At least one worker task is required; this is the default value.
NUM-WQE 1-32768 R z u w b
Maximum number of requests that can be processed by the broker in parallel, over all transport mechanisms.

Each broker command is assigned a worker queue element, regardless of the transport mechanism being used. This element is released when the user has received the results of the command, including the case where the command has timed out.

PARTICIPANT-BLACKLIST YES | NO R z u w b
Determines whether participants attempting a denial-of-service attack on the broker are to be put on a blacklist.
YES Create a participant blacklist.
NO Do not create a participant blacklist.

See Protecting a Broker against Denial-of-Service Attacks under z/OS | Linux | Windows | BS2000.

PERCENTAGE-FOR-CONNECTION-SHORTAGE-MESSAGE 90 | 1-100 O z u w b
Broker will issue a message if the defined percentage value of TCP/IP connections (available file descriptors) is exceeded. Default is 90 percent of the available file descriptors.
PSTORE NO | HOT | COLD O z u w b
Defines the status of the persistent store at broker startup, including the condition of persistent units of work (UOWs). With any value other than NO, PSTORE-TYPE must be set.
NO No persistent store.
HOT Persistent UOWs are restored to their prior state during initialization.
COLD Persistent UOWs are not restored during initialization, and the persistent store is considered empty.

Note:
For a hot or cold start, the persistent store must be available when your broker is restarted.

PSTORE-REPORT NO | YES O z u w b
Determines whether PSTORE report is created.
NO Do not create the PSTORE report file.
YES Create the PSTORE report file.

See also Persistent Store Report.

PSTORE-TYPE DIV (z/OS) | CTREE (Linux, Windows) | ADABAS (all platforms) O z u w b
Describes the type of persistent store driver required.
DIV Data in Virtual. z/OS only, and default on this platform.
CTREE c-tree database. Linux and Windows only. See
ADABAS Adabas. All platforms. See also Adabas-specific Attributes (below) and Managing the Broker Persistent Store under z/OS | Linux | Windows | BS2000.
PSTORE-VERSION 5 O z u w b
Determines the version of the persistent store. PSTORE-VERSION=5 is the only supported version since EntireX version 10.8.

Note:
To change the value of PSTORE-VERSION, the persistent store must be empty (all units of work must be consumed). If the persistent store is not empty, the start of the Broker with a changed PSTORE-VERSION may fail with error ETBE0741 or ETBM0745.

SECURITY NO | YES O z u w b
Determines whether EntireX Security is activated.
NO EntireX Security is not activated.
YES EntireX Security is activated.

See EntireX Security.

SERVER-DEFAULT n | UNLIM O z u w b
Default number of servers that are allowed for every service.
n Number of servers.
UNLIM The number of servers is restricted only by the number of servers globally available. Precludes the use of NUM-SERVER=AUTO.

This value can be overridden by specifying a SERVER-LIMIT for the service. A value of 0 (zero) is invalid.

SERVICE-UPDATES YES | NO O z u w b
Switch on/off the automatic update mode of the broker.
YES The broker reads the attribute file whenever a service registers for the first time. This allows the broker to honor modifications in the attribute file without a restart. The attribute file is read only when the first server registers for a particular service; it is not reread when a second replica is activated.
NO The attribute file is read only once during broker startup. Any changes to the attribute file will be honored only if the broker is restarted.
SHORT-BUFFER-DEFAULT UNLIM | n O z u w b
Number of short buffers to be allocated for each service.
UNLIM The number of short message buffers is restricted only by the number of buffers globally available. Precludes the use of NUM-SHORT-BUFFER=AUTO.
n Number of buffers.

This value can be overridden by specifying a SHORT-BUFFER-LIMIT for the service. A value of 0 (zero) is invalid.

STORAGE-REPORT NO | YES O z u w b
Create a storage report about broker memory usage.
NO Do not create the storage report.
YES Create the storage report.

See Storage Report.

STORE OFF | BROKER O z u w b
Sets the default STORE attribute for all units of work. This attribute can be overridden by the STORE field in the Broker ACI control block.
OFF Units of work are not persistent.
BROKER Units of work are persistent.
TRACE-LEVEL 0-4 O z u w b
The level of tracing to be performed while the broker is running.
0 No tracing. Default value.
1 Traces incoming requests, outgoing replies, resource usage and conversion errors.
2 All of trace level 1, plus all main routines executed.
3 All of trace level 2, plus all routines executed.
4 All of trace level 3, plus Broker ACI control block displays.

Trace levels 2, 3 and 4 should be used only when requested by Software AG Support.

If you modify the TRACE-LEVEL attribute, you must restart the broker for the change to take effect. For temporary changes to TRACE-LEVEL without a broker restart, use Command Central or the EntireX Broker command-line utility ETBCMD.

TRANSPORT TCP-NET | TCP | SSL | NET O z     b
TCP | SSL O   u w  
The broker transport may be specified as any combination of one or more of the following methods:
TCP TCP/IP is supported.
SSL SSL/TLS is supported.
NET Entire Net-Work is supported. This value is not supported for a broker under Linux or Windows.
Examples:

TRANSPORT=NET specifies that only the Entire Net-Work transport method will be supported by the broker.

TRANSPORT=TCP-NET specifies that both the TCP/IP and Net-Work transport methods will be supported by the broker.

TRANSPORT=TCP-SSL-NET specifies that the TCP/IP, SSL/TLS, and Entire Net-Work transport methods will be supported by the broker.

The parameters for each transport method are described in the respective section: TCP | SSL | NET.

TRAP-ERROR nnnn O z u w b
Where nnnn is the four-digit API error number that triggers the trace handler, for example 0007 (Service not registered). Leading zeros are not required. There is no default value.

See Deferred Tracing under z/OS | Linux | Windows.

TRBUFNUM n O z u w b
Changes the trace to write trace data to internal trace buffers. n is the size of the trace buffer in 64 KB units. There is no default value.
TRMODE WRAP O z u w b
Changes the trace mode. WRAP is the only possible value. This value instructs broker to write the trace buffer (see TRBUFNUM) if an event occurs. This event is triggered by a matching TRAP‑ERROR during request processing or when an exception occurs.
UMSG See MAX‑MESSAGES‑IN‑UOW.
UOW-DATA-LIFETIME 1D | nS | nM | nH | nD O z u w b
Defines the default lifetime for units of work for the service.
nS Number of seconds the UOW can exist (max. 2147483647).
nM Number of minutes the UOW can exist (max. 35791394).
nH Number of hours the UOW can exist (max. 596523).
nD Number of days the UOW can exist (max. 24855).

If the UOW is inactive - that is, is not processed within the time limit - it is deleted and given a status of TIMEOUT. This attribute can be overridden by the UWTIME field in the Broker ACI control block.

See Timeout Considerations for EntireX Broker.

UOW-MSGS See MAX‑MESSAGES‑IN‑UOW.
UOW-STATUS-LIFETIME no value | n[S] | nM | nH | nD O z u w b
The value to be added to the UOW‑DATA‑LIFETIME (lifetime of associated UOW). If a value is entered, it must be 1 or greater; a value of 0 will result in an error. If no value is entered, the lifetime of the UOW status information will be the same as the lifetime of the UOW itself.
nS Number of seconds the UOW status exists longer than the UOW itself (max. 2147483647).
nM Number of minutes (max. 35791394).
nH Number of hours (max. 596523).
nD Number of days (max. 24855).

This attribute is ignored if PSTORE=NO is defined.

The lifetime determines how much additional time the UOW status is retained in the persistent store and is calculated from the time at which the associated UOW enters any of the following statuses: PROCESSED, TIMEOUT, BACKEDOUT, CANCELLED, DISCARDED. The additional lifetime of the UOW status is calculated only when broker is executing. Value in UOW‑STATUS‑LIFETIME supersedes the value (if specified) in attribute UWSTATP.

Note:
If no unit is specified, the default unit is seconds. The unit does not have to be identical to the unit specified for UOW‑DATA‑LIFETIME.

UWSTAT-LIFETIME Alias for UOW‑STATUS‑LIFETIME.
UWSTATP 0 | n O z u w b
Contains a multiplier used to compute the lifetime of a persistent status for the service. The UWSTATP value is multiplied by the UOW‑DATA‑LIFETIME value (the lifetime of the associated UOW) to determine the length of time the status will be retained in the persistent store.
0 The status is not persistent.
1-254 Multiplied by the value of UOW-DATA-LIFETIME to determine how long a persistent status will be retained.

Note:
This attribute has not been supported since EntireX version 7.3. Use UOW‑STATUS‑LIFETIME instead.

UWTIME Alias for UOW‑DATA‑LIFETIME.
WAIT-FOR-ACTIVE-PSTORE NO | YES O z u w b
Determines whether broker should wait for the Adabas Persistent Store to become active, or until c-tree PSTORE files become available.
NO If broker should start with a PSTORE-TYPE=ADABAS and the database is not active or is not accessible, broker will stop.

If broker should start with a PSTORE-TYPE=CTREE and the c-tree files are still in use, broker will stop.

YES If broker should start with a PSTORE-TYPE=ADABAS and the database is not active or is not accessible, broker will retry every 10 seconds to initiate communications with the PSTORE. Broker will reject any user requests until it is able to contact the Adabas database.

If broker should start with a PSTORE-TYPE=CTREE and the c-tree files are still in use, broker will retry every 10 seconds to rebuild the persistent data. Broker will reject any user requests until it is able to rebuild the persistent data.

WORKER-MAX 64 | n (min. 1, max. 64) O z u w b
Maximum number of worker tasks the broker can use.
WORKER-MIN 1 | n (min. 1, max. 64) O z u w b
Minimum number of worker tasks the broker can use.
WORKER-NONACT 70S | n | nS | nM | nH O z u w b
Non-activity time to elapse before a worker tasks is stopped.
n Same as nS.
nS Non-activity time in seconds (default 70, max. 2147483647).
nM Non-activity time in in minutes (max. 35791394).
nH Non-activity time in hours (max. 596523).

Caution:
A value of 0 (zero) is invalid. If you set this value too low, additional overhead is required for starting and stopping worker tasks. The default and recommended value is 70S.

WORKER-QUEUE-DEPTH 1 | n (min. 1) O z u w b
Number of unassigned user requests in the input queue before another worker task gets started. The default and recommended value is 1. A higher value will result in longer broker response times.
WORKER-START-DELAY internal-value | n O z u w b
n Delay is extended by n seconds.

Delay after a successful worker task invocation before another worker task can be started to handle current incoming workload. This attribute is used to avoid the risk of recursive invocation of worker tasks, because starting a worker task itself causes workload increase.

If no value is specified, an internal value calculated by the broker is used to optimize dynamic worker management. This calculated value is the maximum time required to start a worker task.

Service-specific Attributes

Each section begins with the keyword DEFAULTS=SERVICE. Services with common attribute values can be grouped together. The attributes defined in the grouping apply to all services specified within it. However, if a different attribute value is defined immediately following the service definition, that new value applies. See also the sections Wildcard Service Definitions and Service Update Modes below the table.

Attribute Values Opt/
Req 		Operating System
z/OS Linux Windows BS2000
APPLICATION-MONITORING
or
APPMON		 YES | NO O z u w b
YES Enable application monitoring for the specified services.
NO Disable application monitoring for the specified services.

See Application Monitoring.

APPLICATION-MONITORING-NAME
or
APPMON-NAME		 A100 O z u w b
Specifies the application monitoring name. Used to set the value of the ApplicationName KPI.

If omitted, the default value from the APPLICATION-MONITORING section is used. If this value is also not specified, the corresponding CLASS/SERVER/SERVICE names are used.

See Application Monitoring.

CLASS A32 (case-sensitive) R z u w b
Part of the name that identifies the service together with the SERVER and SERVICE attributes. CLASS must be specified first, followed immediately by SERVER and SERVICE. The following rules apply:

  • Classes starting with any of the following are reserved for use by Software AG. Do not use these in applications you write: BROKER, SAG, ENTIRE, ETB, RPC, ADABAS, NATURAL.

  • Valid characters for class name are letters a-z, A-Z, numbers 0-9, hyphen and underscore.

  • Do not use dollar, percent, period or comma.

See also the restriction for SERVICE attribute names.

CLIENT-RPC-AUTHORIZATION N | Y O z     b
Determines whether this service is subject to RPC authorization checking.
N No RPC authorization checking is performed.
Y RPC library and program name are appended to the authorization check performed by EntireX Security. Specify YES only to RPC-supported services.

To allow conformity with Natural Security, the CLIENT-RPC-AUTHORIZATION parameter can optionally be defined with a prefix character as follows: CLIENT-RPC-AUTHORIZATION=(YES,<prefix-character>).

CONV-LIMIT UNLIM | n O z u w b
Allocates a number of conversations especially for this service.
UNLIM The number of conversations is restricted only by the number of conversations globally available. Precludes the use of NUM-CONVERSATION=AUTO in the Broker section of the attribute file.
n Number of conversations.

A value of 0 (zero) is invalid.
If NUM-CONVERSATION=AUTO is specified in the Broker section of the attribute file, CONV-LIMIT=UNLIM is not allowed in the service section. A value must be specified or the CONV-LIMIT attribute must be suppressed entirely for the service so that the default (CONV-DEFAULT) becomes active.

CONV-NONACT 5M | n | nS | nM | nH R z u w b
Non-activity time for connections.
n Same as nS.
nS Non-activity time in seconds (max. 2147483647).
nM Non-activity time in minutes (max. 35791394).
nH Non-activity time in hours (max. 596523).

A value of 0 (zero) is invalid. If a connection is not used for the specified time, that is, a server or a client does not issue a broker request that references the connection in any way, the connection is treated as inactive and the allocated resources are freed.

CONVERSION A255

( SAGTCHA [, TRACE=n] [, OPTION=s] |
  SAGTRPC [, TRACE=n] [, OPTION=s] |
  name [, TRACE=n] |
  NO )

 O z u w b
Defines ICU conversion or SAGTRPC user exit for character conversion. See Internationalization with EntireX.
SAGTCHA (1) Conversion using ICU Conversion for ACI-based Programming.
SAGTRPC (2) Conversion using ICU Conversion for RPC-based Components and Reliable RPC.
name (3) Name of the SAGTRPC user exit for RPC-based components and Reliable RPC. See also Configuring SAGTRPC User Exits under z/OS | Linux | Windows and Writing SAGTRPC User Exits under z/OS | Linux | Windows.
NO If conversion is not to be used, either omit the CONVERSION attribute or specify CONVERSION=NO, for example for binary payload.

The CONVERSION attribute overrides the TRANSLATION attribute when defined for a service. That is, when TRANSLATION and CONVERSION are both defined, TRANSLATION will be ignored.

Notes:

  1. See also Configuring ICU Conversion under z/OS | Linux | Windows | BS2000.
  2. SAGTRPC is not supported on BS2000. For conversion with single-byte code pages, use SAGTCHA on BS2000 for RPC-based Components and Reliable RPC.
  3. SAGTRPC user exit is not supported on BS2000.
TRACE

If tracing is switched on, the trace output is written to the broker log file. The following trace levels are available:

0 No tracing  
1 STANDARD This level is an "on-error" trace. It provides information on conversion errors only. For RPC calls this includes the IDL library, IDL program and the data. Note that if OPTION Values for Conversion are set, errors are ignored.
2 ADVANCED Tracing of incoming, outgoing parameters and the payload.
3 SUPPORT This trace level is for support diagnostics. Use only when requested by Software AG Support.

OPTION

See table of possible values under OPTION Values for Conversion.

DEFERRED NO | YES O z u w b
NO Units of work cannot be sent to the service until it is available.
YES Units of work can be sent to a service that is not up and registered. The units of work will be processed when the service becomes available.
LOAD-BALANCING YES | NO O z u w b
YES When servers that offer a particular service are started, new conversations will be assigned to these servers in a round-robin fashion. The first waiting server will get the first new conversation, the second waiting server will get the second new conversation, and so on.
NO A new conversation is always assigned to the first server in the queue.
LONG-BUFFER-LIMIT UNLIM | n O z u w b
Allocates a number of long message buffers for the service.
UNLIM The number of long message buffers is restricted only by the number of buffers globally available. Precludes the use of NUM-LONG-BUFFER=AUTO in the Broker section of the attribute file.
n Number of long message buffers.

A value of 0 (zero) is invalid. If NUM-LONG-BUFFER=AUTO is specified in the Broker section of the attribute file, LONG-BUFFER-LIMIT=UNLIM is not allowed in the service section. A value must be specified or the LONG-BUFFER-LIMIT attribute must be suppressed entirely for the service so that the default (LONG-BUFFER-DEFAULT) becomes active.

MAX-MESSAGES-IN-UOW 16 | n O z u w b
Maximum number of messages in a UOW.
MAX-MESSAGE-LENGTH 2147483647 | n O z u w b
Maximum message size that can be sent to a service.

This is transport-dependent. The default value represents the highest positive number that can be stored in a four-byte integer.
MAX-MSG See MAX‑MESSAGE‑LENGTH.
MAX-UOW-MESSAGE-LENGTH See MAX‑MESSAGE‑LENGTH.
MAX-UOWS 0 | n O z u w b

0 The service does not accept units of work, that is, it processes only messages that are not part of a UOW. Using zero prevents the sending of UOWs to services that are not intended to process them.
n Maximum number of UOWs that can be active concurrently for the service. If you do not provide a MAX-UOWS value for the service, it defaults to the MAX-UOWS setting for the broker. If you provide a value that exceeds that of the broker, the service MAX-UOWS is set to the broker's MAX-UOWS value and a warning message is issued.

Specify MAX-UOWS=0 for Natural RPC Servers. This restriction will be removed with a later release.

MUOW See MAX‑UOWS.
NOTIFY-EOC NO | YES O z u w b
Specifies whether timed-out conversations are to be stored or discarded.
NO Discard the EOC notifications if the server is not ready to receive.
YES Store the EOC notifications if the server is not ready to receive and then notify the server if possible.

If a server is not ready to receive an EOC notification, it can be stored or discarded. If it is stored, the server is notified, if possible, when it is ready to receive.

Caution:
The behavior activated by this parameter can be relied upon only during a single lifetime of the broker kernel. Specifically, conversations containing units of work, whose lifetime can span multiple broker kernel sessions, cannot be assumed to show this behavior, even with NOTIFY-EOC=YES.

NUM-UOW Alias for MAX‑UOWS.
SERVER A32 (case-sensitive) R z u w b
Part of the name that identifies the service together with the CLASS and SERVICE attributes.

CLASS must be specified first, followed immediately by SERVER and SERVICE.

Valid characters for server name are letters a-z, A-Z, numbers 0-9, hyphen and underscore. Do not use dollar, percent, period or comma.

SERVER-DEFAULT n | UNLIM O z u w b
Default number of servers that are allowed for every service.
n Number of servers.
UNLIM The number of servers is restricted only by the number of servers globally available. Precludes the use of NUM-SERVER=AUTO.

A value of 0 (zero) is invalid.

This value can be overridden by specifying a SERVER-LIMIT for the service.

SERVER-LIMIT n | UNLIM O z u w b
Allows a number of servers especially for this service.
n Number of servers.
UNLIM The number of servers is restricted only by the number of servers globally available. Precludes the use of NUM-SERVER=AUTO in the Broker section of the attribute file.

A value of 0 (zero) is invalid.

If NUM-SERVER=AUTO is specified in the Broker section of the attribute file, SERVER-LIMIT=UNLIM is not allowed in the service section. A value must be specified or the SERVER-LIMIT attribute must be suppressed entirely for the service so that the default (SERVER-DEFAULT) becomes active.

Note:
Linux and Windows: This limit also includes any attach server you are using. Make sure you increase the number by one for each attach server you use.

SERVER-NONACT 5M | n | nS | nM | nH R z u w b
Non-activity time for servers. A server that does not issue a broker request within the specified time limit is treated as inactive and all resources for the server are freed.
n Same as nS.
nS Non-activity time in seconds (max. 2147483647).
nM Non-activity time in minutes (max. 35791394).
nH Non-activity time in hours (max. 596523).

If a server registers multiple services, the highest value of all the services registered is taken as non-activity time for the server.

SERVICE A32 (case-sensitive) R z u w b
Part of the name that identifies the service together with the CLASS and SERVER attributes.

CLASS must be specified first, followed immediately by SERVER and SERVICE.

The SERVICE attribute names EXTRACTOR and DEPLOYMENT are reserved for Software AG internal use and should not be used in customer-written applications. Valid characters for service name are letters a-z, A-Z, numbers 0-9, hyphen and underscore. Do not use dollar, percent, period or comma. See also the restriction for CLASS attribute names.

SHORT-BUFFER-LIMIT UNLIM | n O z u w b
Allocates a number of short message buffers for the service.
UNLIM The number of short message buffers is restricted only by the number of buffers globally available. Precludes the use of NUM-SHORT-BUFFER=AUTO in the Broker section of the attribute file.
n Number of short message buffers.

If NUM-SHORT-BUFFER=AUTO is specified in the Broker section of the attribute file, SHORT-BUFFER-LIMIT=UNLIM is not allowed in the service section. A value must be specified or the SHORT-BUFFER-LIMIT attribute must be suppressed entirely for the service so that the default (SHORT-BUFFER-DEFAULT) becomes active.

STORE OFF | BROKER O z u w b
Sets the default STORE attribute for all units of work sent to the service.
OFF Units of work are not persistent.
BROKER Units of work are persistent.

This attribute can be overridden by the STORE field in the Broker ACI control block.

TRANSLATION NO | name (A255) O z u w b
Activates translation user exit for character conversion.
NO If translation is not to be used - for example for binary payload (broker messages) - either omit the TRANSLATION attribute or specify TRANSLATION=NO.
name Name of Translation User Exit. See also Configuring Translation User Exits under z/OS | Linux | Windows | BS2000 or Writing Translation User Exits under z/OS | Linux | Windows | BS2000.

The CONVERSION attribute overrides the TRANSLATION attribute when defined for a service; that is, when TRANSLATION and CONVERSION are both defined, TRANSLATION will be ignored.

UMSG Alias for MAX‑MESSAGES‑IN‑UOW.
UOW-DATA-LIFETIME 1D | nS | nM | nH | nD O z u w b
Defines the default lifetime for units of work for the service.
nS Number of seconds the UOW can exist (max. 2147483647).
nM Number of minutes the UOW can exist (max. 35791394).
nH Number of hours the UOW can exist (max. 596523).
nD Number of days the UOW can exist (max. 24855).

This attribute is ignored if PSTORE=NO is defined.

If the unit of work (UOW) is inactive, that is, not processed within the time limit, it is deleted and given a status of TIMEOUT. This attribute can be overridden by the UWTIME field in the Broker ACI control block.

UOW-MSGS Alias for MAX‑MESSAGES‑IN‑UOW.
UOW-STATUS-LIFETIME no value | n[S] | nM | nH | nD O z u w b
The value to be added to the UOW‑DATA‑LIFETIME lifetime of associated UOW). If a value is entered, it must be 1 or greater; a value of 0 will result in an error. If no value is entered, the lifetime of the UOW status information will be the same as the lifetime of the UOW itself.
nS Number of seconds the UOW status exists longer than the UOW itself (max. 2147483647).
nM Number of minutes (max. 35791394).
nH Number of hours (max. 596523).
nD Number of days (max. 24855).

The lifetime determines how much additional time the UOW status is retained in the persistent store and is calculated from the time at which the associated UOW enters any of the following statuses: PROCESSED, TIMEOUT, BACKEDOUT, CANCELLED, DISCARDED. The additional lifetime of the UOW status is calculated only when broker is executing. Value in UOW-STATUS-LIFETIME supersedes the value (if specified) in attribute UWSTATP.

Note:
If no unit is specified, the default unit is seconds. The unit does not have to be identical to the unit specified for UOW-DATA-LIFETIME.

UWSTATP 0 | n O z u w b
Contains a multiplier used to compute the lifetime of a persistent status for the service. The UWSTATP value is multiplied by the UOW‑STATUS‑LIFETIME value (the lifetime of the associated UOW) to determine the length of time the status will be retained in the persistent store.
0 The status is not persistent.
1 - 254 Multiplied by the value of UOW‑DATA‑LIFETIME to determine how long a persistent status will be retained.

This attribute is ignored if PSTORE=NO is defined.

Note:
This attribute has not been supported since EntireX version 7.3. Use UOW‑STATUS‑LIFETIME instead.

UWSTAT-LIFETIME Alias for UOW‑STATUS‑LIFETIME.
UWTIME Alias for UOW‑DATA‑LIFETIME.

Wildcard Service Definitions

The special names of CLASS = *, SERVER = * and SERVICE = * are allowed in the service-specific and authorization rule-specific sections of the broker attribute file. These are known as "wildcard" service definitions. If this name is present in the attribute file, any service that registers with the broker and does not have its own entry in the attribute file will inherit the attributes that apply to the first wildcard service definition found.

For example, a server that registers with CLASS=ACLASS, SERVER=ASERVER and SERVICE=ASERVICE can inherit attributes from any of the following entries in the attribute file (this list is not necessarily complete): 

CLASS = *, SERVER = ASERVER, SERVICE = ASERVICE
CLASS = ACLASS, SERVER = *, SERVICE = *
CLASS = *, SERVER = *, SERVICE = *

Of course, if there is a set of attributes that are specifically defined for CLASS=ACLASS, SERVER=ASERVER, SERVICE=ASERVICE, then all of the wildcard service definitions will be ignored in favor of the exact matching definition.

Service Update Modes

EntireX has two modes for handling service-specific attributes. See broker-specific attribute SERVICE‑UPDATES.

  • In service update mode (SERVICE-UPDATES=YES), the service configuration sections of the attribute file are read whenever the first replica of a particular service registers.

  • In non-update mode (SERVICE-UPDATES=NO), the attribute file is not reread. All attributes are read during startup and the broker does not honor any changes in the attribute file. This mode is useful if

    • there is a high frequency of REGISTER operations, or

    • the attribute file is rather large and results in a high I/O rate for the broker.

    The disadvantage to using non-update mode is that if specific attributes are modified, the broker must be restarted to effect the changes. Generally, this mode should be used only if the I/O rate of the broker is considerably high, and if the environment seldom changes.

OPTION Values for Conversion

The different option values allow you to either handle character conversion deficiencies as errors, or to ignore them:

  1. Do not ignore any character conversion errors and force an error always (value STOP). This is the default behavior.

  2. Ignore if characters cannot be converted into the receiver's codepage, but force an error if sender characters do not match the sender's codepage (value SUBSTITUTE-NONCONV).

  3. Ignore any character conversion errors (values SUBSTITUTE and BLANKOUT).

Situations 1 and 2 above are reported to the broker log file if the TRACE option for CONVERSION is set to level 1.

Value Description Options Supported for Report Situation in Broker Log File if TRACE Option for CONVERSION is set to 1
SAGTCHA SAGTRPC Bad Input Characters (Sender's Codepage) Non-convertible Characters (Receiver's Codepage)
SUBSTITUTE Substitutes both non-convertible characters (receiver's codepage) and bad input characters (sender's codepage) with a codepage-dependent default replacement character. YES YES No message. No message
SUBSTITUTE-NONCONV If a corresponding code point is not available in the receiver's codepage, the character cannot be converted and is substituted with a codepage-dependent default replacement character. Bad input characters in sender's codepage are not substituted and result in an error. YES YES Write detailed conversion error message. No message.
BLANKOUT Substitutes non-convertible characters with a codepage-dependent default replacement; blanks out the complete RPC IDL field containing one or more bad input characters. NO YES No message. No message.
STOP Signals an error on detecting a non-convertible or bad input character. This is the default behavior if no option is specified. YES YES Write detailed conversion error message. Write detailed conversion error message.

Codepage-specific Attributes

The codepage-specific attribute section begins with the keyword DEFAULTS=CODEPAGE as shown in the sample attribute file. You can use the attributes in this section to customize the broker's locale string defaults and customize the mapping of locale strings to codepages for character conversion with ICU conversion and SAGTRPC user exit. See Internationalization with EntireX for more information.

Attribute Values Opt/
Req 		Operating System
z/OS Linux Windows BS2000
DEFAULT_ASCII Any ICU converter name or alias. See also Additional Notes below. O z u w b
Customize the broker's locale string defaults by assigning the default codepage for EntireX components (client or server). See Broker's Locale String Defaults. This value is used instead of the broker's locale string defaults if

  • the calling component does not send a locale string itself, and

  • the calling component is running on an ASCII platform (Linux, Windows, etc.)

Example:

DEFAULTS=CODEPAGE
    * Broker Locale String Defaults
    DEFAULT_ASCII=windows-950

For more examples, see Configuring Broker's Locale String Defaults in the Internationalization documentation and also Additional Notes below.

DEFAULT_EBCDIC_IBM Any ICU converter name or alias O z u w b
Customize the broker's locale string defaults by assigning the default codepage for EntireX components (client or server). See Broker's Locale String Defaults. This value is used instead of the broker's locale string defaults if

  • the calling component does not send a locale string itself and

  • the calling component is running on an IBM mainframe platform

Example:

DEFAULT=CODEPAGE
    DEFAULT_EBCDIC_IBM=ibm-937

For more examples, see Configuring Broker's Locale String Defaults in the Internationalization documentation and also Additional Notes below.

DEFAULT_EBCDIC_SNI Any ICU converter name or alias. O z u w b
Customize the broker's locale string defaults by assigning the default codepage for EntireX components (client or server). See Broker's Locale String Defaults. This value is used instead of the locale string defaults if

  • the calling component does not send a locale string itself, and

  • the calling component is running on a Fujitsu EBCDIC mainframe platform (BS2000)

Example:

DEFAULT=CODEPAGE
    DEFAULT_EBCDIC_SNI= bs2000-edf03drv

For more examples, see Configuring Broker's Locale String Defaults in the Internationalization documentation and also Additional Notes below.

Additional Notes

  • Locale string matching is case insensitive when bypassing the broker's built-in mechanism, that is, when the broker examines the codepages section in the attribute file.

  • If ICU is used for character conversion and the style in not known by ICU, e.g. <ll>_<cc> etc., the name will be mapped to a suitable ICU alias. For more details on the mapping mechanism, see Broker's Built-in Locale String Mapping. For more details on ICU and ICU converter name standards, see ICU Resources.

  • If SAGTRPC user exit is used for the character conversion, we recommend assigning the codepage in the form CP<nnnnn>. To determine the number given to SAGTRPC user exit, see Broker's Built-in Locale String Mapping.

  • See CONVERSION on this page for the character conversion in use.

Adabas SVC/Entire Net-Work-specific Attributes

The Adabas SVC/Entire Net-Work-specific attribute section begins with the keyword DEFAULTS=NET as shown in the sample attribute file. The attributes in this section are needed to execute the Adabas SVC/Entire Net-Work communicator of the EntireX Broker kernel.

Note:
This section applies to mainframe platforms only. It does not apply to Linux and Windows.

Attribute Values Opt/
Req 		Operating System
z/OS Linux Windows BS2000
EXTENDED-ACB-SUPPORT NO | YES O z     b
Determines whether extended features of Adabas version 8 (or above) are supported.
NO No features of Adabas version 8 or above will be used.
YES Informs broker kernel to provide Adabas/WAL version 8 transport capability. This parameter is required for sending/receiving more than 32 KB data over Adabas [NET] transport. This value should be set only if you have installed Adabas/WAL version 8, Adabas SVC, and included Adabas/WAL version 8 load libraries into the steplib of broker kernel; otherwise, unpredictable results can occur.
FORCE NO | YES O z     b
Determines whether DBID table entries can be overwritten.
NO Overwrite of DBID table entries not permitted.
YES Overwrite of DBID table entries permitted. This is required when the DBID table entry is not deleted after abnormal termination.

Caution:
Overwriting an existing entry prevents any further communication with the overwritten node. Use FORCE=YES only if you are absolutely sure that no target node with that DBID is active.

IDTNAME idtname (A8) | ADABAS5B O       b
If an ID table name is specified with the appropriate ADARUN parameter for Entire Net-Work, Adabas or Natural, the same name must be specified here. The ID table is used to perform various internal functions, including communication between the caller program and the EntireX Broker. Only supported under BS2000.
IUBL 8000 | n O z     b
This parameter sets the maximum length (in bytes) of the buffer that can be passed from the caller to EntireX Broker. The maximum size of IUBL is the same as the maximum value of the Adabas parameter LU. See the Adabas Operations Manual.

IUBL must be large enough to hold the maximum send-length plus receive-length required for any caller program plus any administrative overhead for Adabas and Entire Net-Work control structures.

LOCAL NO | YES O z     b
For remote nodes accessed via Entire Net-Work, the attribute LOCAL specifies whether the target ID defined with the NODE attribute can be accessed only locally, or also remotely.
NO DBID is global and can be accessed from remote nodes via Entire Net-Work.
YES DBID is local and cannot be accessed from remote nodes via Entire Net-Work.
MAX-MESSAGE-LENGTH 2147483647 | n O z u w b
Maximum message size that the broker kernel can process using transport method NET. The default value represents the highest positive number that can be stored in a four-byte integer.
NABS 10 | n O z     b
The number of attached buffers to be used (max. 524287).

An attached buffer is an internal buffer used for interprocess communication. An attached buffer pool equal to the NABS value multiplied by 4096 will be allocated. This buffer pool must be large enough to hold all data (IUBL) of all parallel calls to EntireX Broker.

The following formula can be used to calculate the value for NABS:
NABS = NCQE *IUBL / 4096.

NCQE 10 | n O z     b
NCQE defines the number of command queue elements which are available for processing commands arriving at the broker kernel over Adabas SVC / Net-Work transport mechanism. Sufficient NCQE should be allocated to allow this transport mechanism to process multiple broker commands concurrently. Each command queue element requires 192 bytes, and the element is released when either the user (client or server) has received the results of the command, or if the command is timed out.

The number of command queue elements required to handle broker calls depends on the number of parallel active broker calls that are using the transport mechanism Adabas SVC / Entire Net-Work. For example, all broker commands issued by client or server components using this transport mechanism:

NODE 1-65534 R z     b
Defines the unique DBID for EntireX Broker.

Used for internode Adabas/Entire Net-Work communication. There is no default; the value of NODE must be a value greater than or equal to 1 or less than or equal to 65534. If you set the parameter LOCAL=YES, you can use the same node number for different installations of EntireX Broker in an Entire Net-Work environment.

TIME 30 | n O z     b
This parameter sets the timeout value for broker calls in seconds. The results of a broker call must be received by the caller within this time limit.
TRACE-LEVEL 0-4 O z     b
The level of tracing to be performed while the broker is running with transport method NET. It overrides the global value of trace level for all NET routines.
0 No tracing. Default value.
1 Display invalid Adabas commands.
2 All of trace level 1, plus errors if request entries could not be allocated.
3 All of trace level 2, plus all routines executed.
4 All of trace level 3, plus function arguments and return values.

Trace levels 2, 3 and 4 should be used only when requested by Software AG Support.

If you modify the TRACE-LEVEL attribute, you must restart the broker for the change to take effect. For temporary changes to TRACE-LEVEL without a broker restart, use the EntireX Broker command-line utility ETBCMD.

Security-specific Attributes

The security-specific attribute section begins with the keyword DEFAULTS=SECURITY as shown in the sample attribute file. This section applies only if broker-specific attribute SECURITY=YES is specified.

Attribute Values Opt/
Req 		Operating System
z/OS Linux Windows BS2000
ACCESS-SECURITY-SERVER NO | YES O       b
Determines where authentication is checked.
NO Authentication is checked in the broker tasks. This requires broker to be running under TSOS in order to execute privileged security checks.
YES Authentication is checked in the EntireX Broker Security Server for BS2000. This does not require broker to be running under TSOS. See EntireX Broker Security Server for BS2000.
IGNORE-STOKEN NO | YES O z u w b
Determines whether the value of the ACI field SECURITY-TOKEN is verified on each call.
SECURITY-LEVEL AUTHORIZATION | AUTHENTICATION O z u w b
Specifies the mode of operation.
AUTHORIZATION Authorization and authentication (not under BS2000).
AUTHENTICATION Authentication.

Note:
In version 8.0, the default value for this parameter was AUTHORIZATION.

SECURITY-SYSTEM OS | LDAP O z u w b
OS Authentication is performed against the local operating system. Default if SECURITY=YES is specified and section DEFAULTS=SECURITY is omitted from the attribute file.
LDAP Authentication and authorization are performed against the LDAP repository(not applicable to z/OS and BS2000).
TRACE-LEVEL 0-4 O z u w b
Trace level for EntireX Security. It overrides the global value of trace level in the attribute file.
0 No tracing. Default value.
1 Log security violations and access denied/permitted.
2 All of trace level 1, plus internal errors.
3 All of trace level 2, plus function entered/exit messages with argument values and some progress messages.
4 All of trace level 3, plus some selected data areas for problem analysis.

Trace levels 2, 3 and 4 should be used only when requested by Software AG Support.

If you modify the TRACE-LEVEL attribute, you must restart the broker for the change to take effect. For temporary changes to TRACE-LEVEL without a broker restart, use the EntireX Broker command-line utility ETBCMD.

Note:
Setting this value also affects tracing for authorization rules.

TCP/IP-specific Attributes

The TCP/IP-specific attribute section begins with the keyword DEFAULTS=TCP as shown in the sample attribute file. It contains attributes that apply to the TCP/IP transport communicator. The transport is activated by TRANSPORT=TCP in the Broker-specific section of the attribute file. A maximum of five TCP/IP communicators can be activated by specifying up to five HOST/PORT pairs.

Attribute Values Opt/
Req 		Operating System
z/OS Linux Windows BS2000
CONNECTION-NONACT n | nS | nM | nH O z u w b
Non-activity of the TCP/IP connection, after which a close is performed and the connection resources are freed. If this parameter is not specified here, broker will close the connection only when the application (or the network itself) terminates the connection.
n Same as nS.
nS Non-activity time in seconds (min. 600, max. 2147483647).
nM Non-activity time in minutes (min. 10, max. 35791394).
nH Non-activity time in hours (max. 596523).

If not specified, the connection non-activity is not monitored by the broker. On the stub side, non-activity can be set with the environment variable ETB_NONACT. See Limiting the TCP/IP Connection Lifetime under z/OS | Linux | Windows | z/VSE. Both sides (the stub side and the broker kernel side) act independently of each other.

HOST 0.0.0.0 | hostname | IP address O z u w b
The address of the network interface on which broker will listen for connection requests.

If HOST is not specified, broker will listen on any attached interface adapter of the system (or stack).

A maximum of five HOST/PORT pairs can be specified to start multiple instances of broker's TCP/IP transport communicator.

MAX-MESSAGE-LENGTH 2147483647 | n O z u w b
Maximum message size that the broker kernel can process using transport method TCP/IP. The default value represents the highest positive number that can be stored in a four-byte integer.
PORT 1025-65535 O z u w b
The TCP/IP port number on which the broker will listen for connection requests.

If not specified, the broker will attempt to find its TCP/IP port number from the TCP/IP services file, using getservbyname. If it cannot find the number here, the default value of 1971 is used.

A maximum of five HOST/PORT pairs can be specified to start multiple instances of broker's TCP/IP transport communicator.

Example for multiple ports on z/OS:

HOST=localhost,PORT=3930
HOST=0.0.0.0,PORT=3931

  • Port 3930 is used for local TCP/IP communication only and is not visible outside the z/OS host.

  • Port 3931 is used for global TCP/IP communication. With IBM's AT-TLS this port is turned into a TLS port, see Running Broker with SSL/TLS Transport in the z/OS Administration documentation.

With this configuration you can reach the broker from outside the z/OS host via the secure TLS connection only (port 3931). The TCP connection (port 3930) can only be used from inside the z/OS host.

RESTART YES | NO O z u w b
YES The broker kernel will attempt to restart the TCP/IP communicator.
NO The broker kernel will not try to restart the TCP/IP communicator.

This setting applies to all TCP/IP communicators.
RETRY-LIMIT 20 | n | UNLIM O z u w b
Maximum number of attempts to restart the TCP/IP communicator. This setting applies to all TCP/IP communicators.
RETRY-TIME 3M | n | nS | nM | nH O z u w b
Wait time between stopping the TCP/IP communicator due to an unrecoverable error and the next attempt to restart it.
n Same as nS.
nS Wait time in seconds (max. 2147483647).
nM Wait time in minutes (max. 35791394).
nH Wait time in hours (max. 596523).

Minimum wait time is 1S.

This setting applies to all TCP/IP communicators.
REUSE-ADDRESS YES | NO O z u   b
YES | NO O     w  
YES The TCP port assigned to the broker can be taken over and assigned to other applications (this is the default value on all non-Windows platforms).
NO The TCP port assigned to the broker cannot be taken over and assigned to other applications. This is the default setting on Windows, and we strongly advise you do not change this value on this platform.
Note:
This setting might be required at your site when restarting broker immediately after stopping it. This is due to the inherent latency of the TCP/IP stack when closing connections.
TRACE-LEVEL 0-4 O z u w b
The level of tracing to be performed while the broker is running with transport method TCP/IP. It overrides the global value of trace level for all TCP/IP routines.
0 No tracing. Default value.
1 Display IP address of incoming request, display error number of outgoing error responses.
2 All of trace level 1, plus errors if request entries could not be allocated.
3 All of trace level 2, plus all routines executed.
4 All of trace level 3, plus function arguments and return values.

Trace levels 2, 3 and 4 should be used only when requested by Software AG Support.

If you modify the TRACE-LEVEL attribute, you must restart the broker for the change to take effect. For temporary changes to TRACE-LEVEL without a broker restart, use the EntireX Broker command-line utility ETBCMD.

SSL/TLS-specific Attributes

The Broker can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. RPC-based clients and servers, as well as ACI clients and servers, are always SSL clients. The broker is always the SSL server. For an introduction see SSL/TLS, HTTP(S), and Certificates with EntireX. Your operating system determines whether this section of the attribute file is required:

  • z/OS
    The SSL-specific attribute section is not used. You can use IBM's Application Transparent Transport Layer Security (AT-TLS).
    See Running Broker with SSL/TLS Transport in the z/OS Administration documentation.

  • Linux and Windows
    The SSL-specific attribute section is required, and begins with the keyword DEFAULTS=SSL as shown in the sample attribute file.
    The attributes in this section are needed to execute the SSL communicator of the EntireX Broker kernel.
    See also Running Broker with SSL/TLS Transport under Linux | Windows.

Attribute Values Opt/
Req 		Operating System
z/OS Linux Windows BS2000
CIPHER-SUITE string O   u w b
String that is passed to the underlying SSL/TLS implementation. SSL/TLS is a standardized protocol that uses different cryptographic functions (hash functions, symmetric and asymmetric encryption etc.). Some of these must be implemented in the SSL/TLS stack; others are optional. When an SSL/TLS connection is created, both parties agree by "handshake" on the cipher suite, that is, the algorithms and key lengths used. In a default scenario, this information depends on what both sides are capable of. It can be influenced by setting the attribute CIPHER-SUITE for the SSL/TLS server side (the broker always implements the server side). Thus stubs connect to the broker and thereby become the SSL/TLS clients.

Under Linux, Windows and BS2000, the OpenSSL implementation is used.

The SSL protocol is obsolete. It is no longer available. The TLS protocol is the successor of SSL and is readily available in OpenSSL.

The default OpenSSL configuration uses FIPS 140-2 approved cipher suites, eligible for TLS v1.2, but without anonymous Diffie-Hellman (ADH) and pre-shared key (PSK) algorithms. The resulting set of cipher suites provides for authentication and strong encryption: 

CIPHER-SUITE=FIPS+TLSv1.2:!ADH:!PSK:@STRENGTH

See https://www.openssl.org/docs/man1.1.1/man1/ciphers.

CONNECTION-NONACT n | nS | nM | nH O   u w b
Non-activity of the SSL connection, after which a close is performed and the connection resources are freed. If this parameter is not specified here, broker will close the connection only when the application (or the network itself) terminates the connection.
n Same as nS.
nS Non-activity time in seconds (min. 600, max. 2147483647).
nM Non-activity time in minutes (min. 10, max. 35791394).
nH Non-activity time in hours (max. 596523).

If not specified, the connection non-activity is not monitored by the broker. On the stub side, non-activity can be set with the environment variable ETB_NONACT. See Limiting the TCP/IP Connection Lifetime under z/OS | Linux | Windows | z/VSE. Both sides (the stub side and the broker kernel side) act independently of each other.

HOST 0.0.0.0 | hostname | IP address O   u w b
The address of the network interface on which broker will listen for connection requests.

If HOST is not specified, broker will listen on any attached interface adapter of the system (or stack).

A maximum of five HOST/PORT pairs can be specified to start multiple instances of EntireX Broker's TCP/IP transport communicator.

KEY-FILE filename R   u w b
File that contains the broker's private key (if not contained in KEY-STORE). For test purposes, EntireX delivers certificates for use on various platforms. See SSL/TLS Sample Certificates Delivered with EntireX.

Example for Linux and Windows: MyAppKey.pem.

Note:
EntireX Broker does not support certificates of type .jks or .p12.

KEY-PASSWD password (A32) R   u w b
Password used to protect the private key. Unlocks the KEY-FILE, for example MyAppKey.pem. Deprecated. See KEY-PASSWD-ENCRYTPED below.
KEY-PASSWD-ENCRYPTED encrypted value (A64) R   u w b
Password used to protect the private key. Unlocks the KEY-FILE, for example MyAppKey.pem. This attribute replaces KEY-PASSWD to avoid a clear-text password as attribute value. If KEY-PASSWD and KEY-PASSWD-ENCRYTPED are both supplied, KEY-PASSWD-ENCRYTPED takes precedence.

Use program etbnattr to get the encrypted password: 

etbnattr -w ssl_key_password --echo_password_only

This writes the encrypted password to standard output.
KEY-STORE filename R   u w b
SSL certificate; may contain the private key. For test purposes, EntireX delivers certificates for use on various platforms. See SSL/TLS Sample Certificates Delivered with EntireX.

Example for Linux and Windows: ExxAppCert.pem.

Note:
EntireX Broker does not support certificates of type .jks or .p12.

MAX-MESSAGE-LENGTH 2147483647 | n O   u w b
Maximum message size that the broker kernel can process using transport method SSL. The default value represents the highest positive number that can be stored in a four-byte integer.
PORT 1025-65535 O   u w b
The SSL port number on which the broker will listen for connection requests.

If not changed, this parameter takes the standard value as specified in the sample attribute file. If the port number is not specified, the broker will use the default value of 1958.

A maximum of five HOST/PORT pairs can be specified to start multiple instances of broker's TCP/IP transport communicator.

RESTART YES | NO O   u w b
YES The broker kernel will attempt to restart the SSL communicator (this is the default value).
NO The broker kernel will not attempt to restart the SSL communicator.
RETRY-LIMIT 20 | n | UNLIM O   u w b
Maximum number of attempts to restart the SSL communicator.
RETRY-TIME 3M | n | nS | nM | nH O   u w b
Wait time between suspending SSL communication due to unrecoverable error and the next attempt to restart it.
n Same as nS.
nS Wait time in seconds (max.2147483647).
nM Wait time in minutes (max. 35791394).
nH Wait time in hours (max. 596523).

Minimum: 1S
REUSE-ADDRESS YES | NO O   u w b
YES The SSL port assigned to the broker can be taken over and assigned to other applications (this is the default value).
NO The SSL port assigned to the broker cannot be taken over and assigned to other applications.
Note:
This setting might be required at your site when restarting broker immediately after stopping it. This is due to the inherent latency of the TCP/IP stack when closing connections.
TRACE-LEVEL 0-4 O   u w b
The level of tracing to be performed while the broker is running with transport method SSL/TLS. It overrides the global value of trace level for all SSL/TLS routines.
0 No tracing. Default value.
1 Display IP address of incoming request, display error number of outgoing error responses.
2 All of trace level 1, plus errors if request entries could not be allocated.
3 All of trace level 2, plus all routines executed.
4 All of trace level 3, plus function arguments and return values.

Trace levels 2, 3 and 4 should be used only when requested by Software AG Support.

If you modify the TRACE-LEVEL attribute, you must restart the broker for the change to take effect. For temporary changes to TRACE-LEVEL without a broker restart, use the EntireX Broker command-line utility ETBCMD.

TRUST-STORE filename | keyring R   u w b
Location of the store containing certificates of trust Certificate Authorities (or CAs).

Specify the file name of the CA certificate store. Examples: EXXCACERT.PEM, C:\Certs\ExxCACert.pem
VERIFY-CLIENT NO | YES O   u w b
YES Additional client certificate required.
NO No client certificate required (default).

For more information see SSL/TLS, HTTP(S), and Certificates with EntireX.

Adabas-specific Attributes

The Adabas-specific attribute section begins with the keyword DEFAULTS = ADABAS. The attributes in this section are required if PSTORE-TYPE = ADABAS is specified. In previous versions of EntireX, these Adabas-specific attributes and values were specified in the broker-specific PSTORE‑TYPE attribute.

Attribute Values Opt/
Req 		Operating System
z/OS Linux Windows BS2000
BLKSIZE 126-20000 O z u w b
Optional blocking factor used for message data. If not specified, broker will split the message data into 2 KB blocks to be stored in Adabas records. The maximum value depends on the physical device assigned to data storage. See the Adabas documentation.

For reasons of efficiency, do not specify a BLKSIZE much larger than the actual total size of the UOW data to be written. The total UOW size is the sum of all messages in the UOW plus 41 bytes of header information. This takes effect only after COLD start.

The BLKSIZE parameter applies only for a cold start of broker; subsequently the value of BLKSIZE is taken from the last cold start.

Default value is 2000.
DBID 1-32535 R z u w b
Database ID of Adabas database where the persistent store resides.
FNR 1-32535 R z u w b
File number of broker persistent store file.
FORCE-COLD N | Y O z u w b
Determines whether a broker cold start is permitted to overwrite a persistent store file that has been used by another broker ID and/or platform.

Specify Y to allow existing information to be overwritten.

MAXSCAN 0 | n O z u w b
Limits display of persistent UOW information in the persistent store through Command and Information Services.

Default value is 1000.
OPENRQ N | Y O z u w b
Determines whether driver for Adabas persistent store is to issue an OPEN command to Adabas.
TRACE-LEVEL 0-4 O z u w b
Trace level for Adabas persistent store. It overrides the global value of trace level in the attribute file.
0 No tracing. Default value.
1 Log selected Adabas CB fields (command code, response code, subcode, ISN, additions).
2 n/a
3 All of trace level 1, plus UOWID in use for the various Adabas requests and function entered/exit mesages.
4 All of trace level 3, plus more Adabas CB fields for successful requests and returned function values.

Trace levels 2, 3 and 4 should be used only when requested by Software AG Support.

If you modify the TRACE-LEVEL attribute, you must restart the broker for the change to take effect. For temporary changes to TRACE-LEVEL without a broker restart, use the EntireX Broker command-line utility ETBCMD.

Application Monitoring-specific Attributes

The application monitoring-specific attribute section begins with the keyword DEFAULTS=APPLICATION-MONITORING. It contains attributes that apply to the application monitoring functionality. At startup time, the attributes are read if the Broker-specific attribute APPLICATION-MONITORING=YES is specified. Duplicate or missing values are treated as errors. When an error occurs, application monitoring is turned off and EntireX Broker continues execution. See Application Monitoring.

Attribute Values Opt/
Req 		Operating System
z/OS Linux Windows BS2000
APPLICATION-MONITORING-NAME or
APPMON-NAME		 A100 O z u w b
Specifies a default application monitoring name. Used to set the value of the ApplicationName KPI.
COLLECTOR-BROKER-ID A64 R z u w b
Identifies the Application Monitoring Data Collector. Has the format host_name:port_number, where
where host_name is the host where the Application Monitoring Data Collector is running, and
  port_number is the port number of the Application Monitoring Data Collector.

The default port is 57900.
TRACE-LEVEL 0-4 O z u w b
The level of tracing to be performed while the broker is running with application monitoring.
0 No tracing. Default value.
1 Display application monitoring errors.
2 All of trace level 1, plus measuring points for application monitoring.
3 All of trace level 2, plus function entered/exit messages with argument values and monitoring buffers.
4 All of trace level 3, plus returned function values.

Trace levels 2, 3 and 4 should be used only when requested by Software AG Support.

If you modify the TRACE-LEVEL attribute, you must restart the broker for the change to take effect. TRACE-LEVEL cannot be changed dynamically for application monitoring.

Variable Definition File

The broker attribute file contains the configuration of one EntireX Broker instance. In order to share attribute files between different brokers, you identify the attributes that are unique and move them to a variable definition file. This file enables you to share one attribute file among different brokers. Each broker in such a scenario requires its own variable definition file.

The following attributes are considered unique for each machine:

How you use the variable definition file will depend upon your particular needs. For instance, some optional attributes may require uniqueness - for example, DBID and FNR in DEFAULTS=ADABAS - so that you may specify the persistent store.