CHGDSTQ (Change Distribution Queue)

CHGDSTQ Command syntax diagram

 

Purpose

The Change Distribution Queue (CHGDSTQ) command changes 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.

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

1. This command is shipped with public *EXCLUDE authority, and the QPGMR and QSYSOPR user profiles have private authorities to use the command.
   
2. 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.
   
3. A unique remote location name must be specified for each RPDS-type distribution queue in the queue table. RPDS queues do not use modes, remote network identifiers, or local location names.
   
4. Configuration in 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.
   
5. SVDS-type distribution queues can support only a single queue view (the queue is not divided into normal and priority halves). For configurations and operations purposes, only the normal queue is specified.
   
6. 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.
   
7. 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.
   
8. Messages that report errors about distribution queues may display or print different characters than the user 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 on the Work with Distribution Queue (WRKDSTQ) command. An error may be reported if the character-string value specified for the 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).

 

Required Parameters

DSTQ

Specifies the name of the distribution queue being changed.

RMTLOCNAME

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

*SAME: The name of the remote location does not change.

remote-location: Specify a maximum of 8 characters for the name of the remote location.

 

Optional Parameters

MODE

Specifies the name of the mode that defines the sessions on the device used by the distribution queue. This parameter is not applicable to RPDS-type distribution queues.

*SAME: The name of the mode does not change.

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

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

RMTNETID

Specifies the remote network identifier of the remote network to which this distribution queue sends distributions. This parameter is not applicable to RPDS-type distribution queues.

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

LCLLOCNAME

Specifies the name used to identify the local system to remote systems in the network. Whenever possible, the name should be the same as the local system name.

*SAME: The local location name does not change.

*LOC: The local location name defined in the device description used by this distribution queue is used.

local-location-name: Specify a maximum of 8 characters for the local location name.

NRMPTY

Specifies the queue sending conditions for distributions having a service level of data low.

Element 1: Send Time

Send time is 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 queue depth and are not related to time. The time must be specified in the 24-hour format hhmm where h = hours and m = minutes.

*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: Specify the time of day at which the system starts sending distributions of this priority from this distribution queue if the value specified for send depth is reached. If from time is specified, to time must also be specified.

to-time: Specify the time of day at which the system stops sending distributions of this priority from this distribution queue. If to time is specified, from time must also be specified.

Element 2: Force Time

Force time is the 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. The time must be specified in the 24-hour format hhmm where h = hours and m = minutes.

*SAME: The force time does not change.

*NONE: No force time is specified.

force-time: Specify the time at which distributions of this priority are sent regardless of queue depth.

Element 3: Depth

Queue depth specifies the number of distributions of this priority that are on the queue before sending can begin.

*SAME: The queue depth value does not change.

*MANUAL: Distributions of this priority are sent only when an operator manually sends them using the Work with Distribution Queue (WRKDSTQ) command or the Send Distribution Queue (SNDDSTQ) command.

depth: Specify the number of distributions of this priority that are on this distribution queue before any are sent. Valid values range from 1 through 999.

HIGHPTY

Specifies the queue sending conditions for distributions having a service level of fast, status, or data high. On this parameter, time must be specified in the 24-hour format hhmm where h = hours and m = minutes.

Element 1: Send Time

*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: Specify the time of day at which the system starts sending distributions of this priority from this distribution queue if the value specified for send depth is reached. If from time is specified, to time must also be specified.

to-time: Specify the time of day at which the system stops sending distributions of this priority from this distribution queue. If to time is specified, from time must also be specified.

Element 2: Force Time

*SAME: The force time does not change.

*NONE: No force time is specified.

force-time: Specify the time at which distributions of this priority are sent regardless of queue depth.

Element 3: Depth

*SAME: The queue depth value does not change.

*MANUAL: Distributions of this priority are sent only when an operator manually sends them using the Work with Distribution Queue (WRKDSTQ) command or the Send Distribution Queue (SNDDSTQ) command.

depth: Specify the number of distributions of this priority that are on this distribution queue before any are sent. Valid values range from 1 through 999.

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.

*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 through 9999.

RTYITV

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

*SAME: The retry interval does not change.

minutes: Specify the interval between retry attempts. Valid values range from 0 to 9999 minutes.

SNDQ

Specifies whether this distribution queue ignores the send time and depth values specified on the NRMPTY and HIGHPTY parameters 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 a SNADS-type distribution queue is being changed.

*SAME: The send queue value does not change.

*NO: Distributions are sent from this queue only when the queue's sending conditions are met.

*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 other sending conditions. Distributions are automatically sent for manual queues (queues that have no specified depth variable).

Example for CHGDSTQ

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.

Error messages for CHGDSTQ

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