Quick Reference

Broker Attributes

Note:
This section lists all EntireX Broker parameters. Not all parameters are applicable to all supported operating systems.

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.

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
z/OS Member EXBATTR in the EntireX Broker source library.
UNIX File etbfile in directory <InstDir>/EntireX/config/etb/<BrokerName> (default) *
Windows File <BrokerName>.atr in directory <InstDir>\EntireX\config\etb\<BrokerName> (default) *
BS2000 File ETB-ATTR in library EXX103.JOBS.
z/VSE Library member ETBnnn.ATR, where nnn is a placeholder specifying the broker instance (e.g.nnn= the assigned broker ID).
* When starting a broker manually, name and location of the broker attribute file can be overwritten with the environment variable ETB_ATTR.

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 (UNIX 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 UNIX 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 UNIX Windows z/VSE BS2000
ABEND‑LOOP‑DETECTION YES | NO O z u w v 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 v 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 v 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 | UNIX | Windows | z/VSE | BS2000.

ACCOUNTING‑VERSION 1 | 2 | 3 | 4 | 5 O z u w v 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 v 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 earlier EntireX versions 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 v 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 v b
YES LOGON occurs automatically during the first SEND or REGISTER.
NO The application has to issue a LOGON call.
AUTOSTART NO | YES O   u w    

This attribute defines the autostart behavior of a broker.

NO Broker is not started automatically with the next system start.
YES Broker is restarted automatically with the next system start.

Note:
Prior to EntireX version 10.5 this was handled by the Broker Administration Service.

BLACKLIST‑PENALTY‑TIME 5m | n | nS | nM | nH R z u w v 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 | UNIX | Windows | z/VSE | BS2000.

BROKER‑ID A32 R z u w v 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 v 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 v 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 v 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 v 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 v 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 v 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 v 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 YES | NO O         b

Bundles the output of the various broker tasks in task ETBCOM.

FORCE NO | YES O   u      
NO Go down with error if IPC resources still exist.
YES Clean up the left-over IPC resources of a previous run.

Notes:

  1. If broker is started twice, the second instance will kill the first by removing the IPC resources.
  2. For z/OS, z/VSE and BS2000, see separate attribute FORCE under DEFAULTS=NET.
HEAP‑SIZE 1024 | n O z u w v 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 v b

Disable or enable ICU conversion. Default for z/VSE is NO; other platforms YES.

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.

ICU‑DATA‑DIRECTORY Folder or directory name in quotes. O z u w    

The location where the broker searches for ICU custom converters. See Building and Installing ICU Custom Converters under z/OS | UNIX | Windows.

ICU‑SET‑DATA‑DIRECTORY YES | NO O z u w    

Disable or enable ICU custom converter usage.

YES The broker tries to locate ICU custom converters with the mechanism defined by the platform, see Building and Installing ICU Custom Converters under z/OS | UNIX | Windows.
NO Use of ICU custom converters is not possible.
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 v 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 v 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 v 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 v b
Maximum number of messages in a UOW.
MAX‑MSG See MAX‑MESSAGE‑LENGTH.
MAX‑TRACE‑FILES 4 | n O   u w    

Defines the number of backup copies of the trace file ETB.LOG. Minimum number is 1; maximum is 999. A new trace file is allocated when the value for TRACE‑FILE‑SIZE is exceeded. These two attributes prevent a constantly growing ETB.LOG file. See Trace File Handling under UNIX | Windows.

MAX‑UOW‑MESSAGE‑LENGTH See MAX‑MESSAGE‑LENGTH.
MAX‑UOWS 0 | n O z u w v 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 v 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 v 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 v 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 | UNIX | Windows | z/VSE | BS2000.
NUM‑CLIENT n R z u w v 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 v 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 v 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 v 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. The values used in the calculation must not be set 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 v 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. The values used in the calculation must not be set 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 v 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 v 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. The values used in the calculation must not be set 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 v 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 v 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 v 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. The values used in the calculation must not be set 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 v 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. 10) R z u w v 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 v 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 v 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 | UNIX | Windows | z/VSE | BS2000.

PARTNER‑CLUSTER‑ADDRESS A32 R z u w v b

This is the address of the load/unload broker in transport-method-style. Transport methods TCP and SSL are supported. See Transport-method-style Broker ID for more details. This attribute is required if the attribute RUN-MODE is specified.

