Change Distribution Queue (CHGDSTQ)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Change Distribution Queue (CHGDSTQ) command allows you to change an entry in the distribution services queue table. Distribution queues are used to store distributions before they are sent or forwarded to other systems.

The CHGDSTQ command does not provide interactive display support. This is provided by the Configure Distribution Services (CFGDSTSRV) command. More information about configuring a distribution network is in the SNA Distribution Services book, SC41-5410.

If connection information (remote location name, mode, remote network identifier, and local location name) is changed and a SNADS (SNA distribution services) sender job is active (but not sending), the SNADS sender job is ended and a new job is started to ensure that the job name always reflects the remote location name.

Distribution queue names are translated to the graphic character set and code page 930 500, using the job's coded character set identifier (CCSID).

Restrictions:

This command is shipped with public *EXCLUDE authority, and the QPGMR and QSYSOPR user profiles have private authorities to use the command.

The combination of remote location name, mode, remote network identifier, and local location name must be unique within the type of distribution queue. This combination does not need to be unique within the system, for SNA distribution services (SNADS) distribution queues in the distribution services queue table (SNADS-type distribution queues), and for SystemView distribution services (SVDS) distribution queues (SVDS-type distribution queues). The default value *LOC, which can be specified on the RMTNETID parameter and the LCLLOCNAME parameter, and the default value *NETATR, which can be specified on the MODE parameter, represent any possible values that the system determines are not already configured for another SNADS or SVDS distribution queue of the same type.
You must specify a unique remote location name for each RPDS-type distribution queue in the queue table. RPDS queues do not use modes, remote network identifiers, or local location names.
Configuration of the routing table is not required for SVDS-type distribution queues. SVDS queues may be configured optionally in the SNADS routing table. However, normal SNADS mail can neither be routed to change management queues nor be received through change management connections, and change management connections can neither be routed to SNADS queues nor be received through SNADS connections.
SVDS-type distribution queues can support only a single queue view (the queue is not divided into normal and priority halves). For configuration and operations purposes, only the normal queue is specified.

Connection information cannot be changed when the queue has a status of "Sending" or when queue entries have the status of "Suspend" or "Pending." Wait for the status of the queue or queue entry to be no longer active or, as an alternative, use the Initialize Distribution Queue (INZDSTQ) command to reset this condition.
SVDS-type distribution queues cannot be changed when a receiver is active or when distributions have been received and the sender has not acknowledged receiving the confirmation. Wait for the remote system to complete sending, or as an alternative, use the Initialize Distribution Queue (INZDSTQ) command to reset this condition.

Messages that report errors about distribution queues may display or print different characters than you entered for the distribution queue name because of internal system transformations. Similarly (depending on the language used for the work station), the internal value for a distribution queue name may differ from the characters shown for the Work with Distribution Queue (WRKDSTQ) command. An error may be reported if the character-string value specified for the Distribution queue prompt (DSTQ parameter) does not match the rules for an internal distribution queue value or if it does not match the internal value for any defined distribution queue (ignoring case differences).

Top

Parameters

Keyword	Description	Choices	Notes
DSTQ	Distribution queue	Character value	Required, Positional 1
RMTLOCNAME	Remote location	Communications name, *SAME	Optional
MODE	Mode	Communications name, SAME, NETATR	Optional
RMTNETID	Remote network identifier	Communications name, SAME, LOC, *NONE	Optional
LCLLOCNAME	Local location	Communications name, SAME, LOC	Optional
NRMPTY	Normal priority	Element list	Optional
	Element 1: Send time	Single values: SAME, ALWAYS Other values: Element list
	Element 1: From time (HHMM)	0000-2359, ' '
	Element 2: To time (HHMM)	0000-2359, ' '
	Element 2: Force time (HHMM)	0000-2359, SAME, NONE
	Element 3: Send depth	1-999, SAME, MANUAL
