Broker Attributes

Determines whether accounting records are created.

See also Accounting in EntireX Broker.

Determines whether accounting records are created.

This parameter applies when ACCOUNTING is activated.

See Application Monitoring.

Define the length of time a participant is placed on the PARTICIPANT-BLACKLIST to prevent a denial-of-service attack.

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

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.

Define the non-activity time for clients.

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.

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.

Default number of conversations that are allocated for every service.

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

Disable or enable deferred processing of units of work.

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

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

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

• WORKER-MAX

• WORKER-MIN

• WORKER-NONACT

• WORKER-QUEUE-DEPTH

• WORKER-START-DELAY

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

Notes:

1. If broker is started twice, the second instance will kill the first by removing the IPC resources.
2. For BS2000/OSD, z/OS and z/VSE, see separate attribute FORCE in section Adabas SVC/Entire Net-Work-specific Attributes.

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.

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

If any of the broker service definitions uses the internationalization approach "ICU conversion", that is, the conversion methods SAGTCHA and SAGTRPC are defined by the service-specific or topic-specific attribute CONVERSION, ICU-CONVERSION must be set to "YES". The internationalization approaches "Translation", "Translation User Exit" and "SAGTRPC User Exit" do not require ICU conversion. If all broker service definitions use these internationalization approaches, 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.

Disable or enable ICU custom converter usage. Not defined for mainframe platforms.

This attribute applies to EntireX version 9.0 and above.

Number of long buffers to be allocated for each service or topic.

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

Defines the upper limit of memory allocated by broker if DYNAMIC-MEMORY-MANAGEMENT=YES has been defined.

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

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.

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.

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.

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

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

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.

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

Defines the number of publications that can be active concurrently.

Notes:

1. A value of 0 (zero) is invalid.
2. If a wildcard topic is defined in the topic-specific section of the attribute file, the value of AUTO is invalid.

Defines the number of participant extensions to link participants as clients and servers.

A value of 0 (zero) is invalid.

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

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

Defines the number of service extensions to link servers to services.

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 (see note below).

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.

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

Defines the number of subscribers that can be active concurrently.

A value of 0 (zero) is invalid. If a wildcard topic is defined in the topic-specific section of the attribute file, the value of AUTO is invalid.

Defines the total number of subscribers that can be durably subscribed. Their subscription information is saved in the persistent store.

A value of 0 (zero) is invalid. This value must be greater than or equal to the NUM-SUBSCRIBER value. Parameter is required if SUBSCRIBER-STORE=PSTORE is defined.

Defines the number of topics that can be active in the broker. A value of 0 (zero) is invalid.

Defines the number of topic extensions to link subscribers to topics.

The minimum value is NUM-SUBSCRIBER.
The maximum value is NUM-SUBSCRIBER multiplied by NUM-TOPIC.

Caution is recommended with this attribute.

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

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

• Value AUTO calculates the number of allowed server instances from NUM-SUBSCRIBER, which itself might set to AUTO. In this case, this also considers the value of SERVER-DEFAULT and even the individual SERVER-LIMIT for each topic definition (see note below).

Defines the total number of topics for which durable subscribers are allowed.

This value must be greater than or equal to the NUM-TOPIC value. This parameter is required if SUBSCRIBER-STORE=PSTORE is defined.

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

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.

Determines whether participants attempting a denial-of-service attack on the broker are to be put on a blacklist.

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

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.

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.

Note:
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; we recommend POLL=NO to reduce CPU consumption.

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.

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

Determines whether PSTORE report is created.

See also Persistent Store Report.

Describes the type of persistent store driver required.

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. We recommended setting PSTORE-VERSION=3.

The DIV PSTORE requires PSTORE-VERSION=4.

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.

Default number of publications that are allocated for every topic.

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

Lifetime of a publication in absolute time units. Publications are retained by broker until they are either received by all subscribers or the publication lifetime has expired.

The publication lifetime is calculated even for periods of time when broker is stopped.

Determines the initial run mode of the broker.

Determines whether the EntireX Broker security exits are activated.

Broker trace reports the type of security which is active and from where the security module USRSEC is loaded:

• EntireX Security

• User-written USRSEC.

SECURITY-PATH=usersec.dll

This assumes the DLL is in the default path. Or:

SECURITY-PATH=c:\brokerexit\yoursecu.dll

If the path name contains spaces, enclose it in quotation marks. Example:

SECURITY-PATH="c:\Software AG\broker exit\yoursecu.dll"

Note:
This attribute is used only when implementing a user-written security exit.

Default number of servers that are allowed for every service.

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

Switch on/off the automatic update mode of the broker.

Number of short buffers to be allocated for each service.

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

Create a storage report about broker memory usage.

See Storage Report.

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.

Default number of subscribers that are allowed for every topic.

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

Determines whether subscriber information is stored and where.

Tip:
The subscriber store in a secondary store is no longer supported. We recommend you use the PSTORE persistent store to store your subscriber data.

Determines whether conversations with units of work remain in memory or are swapped. See also Swapping out New Units of Work.

Note:
See service-specific attribute MIN-UOW-CONVERSATIONS-IN-MEMORY for defining a minimum number of UOW conversations kept in memory to improve the performance for servers receiving new UOW conversations without waiting for swap-in of data from PSTORE. During broker restart, all new and unassigned UOW conversations remain in PSTORE only. This reduces the restart time significantly.

See also Swapping out New Units of Work.

Switch on/off automatic update of topic defaults in the broker.

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"

The level of tracing to be performed while the broker is running.

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 restarting the broker, use System Management Hub or ETBCMD.

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

The broker transport may be specified as any combination of one or more of the following methods:

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.

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.

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.

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.

See MAX-MESSAGES-IN-UOW.

See MAX-MESSAGES-IN-UOW.