PERCENTAGE‑FOR‑CONNECTION‑SHORTAGE‑MESSAGE 90 | 1-100 O z u w v 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.
POLL YES | NO O z u   v  

In earlier EntireX versions, the maximum number of TCP/IP connections per communicator was limited; see Maximum TCP/IP Connections per Communicator for platform-specific list. With attribute POLL introduced in EntireX version 9.0, this restriction can be lifted under z/OS, UNIX and z/VSE.

NO This setting is used to run the compatibility mode in Broker. The poll() system call is not used. The limitations described under Maximum TCP/IP Connections per Communicator apply.
YES The poll() system call is used to lift the resource restrictions with select() in multiplexing file descriptor sets.

Note:
The maximum number of file descriptors per process is a hard limit that cannot be exceeded by POLL=YES.

Setting this attribute to YES increases CPU consumption. POLL=YES is only useful if

  • you need more than the maximum number of TCP/IP connections per communicator, as described under Maximum TCP/IP Connections per Communicator, and

  • this maximum number is less than the maximum number of file descriptors per process

We recommend POLL=NO to reduce CPU consumption.

PSTORE NO | HOT | COLD O z u w v 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 v 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 (UNIX, Windows) | ADABAS (all platforms) | FILE (UNIX, Windows) O z u w v b

Describes the type of persistent store driver required.

DIV Data in Virtual. z/OS only, and default on this platform. See DIV-specific Attributes below and Implementing a DIV Persistent Store under Managing the Broker Persistent Store.
CTREE c-tree database. UNIX and Windows only. See c-tree-specific Attributes and c-tree Database as Persistent Store under UNIX | Windows.
ADABAS Adabas. All platforms. See also Adabas-specific Attributes (below) and Managing the Broker Persistent Store under z/OS | UNIX | Windows | BS2000 | z/VSE.
FILE B-Tree database. UNIX and Windows only. No longer supported.
PSTORE‑VERSION 2 | 3 | 4 | 5 O z u w v b

Determines the version of the persistent store. PSTORE=COLD is not needed to upgrade the PSTORE to version 3. Any broker restart with PSTORE-VERSION=3 will upgrade the PSTORE version.

PSTORE-VERSION=3 is needed for ICU support.

The DIV PSTORE requires PSTORE-VERSION=4.

PSTORE-VERSION=5 was added in EntireX version 10.1 to support 64-bit time values on z/OS, and unique message IDs on all platforms. See Unique Message ID. PSTORE-VERSION=5 significantly improvement Adabas PSTORE performance on all platforms. We strongly recommend you use this version.

Caution:

  • If you go back to PSTORE-VERSION=2 after upgrading to PSTORE-VERSION=3, the broker will only process data previously created with version 2. No version 3 data will be accessible.

  • If you change the DIV PSTORE from version 3 to 4, perform a COLD restart for the change to take effect, or run PSTORE UNLOAD/LOAD first.

  • If you change to PSTORE-VERSION=5, perform a COLD restart for the change to take effect.

RUN‑MODE STANDARD | STANDBY | PSTORE-LOAD | PSTORE-UNLOAD O z u w v b

Determines the initial run mode of the broker.

STANDARD Default value. Normal mode.
STANDBY Deprecated. Supported for compatibility reasons.
PSTORE‑LOAD Broker will run as load broker to write Persistent Store data to a new persistent store. See also Migrating the Persistent Store.
PSTORE‑UNLOAD Broker will run as unload broker to read an existing persistent store and pass the data to a broker running in PSTORE-LOAD mode. See also Migrating the Persistent Store.
SECURITY NO | YES O z u w v 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 v 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 v 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 v 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 v 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 v 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‑DD A255 O z        

A string containing data set attributes enclosed in quotation marks. These attributes describe the trace output file and must be defined if you are using using a GDG (generation data group) as output data set. See Flushing Trace Data to a GDG Data Set under Tracing EntireX Broker.

The following keywords are supported as part of the TRACE-DD value:

  • DATACLAS

  • DCB including BLKSIZE, DSORG, LRECL, RECFM

  • DISP

  • DSN

  • MGMTCLAS

  • SPACE

  • STORCLAS

  • UNIT

Refer to your JCL Reference Manual for a complete description of the syntax.

Example:

TRACE-DD = "DSNAME=EXX.GDG,
          DCB=(BLKSIZE=1210,DSORG=PS,LRECL=121,RECFM=FB),
          DISP=(NEW,CATLG,CATLG),
          SPACE=(CYL,(100,10)),
          STORCLAS=SMS"

Note:
If you specify TRACE-DD, you must also specify TRMODE=WRAP and a value for TRBUFNUM for the setting to take effect.

TRACE‑FILE‑SIZE n | nK | nM | nG O   u w    

Defines the size of one trace file in kilobytes, megabytes or gigabytes. If this size is exceeded, a new trace file is allocated until the maximum number of trace files specified with MAX‑TRACE‑FILES is reached. There is no default value. These two parameters help prevent a constantly growing ETB.LOG file. See Trace File Handling under UNIX | Windows.

TRACE‑LEVEL 0-4 O z u w v 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     v 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 UNIX 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 | UNIX | 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 v 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 v 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 v 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 v 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 32 | n  (min. 1, max. 32) O z u w   b

Maximum number of worker tasks the broker can use.
WORKER‑MIN 1 | n (min. 1, max. 32) 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 UNIX Windows z/VSE BS2000
APPLICATION‑MONITORING or
APPMON		 YES | NO O z u w v 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 v 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 v 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.

Classes starting with any of the following are reserved for use by Software AG and should not be used in customer-written applications: 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 v 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 v 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 v 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 | UNIX | Windows and Writing SAGTRPC User Exits under z/OS | UNIX | 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 | UNIX | Windows | BS2000 | z/VSE.
  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 z/VSE and 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. Please 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 and should only be switched on when requested by Software AG support.

OPTION

See table of possible values under OPTION Values for Conversion.

DEFERRED NO | YES O z u w v 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 v 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 v 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 v 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 v b

0 The service does not accept units of work, i.e. 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 v 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.

POSTPONE‑ATTEMPTS 0 | n O z u w    

Defines the number of attempts putting a received unit of work (UOW) due to SYNCPOINT option CANCEL on the postpone queue for later processing.

0 All UOWs rejected by the receiver (SYNCPOINT option CANCEL) will be cancelled immediately. Attribute POSTPONE‑DELAY is ignored.
n Defines the number of postpone attempts that are performed instead of considering the UOW finished due to SYNCPOINT option CANCEL; the UOW will be moved to the postpone queue and the UOW status will be changed to POSTPONED. These UOWs will be delivered to the receiver when the time specified with POSTPONE‑DELAY has elapsed.

The default value is 0. See Postponing Units of Work.

POSTPONE‑DELAY 0 | n | nS | nM | nH O z u w    

The length of time a UOW is kept in status POSTPONED.

0 The postpone feature is disabled. Attribute POSTPONE‑ATTEMPTS is ignored.
nS Number of seconds the UOW stays unreadable in the postpone queue with status POSTPONED (max. 2147483647).
nM Number of minutes the UOW stays unreadable in the postpone queue with status POSTPONED (max. 35791394).
nH Number of hours the UOW stays unreadable in the postpone queue with status POSTPONED (max. 596523).
nD Number of days the UOW stays unreadable in the postpone queue with status POSTPONED (max. 24855).

The status of the UOW will be changed from POSTPONED to ACCEPTED after elapsed POSTPONE-DELAY. This delay time does not affect the UOW‑DATA‑LIFETIME. The POSTPONE-DELAY must be less than UOW-STATUS-LIFETIME in order to make the UOW receivable again.

Note:
By default, the postpone feature is disabled. However, if any value is specified, the minimum delay is 30 seconds. Any value entered that is less than 30 seconds will be increased to this value.

SERVER A32 (case-sensitive) R z u w v 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 v 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 v 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:
UNIX 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 v 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 v 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 v 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 v 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 v b

Activates translation user exit for character conversion.