HIGHPTY	High priority	Element list	Optional
	Element 1: Send time	Single values: SAME, ALWAYS Other values: Element list
	Element 1: From time (HHMM)	0000-2359, ' '
	Element 2: To time (HHMM)	0000-2359, ' '
	Element 2: Force time (HHMM)	0000-2359, SAME, NONE
	Element 3: Send depth	1-999, SAME, MANUAL
RTYNBR	Number of retries	0-9999, *SAME	Optional
RTYITV	Retry interval	0-9999, *SAME	Optional
SNDQ	Send while receiving	SAME, NO, *YES	Optional

Top

Distribution queue (DSTQ)

Specifies the name of the distribution queue entry being changed.

This is a required parameter.

Top

Remote location (RMTLOCNAME)

Specifies the name of the remote location to which distributions are sent from this distribution queue. The remote location name must be the same as the remote location name specified in the device description of the device used when sending distributions to another system from this distribution queue.

The possible values are:

*SAME: The remote location name does not change.
remote-location: Specify a maximum of 8 characters for the name of the remote location.

Top

Mode (MODE)

Specifies the name of the mode that defines the sessions on the device used by the distribution queue. This parameter is not applicable if you are changing an RPDS-type distribution queue entry.

The possible values are:

*SAME: The mode name does not change.

*NETATR: The mode in the network attributes is used.

mode-name: Specify a maximum of 8 characters for the name of the mode. Do not use CPSVCMG or SNASVCMG; these mode names are reserved for system use.

Top

Remote network identifier (RMTNETID)

Specifies the remote network identifier of the remote network to which this distribution queue sends distributions. This parameter is not applicable if you are changing an RPDS-type distribution queue entry.

The possible values are:

*SAME: The remote network identifier does not change.
*LOC: The remote network identifier defined in the device description used by this distribution queue is used.
*NONE: No remote network identifier is specified.
remote-network-ID: Specify the remote network identifier.

Top

Local location (LCLLOCNAME)

Specifies the name used to identify your system to remote systems in the network. It is recommended that the name be the same as your system name.

The possible values are:

*SAME: The local location name does not change.
*LOC: The local location name is the name defined in the device description used by this distribution queue.
local-location-name: Specify a maximum of 8 characters for the local location name.

Top

Normal priority (NRMPTY)

Specifies the queue sending conditions for distributions having a service level of data low. This parameter's three elements are:

Send time: The time period during which queued distributions of this priority are sent from this distribution queue. If you do not enter a time period, the transmissions are controlled by send depth and are not related to time.
Force time: A specific time during which distributions of this priority are sent regardless of queue depth. If *ALWAYS is specified for the send time, the force time can be set to any time of day. If you specify a specific to-time and from-time for the send time, the force time must occur within that time period.
Send depth: The number of distributions of this priority that must be on the queue before the system automatically begins sending them.

The possible send time values are:

*SAME: The send time does not change.
*ALWAYS: Distributions of this priority are sent from this distribution queue regardless of the time of day.
from-time to-time: Specify the time of day during which distributions of this priority can be sent from this distribution queue. The from-time and to-time must be specified in the 24-hour time format hhmm where h = hours and m = minutes. Both from-time and to-time must be specified.

The possible force time values are:

*SAME: The force time does not change.
*NONE: No force time is specified.
force-time: Specify the force time in the 24-hour format hhmm where h = hours and m = minutes.

The possible send depth values are:

*SAME: The send depth does not change.
*MANUAL: Distributions are sent only when an operator manually sends them using the Work with Distribution Queue (WRKDSTQ) command or the Send Distribution Queue (SNDDSTQ) command.
send depth: Specify the number of distributions of this priority that must be in this distribution queue before any are sent. Valid values range from 1 through 999.

Top

High priority (HIGHPTY)

Specifies the queue sending conditions for distributions having a service level of fast, status, or data high. This parameter's three elements are:

Send time: The time period during which queued distributions of this priority are sent from this distribution queue. If you do not enter a time period, the transmissions are controlled by send depth and are not related to time.
Force time: A specific time during which distributions of this priority are sent regardless of queue depth. If *ALWAYS is specified for the send time, the force time can be set to any time of day. If you specify a specific to-time and from-time for the send time, the force time must occur within that time period.
Send depth: The number of distributions of this priority that must be on the queue before the system automatically begins sending them.

The possible send time values are:

*SAME: The send time does not change.
*ALWAYS: Distributions of this priority are sent from this distribution queue regardless of the time of day.
from-time to-time: Specify the time of day during which distributions of this priority can be sent from this distribution queue. The from-time and to-time must be specified in the 24-hour time format hhmm where h = hours and m = minutes. Both from-time and to-time must be specified.

The possible force time values are:

*SAME: The force time does not change.
*NONE: No force time is specified.
force-time: Specify the force time in the 24-hour format hhmm where h = hours and m = minutes.

The possible send depth values are:

*SAME: The send depth does not change.
*MANUAL: Distributions are sent only when an operator manually sends them using the Work with Distribution Queue (WRKDSTQ) command or the Send Distribution Queue (SNDDSTQ) command.
send depth: Specify the number of distributions of this priority that must be in this distribution queue before any are sent. Valid values range from 1 through 999.

Top

Number of retries (RTYNBR)

Specifies the maximum number of times the system attempts to resend distributions from this distribution queue after a failure occurs. This parameter applies to communications line failures and recoverable distribution failures on a remote system. The SNADS job serving this distribution queue ends when the number of retries is exceeded.

The possible values are:

*SAME: The maximum number of retry attempts does not change.
number: Specify the maximum number of times the system can attempt to resend distributions after a failure. Valid values range from 0 to 9999.

Top

Retry interval (RTYITV)

Specifies the interval (in minutes) between each retry attempt.

The possible values are:

*SAME: The number of minutes between retries does not change.
minutes: Specify the interval (in minutes) between retries. Valid values range from 0 to 9999.

Top

Send while receiving (SNDQ)

Specifies whether this distribution queue ignores the send time and depth values specified on the Normal priority prompt (NRMPTY parameter) and High priority prompt (HIGHPTY parameter) and begins sending when a distribution is received from the SNADS system to which the queue sends its distributions.

This parameter is valid only if you are changing a SNADS-type distribution queue entry.

The possible values are:

*SAME: The send queue value does not change.
*NO: Distributions are sent from this queue only when the queue's sending conditions are met, or when the Send Distribution Queue (SNDDSTQ) or Work with Distribution Queue (WRKDSTQ) command is used to send the distributions.
*YES: This distribution queue begins sending when distributions are received from the SNADS system to which the queue sends its distributions regardless of the queue's sending conditions. Distributions are automatically sent for manual queues (queues that have no specified depth variable).

Top

Examples

CHGDSTQ   DSTQ(CHICAGO)  RMTLOCNAME(NEWLU)  MODE(*NETATR)

This command changes the distribution queue named CHICAGO. The remote location name is changed to NEWLU and the mode is changed to the mode specified in the system network attributes.

Top

Error messages

*ESCAPE Messages

CPF8802: Distribution queue &1 was not found.
CPF8807: Error occurred while using QSNADS journal.
CPF8809: Errors detected on SNADS internal queues.
CPF881A: Connection information for distribution queue &1 cannot be changed at this time
CPF881B: Distributions are being received for distribution queue &1
CPF881D: High priority data not allowed for *SVDS distribution queues
CPF8826: Distribution queue entries exist for distribution queue &1.
CPF8827: Routing table entries exist for distribution queue &1.
CPF8828: Remote document library entries exist for *DLS distribution queue &1.
CPF8833: Distribution queue &1 already exists.
CPF8849: Queue &1 in use by another distribution services function.
CPF9845: Error occurred while opening file &1.
CPF9846: Error while processing file &1 in library &2.
CPF9847: Error occurred while closing file &1 in library &2.
CPF9899: Error occurred during processing of command.

Top