The value to be added to the UWTIME (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.

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 UWSTAT-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 UWTIME.

Contains a multiplier used to compute the lifetime of a persistent status for the service. The UWSTATP value is multiplied by the UWTIME value (the lifetime of the associated UOW) to determine the length of time the status will be retained in the persistent store.

Note:
This attribute has not been supported since EntireX version 7.3. Use UWSTAT-LIFETIME instead.

Defines the default lifetime for units of work for the service.

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.

Determines whether broker should wait for the Adabas Persistent Store to become active.

Maximum number of worker tasks the broker can use.

Minimum number of worker tasks the broker can use.

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.

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.

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.

See Application Monitoring.

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.

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.

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

Allocates a number of conversations especially for this service.

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.

Non-activity time for connections.

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.

( SAGTCHA [, TRACE =n] [, OPTION =s] |

  SAGTRPC [, TRACE =n] [, OPTION =s] |

  name [, TRACE =n] |

  NO )

Defines conversion for internationalization. See Internationalization with EntireX and What is the Best Internationalization Approach to use? for help on making decisions about the internationalization approach.

Only one internationalization approach can be active at one time for a service. The CONVERSION attribute for internationalization 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/OSD | z/VSE.
2. Conversion with Multibyte, Double-byte and other Complex Codepages is not supported on BS2000. For Conversion with Single-byte Codepages, use SAGTCHA.
3. SAGTRPC user exit is not supported on z/VSE and BS2000.

If tracing is switched on, the trace output is written to the broker log file:

See table of possible values under OPTION Values for Conversion.

Enforce encryption when data is transferred between client and server.

See also ENCRYPTION-LEVEL in Broker ACI control block and Encryption under Writing Applications using EntireX Security.

Note:
The per service ENCRYPTION-LEVEL attribute is to be specified only where the broker attribute SECURITY=YES has been specified and only if you are using EntireX Security.

Allocates a number of long message buffers for the service.

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.

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.

See MAX-MESSAGE-LENGTH.

See MAX-MESSAGE-LENGTH.

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

Defines the minimum number of UOW conversations (STORE=BROKER, created by a client and finished with an EOC without being accepted by a server) kept in memory to improve the performance for servers receiving new UOW conversations without waiting for data to be swapped in from PSTORE. See also Swapping out New Units of Work.

Note:
If broker-specific attribute SWAP-OUT-NEW-UOWS is set to "NO", MIN-UOW-CONVERSATIONS-IN-MEMORY has no effect.

See MAX-UOWS.

Specifies whether timed-out conversations are to be stored or discarded.

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.

Alias for MAX-UOWS.

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.

Default number of servers that are allowed for every service.

A value of 0 (zero) is invalid.

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

Allows a number of servers especially for this service.

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.

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.

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

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.

Allocates a number of short message buffers for the service.

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.

Sets the default STORE attribute for all units of work sent to the service.

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

SAGTCHA | NO | <name>

Activates translation or translation user exit for internationalization (see Translation User Exit). For help on deciding the right internationalization approach for your environment, see What is the Best Internationalization Approach to use?

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

Alias for MAX-MESSAGES-IN-UOW.

Alias for MAX-MESSAGES-IN-UOW.

The value to be added to the UWTIME (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.

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 UWSTAT-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 UWTIME.

Contains a multiplier used to compute the lifetime of a persistent status for the service. The UWSTATP value is multiplied by the UWTIME value (the lifetime of the associated UOW) to determine the length of time the status will be retained in the persistent store.

Note:
This attribute has not been supported since EntireX version 7.3. Use UWSTAT-LIFETIME instead.

Defines the default lifetime for units of work for the service.

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.

Determines whether a subscriber is allowed to perform a durable subscription to a topic.

If users are allowed to durably subscribe to any topic, you must specify a value for the SUBSCRIBER-STORE parameter.

Determines if it is possible for a user to subscribe to a topic directly (YES) or only by Administrator.

( SAGTCHA [TRACE =n] [, OPTION =s] )

Defines conversion for internationalization. See Internationalization with EntireX. For help on making decisions about the internationalization approach, see What is the Best Internationalization Approach to use?

Only one internationalization approach can be active at one time for a topic. The CONVERSION attribute for internationalization overrides the TRANSLATION attribute when defined for a topic, that is, when TRANSLATION and CONVERSION are both defined, TRANSLATION will be ignored.

If tracing is switched on, the trace output is written to the broker log file:

See OPTION Values for Conversion under Service-specific Attributes above.

Allocates a number of long message buffers for the topic.

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 topic section. A value must be specified or the LONG-BUFFER-LIMIT attribute must be suppressed entirely for the topic so that the default (LONG-BUFFER-DEFAULT) becomes active.

Maximum number of messages in a publication.

Maximum size of a message in a publication. The actual publication size is transport-dependent.

Lifetime of a publication in absolute time units. Publications are retained by broker until they are either received by all subscribers or the publication lifetime has expired.

The publication lifetime is calculated even for periods of time when broker is stopped.

There is no default. Maximum number of publications possible for this topic. If specified, this overrides the publication default value, which is a general maximum value per topic. If neither parameter is specified, the total number of publications for the topic is limited only by NUM-PUBLICATION.

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

Non-activity of the publisher, after which an auto-logoff is performed and the publisher's resources are freed.

If not specified, defaults to 5 minutes. This is the time after which the publisher's internal memory structures will be cleaned up and a subsequent logon is required.

Allocates a number of short message buffers for the topic.

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

There is no default. Maximum number of subscriptions possible for this topic. If specified, this overrides the subscriber default value, which is a general maximum value per topic. If neither parameter is specified, the total number of subscribers for the topic is limited only by NUM-SUBSCRIBER.

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

Non-activity of the subscriber after which an auto-logoff is performed and the publisher's resources are freed.

In the case of a non-durable subscriber, the user's subscription is also cancelled. In the case of a durable subscriber, the user's subscription is persisted, and it is not necessary for the user to issue any subsequent SUBSCRIBE commands. The subscription of a durable subscriber is also persisted even while broker is stopped.

If not specified, defaults to 5 minutes. This is the time after which the subscriber's internal memory structures will be cleaned up and a subsequent logon is required.

Lifetime of a user's subscription in absolute time units. Subscriptions are retained by broker until either the user issues an UNSUBSCRIBE command or the subscription lifetime has expired.

Durable subscriptions remain effective even if the user performs the LOGOFF command or broker is stopped. The subscription lifetime is calculated also for periods of time when broker is stopped.

SUBSCRIPTION-EXPIRATION is the time after which the subscription expires. In the case of durable subscription, the subscription is removed from the PSTORE. Broker removes expired subscriptions only when the user is not currently active, for example when the user has issued a LOGOFF command or after the SUBSCRIBER-NONACT has passed if no LOGOFF is issued.

If SUBSCRIBER-NONACT is specified greater than SUBSCRIPTION-EXPIRATION, broker adjusts SUBSCRIPTION-EXPIRATION to the value of SUBSCRIBER-NONACT.

Name of the topic for publish and subscribe processing. Valid characters for topic name are letters a-z, A-Z, numbers 0-9, hyphen and underscore. Do not use dollar, percent, period or comma.

SAGTCHA | NO | <name>

Activates translation or translation user exit for internationalization (see Translation User Exit). See also What is the Best Internationalization Approach to use?

The CONVERSION attribute for internationalization overrides the TRANSLATION attribute when defined for a service, i.e. when TRANSLATION and CONVERSION are both defined, TRANSLATION will be ignored.

Customize the broker's locale string defaults by assigning the default codepage for EntireX components (client or server, publisher or subscriber). 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.), and

• one of the internationalization approaches ICU conversion or SAGTRPC user exit is used. See ICU Conversion and SAGTRPC User Exit.

Example:

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

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

Customize the broker's locale string defaults by assigning the default codepage for EntireX components (client or server, publisher or subscriber). 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.) and

• one of the internationalization approaches ICU conversion or SAGTRPC user exit is used.

Example:

DEFAULT=CODEPAGE
    DEFAULT_EBCDIC_IBM=ibm-937

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

Customize the broker's locale string defaults by assigning the default codepage for EntireX components (client or server, publisher or subscriber). 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/OSD), and

• one of the internationalization approaches ICU conversion or SAGTRPC user exit is used.

Example:

DEFAULT=CODEPAGE
    DEFAULT_EBCDIC_SNI= bs2000-edf03drv

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

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 UNIX | Windows.

The attribute (locale string) is the locale string sent by your EntireX component (client or server, publisher or subscriber) 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.

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/OSD.

Determines whether extended features of Adabas version 8 (or above) are supported.

Determines whether DBID table entries can be overwritten.

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.

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.

Specifies whether the broker ID is local.

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.

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 any of the following application components using this transport mechanism:

• clients

• servers

• publishers

• subscribers

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.

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.

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.

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 restarting the broker, use System Management Hub or ETBCMD.

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

Determines where authentication is checked.

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.

• TCP
  Specify repository URL:
  AUTHENTICATION-TYPE="ldap://HostName[:PortNumber]"

• SSL/TLS
  Specify repository URL with ldaps:
  AUTHENTICATION-TYPE="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:
AUTHENTICATION-TYPE="ldap://myhost.mydomain.com"
AUTHENTICATION-TYPE="ldaps://myhost.mydomain.com:636"

Determines whether access is granted to a specified service if the specified could not be found listed in the repository of authorization rules.

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 and AUTHORIZATIONDEFAULT to perform an access check for a particular broker instance against an (authenticated) user ID and list of rules.

See also Administering Authorization Rules using System Management Hub under UNIX | Windows.

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

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

See also Administering Authorization Rules using System Management Hub under UNIX | Windows.

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

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.

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.

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

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

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

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

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"

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.

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

LDAP-USERID-FIELD=uid

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.

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

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

The default value is used if an incorrect or no value is specified.

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.

Specifies the name of the SAF class/type used to hold the EntireX-related resource profiles.

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

Specifies the mode of operation.

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

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.

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

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

Activates the trusted user ID mechanism for broker requests arriving over the local Adabas IPC mechanism.

Determines whether user ID is converted to uppercase before verification.

Determines whether access to undefined resource profiles is allowed.

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

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.

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.

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.

The TCP/IP port number on which the broker will listen for connection requests.

If specified, PORT overrides broker attribute TCPPORT.

Note:
TCPPORT will be retired with the next version.

If PORT is not specified but TCPPORT is specified, TCPPORT is used.

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

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

If specified, RESTART overrides broker attribute TCP-RESTART.

Note:
TCP-RESTART will be retired with the next version.

If RESTART is not specified but TCP-RESTART is specified, TCP-RESTART is used.

The RESTART setting applies to all TCP/IP communicators.

Maximum number of attempts to restart the TCP/IP communicator.

If specified, RETRY-LIMIT overrides broker attribute TCP-RETRY-LIMIT.

Note:
TCP-RETRY-LIMIT will be retired with the next version.

If RETRY-LIMIT is not specified but TCP-RETRY-LIMIT is specified, TCP-RETRY-LIMIT is used.

The RETRY-LIMIT setting applies to all TCP/IP communicators.

Wait time between stopping the TCP/IP communicator due to an unrecoverable error and the next attempt to restart it.

Minimum wait time is 1S.

If specified, RETRY-TIME overrides broker attribute TCP-RETRY-TIME.

Note:
TCP-RETRY-TIME will be retired with the next version.

If RETRY-TIME is not specified but TCP-RETRY-TIME is specified, TCP-RETRY-TIME is used.

The RETRY-TIME setting applies to all TCP/IP communicators.

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.

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.

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 restarting the broker, use System Management Hub or ETBCMD.

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

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

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

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 name of the target directory for c-tree index and data files.

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

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

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/OSD, the OpenSSL implementation is used; under z/OS it is GSK.

The SSL protocol is obsolete and should no longer be used for secure operations. The TLS protocol is the successor of SSL and is readily available in OpenSSL and GSK. The following examples show how to configure strong encryption:

• OpenSSL
  This example uses FIPS-approved algorithms, but without ADH, MD5 or other low or export-grade implementations.
  It requires authentication and encryption, that is, do not use NULL ciphers:

  CIPHER-SUITE=FIPS:!ADH:!LOW:!EXP:!MD5:!aNULL:!eNULL:@STRENGTH

  Default configuration:

  CIPHER-SUITE=TLSv1:!ADH:!LOW:!EXP:!MD5:@STRENGTH

  See http://www.openssl.org/docs/apps/ciphers.html

• GSK
  Default configuration:

  CIPHER-SUITE=35363738392F303132330A1613100D

  This list of cipher suites starts with a strong '256-bit AES encryption with SHA-1 message authentication and RSA key exchange' (35) and ends with a relatively weak '168-bit Triple DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSA certificate' (0D).

  See IBM documentation: z/OS V2R1.0 System SSL Programming, SC14-7495-00, Appendix C: Cipher Suite Definitions.

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.

If not specified, the connection non-activity test is disabled.

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.

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

(Example: "ETBCERT")

File that contains the broker's private key (if not contained in KEY-STORE).

(Example: MyAppKey.pem)

Note:
EntireX Broker supports only key files of type .pem. Files of type .jks are not supported.

Password used to protect the private key. Unlocks MyAppKey.pem. Deprecated. See KEY-PASSWD-ENCRYTPED below.

Password used to protect the private key. Unlocks 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.

SSL certificate; may contain the private key.

(Example: ExxAppCert.pem)

Note:
EntireX Broker supports only keystores of type .pem. Files of type .jks are not supported.

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.

Maximum number of attempts to restart the SSL communicator.

Wait time between suspending SSL communication due to unrecoverable error and the next attempt to restart it.

Minimum: 1S

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.

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.

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 restarting the broker, use System Management Hub or ETBCMD.

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

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

The VSAM Persistent Store parameters, enclosed in double quotes (""). The value can span more than one line. See Format Parameters for details of the parameters. In previous versions of EntireX, these parameters were read from the SYSIN DD during broker kernel startup.

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.

Database ID of Adabas database where the persistent store resides.

File number of broker persistent store file.

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.

Limits display of persistent UOW information in the persistent store through Command and Information Services.

Default value is 1000.

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

Use this parameter to specify the Adabas SVC number to be used by the Adabas persistent store driver.

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

A trace level should be used only when requested by Software AG support.