NO If translation is not to be used - e.g., 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 | UNIX | Windows | BS2000 | z/VSE or Writing Translation User Exits under z/OS | UNIX | Windows | BS2000 | z/VSE.

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 v 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 v 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 v 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 UNIX Windows z/VSE BS2000
DEFAULT_ASCII Any ICU converter name or alias. See also Additional Notes below. O z u w v 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 (UNIX, 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 v 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 (z/OS, z/VSE etc.)

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 v 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.

locale‑string Any ICU converter name or alias. See also Additional Notes below. O z u w v  

Customize the mapping of locale strings to codepages and bypass the broker's locale string processing mechanism. See Broker's Locale String Processing. This is useful:

  • if the broker's locale string processing fails - i.e. leads to no codepage or to the wrong codepage - you can explicitly assign the codepage which meets your requirements.

  • if you want to install user-written ICU converters (codepages) into the broker, see Building and Installing ICU Custom Converters under z/OS | UNIX | Windows.

The attribute (locale string) is the locale string sent by your EntireX component (client or server) and the value is the codepage that you want to use in place of that locale string. In the first line of the example below, the client or server application sends ASCII as a locale string; the broker maps this to the codepage ISO 8859_1. In the same way EUC_JP_LINUX is mapped to ibm-33722_P12A-1999. All other locale strings are mapped by the broker's mapping mechanism, see Broker's Built-in Locale String Mapping. Example: 

DEFAULTS=CODEPAGE
    * Broker Locale String Codepage Assignments
    ASCII=ISO8859
    EUC_JP_LINUX=ibm-33722_P12A-1999
    * Customer-written ICU converters
    CP1140=myebcdic
    CP0819=myascii

For more examples, see Bypassing Broker's Built-in Locale String Mapping 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 UNIX and Windows.

Attribute Values Opt/
Req 		Operating System
z/OS UNIX Windows z/VSE BS2000
ADASVC nnn R z     v  

Sets the Adabas SVC number for EntireX Broker access.

The Adabas SVC is used to perform various internal functions, including communication between the caller program and EntireX Broker.

Not supported on BS2000.
EXTENDED‑ACB‑SUPPORT NO | YES O z     v 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     v 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     v 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     v 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 v 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     v 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     v 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     v 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     v 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     v 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 UNIX Windows z/VSE 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.
APPLICATION‑NAME A8 O z        

Specifies the name of the application to be checked if FACILITY-CHECK=YES is defined. In RACF, for example, an application BROKER with read permission for user DOE is defined with following commands: 

RDEFINE APPL BROKER UACC(NONE)
PERMIT BROKER CLASS(APPL) ID(DOE) ACCESS(READ)
SETROPTS CLASSACT(APPL)

See attribute FACILITY‑CHECK for more information.

AUTHORIZATION-DEFAULT YES | NO O   u w    

Determines whether access is granted to a specified service if the specified service could not be found listed in the repository of authorization rules or in section DEFAULTS=AUTHORIZATION-RULES of the attribute file.

YES Grant access.
NO Deny access.

Applies only when using EntireX Security under UNIX and Windows. Authorization rules can be stored within a repository. When an authorization call occurs, EntireX Security uses the values of this parameter to perform an access check for a particular broker instance against an (authenticated) user ID and list of rules.

See also Authorization Rules.

CHECK‑IP‑ADDRESS YES | NO O z        

Determines whether the TCP/IP address of the caller is subject to a resource check.

ERRTXT‑MODULE NA2MSG0 | NA2MSG1 | NA2MSG2 | ModuleName O z        

Specifies the name of the security error text module. Default is NA2MSG0, English messages. For instructions on how to customize messages, see Build Language-specific Messages (Optional) under Installing EntireX Security under z/OS.

FACILITY‑CHECK NO | YES O z        

It is possible to check whether a particular user is at all allowed to use an application before performing a password check. The advantage of this additional check is that when the user is not allowed to use this application, the broker returns error 00080013 and does not try to authenticate the user. Failing an authentication check may lead to the user's password being revoked; this situation is avoided if the facility check is performed first. See attribute APPLICATION‑NAME for further details.

Note:
This facility check is an additional call to the security subsystem and is executed before each authentication call.

IGNORE‑STOKEN NO | YES O z u w   b

Determines whether the value of the ACI field SECURITY-TOKEN is verified on each call.

INCLUDE‑CLASS YES | NO O z        

Determines whether the class name is included in the resource check.

INCLUDE‑NAME YES | NO O z        

Determines whether the server name is included in the resource check.

INCLUDE‑SERVICE YES | NO O z        

Determines whether the service name is included in the resource check.

LDAP-AUTHENTICATION-URL ldapUrl O   u w    

Authentication is performed against the LDAP repository specified under ldapUrl.

  • TCP
    Specify repository URL: 

    LDAP-AUTHENTICATION-URL="ldap://HostName[:PortNumber]"

  • SSL/TLS
    Specify repository URL with ldaps: 

    LDAP-AUTHENTICATION-URL="ldaps://HostName[:PortNumber]"

If no port number is specified, the default is the standard LDAP port number 389 for TCP transport. Examples for TCP and SSL/TLS:

LDAP-AUTHENTICATION-URL="ldap://myhost.mydomain.com"
LDAP-AUTHENTICATION-URL="ldaps://myhost.mydomain.com:636"
LDAP-AUTHORIZATION-URL ldapUrl O   u w    

Authorization is performed against the LDAP repository specified under ldapUrl.

  • TCP
    Specify repository URL: 

    LDAP-AUTHORIZATION-URL="ldap://HostName[:PortNumber]"

If no port number is specified, the default is the standard LDAP port number 389 for TCP transport.
Example for TCP: 

LDAP-AUTHORIZATION-URL="ldap://myhost.mydomain.com:389"

This attribute replaces the parameters host, port and protocol in the xds.ini file of EntireX version 9.10 and below.

LDAP‑AUTH‑DN authDN O   u w    

For authenticated access to the LDAP server. Specifies the DN of the user. Default value:

cn=admin,dc=software-ag,dc=de

This attribute replaces parameter authDN in the xds.ini file of EntireX version 9.10 and below.

LDAP-AUTH-PASSWD-ENCRYPTED authPass O   u w    

For authenticated access to the LDAP server. Specifies the encrypted value of the user password. Use program etbnattr to get the encrypted password: 

etbnattr –x clear_text_password –echo_password_only

This writes the encrypted password to standard output.

This attribute replaces parameter authPass in the xds.ini file of EntireX version 9.10 and below.

LDAP‑AUTHORIZATION‑RULE A32 O   u w    

List of authorization rules. Multiple sets of rules can be defined, each set is limited to 32 chars. The maximum number of LDAP-AUTHORIZATION-RULE entries in the attribute file is 16.

Applies only when using EntireX Security under UNIX or Windows and SECURITY-SYSTEM=ldapUrl. Authorization rules can be stored in an LDAP repository. When an authorization call occurs, EntireX Security uses the values of this parameter and AUTHORIZATION‑DEFAULT to perform an access check for a particular broker instance against an (authenticated) user ID and list of rules.

See also Authorization Rules.

LDAP‑BASE‑DN baseDN O   u w    

Specifies the base distinguished name of the directory object that is the root of all objects for authorization rules. Default value: 

dc=software-ag,dc=de

This attribute replaces parameter baseDN in the xds.ini file of EntireX version 9.10 and below.

LDAP-PERSON-BASE-BINDDN ldapDn O   u w    

Used with LDAP authentication to specify the distinguished name where authentication information is stored. This value is prefixed with the user ID field name (see below). Example:

LDAP-PERSON-BASE-BINDDN="cn=users,dc=mydomain,dc=com"
LDAP-REPOSITORY-TYPE OpenLDAP | ActiveDirectory | SunOneDirectory | Tivoli | Novell | ApacheDS O   u w    
Use predefined known fields for the respective repository type. Specify the repository type that most closely matches your actual repository. In the case of Windows Active Directory, the user ID is typically in the form domainName\userId.
LDAP-SASL-AUTHENTICATION NO | YES O     w    

Specifies whether or not Simple Authentication and Security Layer (SASL) is to perform the authentication check. In practice, this determines whether or not the password supplied by the user is passed in plain text between the broker kernel and the LDAP server. If SASL is activated, this implies that the password is encrypted.

NO Password is sent to LDAP server in plain text.
YES Password is sent to LDAP server encrypted.
LDAP‑USERID‑FIELD cn | uidFieldName O   u w    

Used with LDAP authentication to specify the first field name of a user in the Distinguished Name, for example:

LDAP-USERID-FIELD=uid
MAX-SAF-PROF-LENGTH 1-256 O z        

This parameter should be increased if the length of the resource checks - that is, the length of the profile comprising "<class>.<server>.<service>" - is greater than 80 bytes.

This parameter defaults to 80 if a value is not specified.
PASSWORD-TO-UPPER-CASE NO | YES O z     v  

Determines whether the password and new password are converted to uppercase before verification.

PRODUCT RACF | ACF2 | TOP-SECRET O z        

Specifies the name of the installed security product. This attribute is used to analyze security-system-specific errors. The following systems are currently supported:

ACF2 Security system ACF2 is installed.
RACF Security system RACF is installed. Default.
TOP-SECRET Security system TOP-SECRET is installed.

The default value is used if an incorrect or no value is specified.
PROPAGATE-TRUSTED-USERID YES | NO O z        

Determines whether a client user ID obtained by means of the trusted user ID mechanism is propagated to a server using the ACI field CLIENT-USERID.

SAF‑CLASS NBKSAG | SAFClassName O z        

Specifies the name of the SAF class/type used to hold the EntireX-related resource profiles.
SAF‑CLASS‑IP NBKSAG | SAFClassName O z        

Specifies the name of the SAF class/type used when performing IP address authorization checks.

SECURITY‑LEVEL AUTHORIZATION | AUTHENTICATION O z u w v b

Specifies the mode of operation.

AUTHORIZATION Authorization and authentication (not under BS2000 or z/VSE).
AUTHENTICATION Authentication.

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

SECURITY‑NODE YES | name O z        

This parameter can be used to specify a prefix that is added to all authorization checks, enabling different broker kernels, in different environments, to perform separate authorization checks according to each broker kernel. For example, it is often important to distinguish between production, test, and development environments.

YES This causes the broker ID to be used as a prefix for all authorization checks.
name This causes the actual text (maximum 8 characters) to be prefixed onto all authorization checks.

Note:
By not setting this parameter, no prefix is added to the resource check (the default behavior).

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 specified under LDAP‑AUTHENTICATION‑URL and LDAP‑AUTHORIZATION‑URL.
TRACE‑LEVEL 0-4 O z u w v 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.

TRUSTED‑USERID YES | NO O z        

Activates the trusted user ID mechanism for broker requests arriving over the local Adabas IPC mechanism.
USERID-TO-UPPER-CASE NO | YES O z     v  

Determines whether user ID is converted to uppercase before verification.

UNIVERSAL NO | YES O z        

Determines whether access to undefined resource profiles is allowed.

WARN‑MODE NO | YES O z u w   b

Determines whether a resource check failure results in just a warning or an error.

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 UNIX Windows z/VSE BS2000
CONNECTION‑NONACT n | nS | nM | nH O z u w v 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 test is disabled. 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 | UNIX | Windows | z/VSE.

HOST 0.0.0.0 | HostName | IP address O z u w v 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 v 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 v 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 v 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 v 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 v 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   v 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.
STACK‑NAME StackName O z        

Name of the TCP/IP stack that the broker is using.

If not specified, broker will connect to the default TCP/IP stack running on the machine.
TRACE‑LEVEL 0-4 O z u w v 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.

c-tree-specific Attributes

The c-tree-specific attribute section begins with the keyword DEFAULTS = CTREE. The attributes in this section are optional. This section applies only if PSTORE-TYPE = CTREE is specified.

Not available under z/OS, BS2000, z/VSE.

Attribute Values Opt/
Req 		Operating System
z/OS UNIX Windows z/VSE BS2000
COMPATIBILITY NO | YES O   u w    

Determines whether the following c-tree parameters are set:

  • COMPATIBILITY PREV610A_FLUSH

  • COMPATIBILITY FDATASYNC

  • SUPPRESS_LOG_FLUSH YES

  • PREIMAGE_DUMP YES

See your FairCom documentation for a description of these parameters.

NO The c-tree parameters listed above are not set. Default.
YES The c-tree parameters listed above are set. This provides compatibility with c-tree behavior prior to EntireX Broker 10.5.
FLUSH-DIR YES | NO O   u w    

Controls whether metadata is flushed to disk immediately after creates, renames, and deletes of transaction log files and transaction-dependent files.

YES Metadata is flushed to disk.
NO Metadata is not flushed to disk. This provides compatibility with c-tree behavior prior to EntireX Broker version 10.5. See COMPATIBILITY NO_FLUSH_DIR in the FairCom documentation for a description of this parameter.
MAXSIZE n | nM | nG O   u w    

Defines the maximum size of c-tree data files. Broker allocates one data file for control data and another data file for message data:

n Maximum size in MB.
nM Maximum size in MB.
nG Maximum size in GB.
PAGESIZE n | nK O   u w    

Determines how many bytes are available in each c-tree node. PSTORE COLD start is required after changing this value.

n Same as nK
nK PAGESIZE in KB.

The default and minimum value is 8 KB.

If PSD Reason Code = 527 is returned during UOW write processing, increase the PAGESIZE value and restart broker with PSTORE=COLD, or migrate the existing PSTORE to a new PSTORE with an increased PAGESIZE value. See Migrating the Persistent Store and define the increased PAGESIZE value for the load broker.

PATH  A255 O   u w    

Path name of the target directory for c-tree index and data files.

SYNCIO NO | YES O   u w    

Controls the open mode of the c-tree transaction log.

NO c-tree transaction log is not opened in synchronous mode. Default.
YES c-tree transaction log is opened in synchronous mode to improve data security. It may degrade performance of PSTORE operations, but offers the highest level of data security. See c-tree Database as Persistent Store under UNIX | Windows.
TRACE‑LEVEL 0-4 O   u w    

Trace level for c-tree persistent store. It overrides the global value of trace level in the attribute file.

0 No tracing. Default value.
1 Log memory allocation failures and errors during close of files.
2 n/a
3 All of trace level 1, plus UOWID in use for the various ctree requests and function entered/exit mesages.
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. 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 and Certificates with EntireX.

Your operating system and, for z/OS, the approach you use determine whether this section of the attribute file is required:

  • z/OS

    • AT-TLS
      This is the approach we recommend. IBM's Application Transparent Transport Layer Security (AT-TLS) does not require the SSL-specific attribute section.

    • Direct SSL
      For direct SSL/TLS support, the SSL-specific attribute section is required. It begins with the keyword DEFAULTS=SSL as shown in the sample attribute file.

      Note:
      Direct SSL/TLS support (using GSK) inside the Broker under z/OS will be dropped in the next version. We strongly recommend using IBM's Application Transparent Transport Layer Security (AT-TLS) instead.

    See Running Broker with SSL/TLS Transport in the z/OS Administration documentation.

  • UNIX 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 Running Broker with SSL/TLS Transport under UNIX | Windows.

  • z/VSE
    The SSL-specific attribute section is not used. You can use BSI's Automatic Transport Layer Security (ATLS). See Running Broker with SSL/TLS Transport in the z/VSE Administration documentation.

Attribute Values Opt/
Req 		Operating System
z/OS UNIX Windows z/VSE BS2000
CIPHER‑SUITE string O z 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 UNIX, Windows and BS2000, the OpenSSL implementation is used; under z/OS it is GSK.

The SSL protocol is obsolete. It is no longer available. The TLS protocol is the successor of SSL and is readily available in OpenSSL and GSK. The following examples show how to configure the available cipher suites:

  • OpenSSL
    The default 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.

  • GSK
    Default configuration: 

    CIPHER-SUITE=9F9D9E9C6B673D3C39383332352F

    This list of FIPS 140-2 approved cipher suites starts with a strong '256-bit AES in Galois Counter Mode encryption with 128-bit AEAD authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate' (9F) and ends with a relatively weak '128-bit AES encryption with SHA-1 message authentication and RSA key exchange' (2F).

    See the IBM documentation z/OS V2R3 Cryptographic Services System Secure Sockets Layer Programming, SC14-7495-30, Appendix C: Cipher Suite Definitions.

CONNECTION‑NONACT n | nS | nM | nH O z 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 test is disabled.
HOST hostname 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 EntireX Broker's TCP/IP transport communicator.

KEY‑LABEL name O z        

The label of the key in the RACF keyring that is used to authenticate the broker kernel (see also TRUST-STORE parameter).

Example: ETBCERT.

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 UNIX and Windows: MyAppKey.pem.

Note:
EntireX Broker does not support Java certificates (keystore files of type .jks).

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 file name 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 UNIX and Windows: ExxAppCert.pem.

Note:
EntireX Broker does not support Java certificates (keystore files of type .jks).

MAX‑MESSAGE‑LENGTH 2147483647 | n O z 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 z 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 example attribute file.

If the port number is not specified, the broker will use the default value of 1958.

RESTART YES | NO O z 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 z u w   b

Maximum number of attempts to restart the SSL communicator.
RETRY‑TIME 3M | n | nS | nM| nH O z 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 z 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.
STACK‑NAME name O z u w    

Name of the TCP/IP stack that the broker is using.

If not specified, broker will connect to the default TCP/IP stack running on the machine.

TRACE‑LEVEL 0-4 O z 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 file name | keyring R z u w   b

Location of the store containing certificates of trust Certificate Authorities (or CAs).

  • z/OS
    Specify the RACF keyring using the following format: [USER-ID/]RING-NAME. If no value for USER-ID is provided, the keyring is assumed to be associated with the user ID that the broker kernel is running under.

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

DIV-specific Attributes

These attributes define a persistent store that is implemented as a VSAM linear data set (LDS) accessed using Data In Virtual (DIV). This DIV persistent store is a container for units of work. The DIV-specific attribute section begins with the keyword DEFAULTS = DIV. The attributes in this section are required if PSTORE-TYPE = DIV is specified.

Note:
All attributes except the deprecated DIV were introduced with EntireX version 9.12. They replace the Format Parameters of earlier versions, which are deprecated but still supported for compatibility reasons.

Attribute Values Opt/
Req 		Operating System
z/OS UNIX Windows z/VSE BS2000
DIV A511 O z        

The VSAM persistent store parameters, enclosed in double quotes (""). The value can span more than one line.

Note:
Deprecated. This attribute is applicable only if you are supplying the persistent store parameters using Format Parameters of earlier versions. We recommend you use the attributes below that were introduced with EntireX 9.12 instead.

DATASPACE‑NAME A8 O z        

Defines the name of the dataspace that will be used to map the persistent store.

Default value is DSPSTORE.

DATASPACE‑PAGES 126-524284 O z        

Defines the size of the dataspace used to map the persistent store (size=DATASPACE-PAGES * 4 KB). We recommend using the maximum value.

Default value is 2048.
DDNAME A8 R z        

Defines the JCL DDNAME that will be used to access the persistent store.

STORE A8 R z        

Defines an internal name that is used to identify the persistent store.
TRACE‑LEVEL 0-4 O z        

Trace level for DIV. It overrides the global value of trace level in the attribute file.

0 No tracing. Default value.
1 Log selected DIV SAVE calls taking longer than 2 seconds elapsed time.
2 n/a
3 All of trace level 1, plus UOWID in use for the various DIV requests.
4 n/a

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.

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 UNIX Windows z/VSE BS2000
BLKSIZE 126-20000 O z u w v 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 v b

Database ID of Adabas database where the persistent store resides.
FNR 1-32535 R z u w v b

File number of broker persistent store file.
FORCE‑COLD N | Y O z u w v 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 v 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 v b

Determines whether driver for Adabas persistent store is to issue an OPEN command to Adabas.

SVC 200-255 R z     v  

Use this parameter to specify the Adabas SVC number to be used by the Adabas persistent store driver.
TRACE‑LEVEL 0-4 O z u w v 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 UNIX Windows z/VSE BS2000
APPLICATION‑MONITORING‑NAME or
APPMON-NAME		 A100 O z u w v b
Specifies a default application monitoring name. Used to set the value of the ApplicationName KPI.
COLLECTOR‑BROKER‑ID A64 R z u w v b
Identifies the Application Monitoring Data Collector. Has the format host_name:port_number, 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 v 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.

Authorization Rule-specific Attributes

The authorization rule-specific attribute section begins with the keyword DEFAULTS=AUTHORIZATION-RULES. It contains attributes that enhance security-related definitions. At startup time, the attributes are read if the following conditions are met:

When an error occurs, the EntireX Broker stops. See Authorization Rules.

Attribute Values Opt/
Req 		Operating System
z/OS UNIX Windows z/VSE BS2000
RULE‑NAME A32 R   u w    
Specifies a rule name. A rule is a container for a list of services and a list of client and server user IDs. All users defined in a rule are authorized to use all services defined in this rule. See example under Rules Stored in Broker Attribute File.
CLASS
SERVER
SERVICE		 A32 R   u w    
These three attributes together identify the service. CLASS must be specified first, followed immediately by SERVER and SERVICE. Wildcard Service Definitions are allowed.
CLIENT‑USER‑ID A32 R   u w    
Defines an authorized client user ID.
SERVER‑USER‑ID A32 R   u w    
Defines an authorized server user ID.

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.