acquire

Purpose

Note: SnF queue sessions are deprecated. Use SnF output channels instead.

Use this command to acquire an SnF queue session. All message traffic for the session travels by way of an SAG. The SAG is specified indirectly by the CO of type DnfEfaSnFQueue that represents the SnF queue (see SnF queue options: SnfQueueOptions). This CO specifies the name of an SAG MP option set, and this option set specifies the SNL ID of the SAG. The SIPN assigns an ID to each SnF session; this session ID is sent with the response to the acquire command.

Note: Before you issue this command:

The MSIF transfer service must be started for the corresponding business OU (see start).
Ensure that there is not already an active channel session for the SnF queue (that is, that an output channel to the SnF queue is not currently open), because this can result in errors if the SIPN issues a queue event for the SnF queue.

Parameters marked as optional overwrite the stored SnF queue configuration.

Required access rights:	CT: DnfEfaCmdAccessControl CO: * attr: acquire CT: DnfEfaSnFQueue CO: <queue name> attr: *
Predefined roles that provide required access rights:	DnfEfaSwiftOperator
Issue for OU:	Business OU
Issue to service:	DNF_O_CMD

Format

Parameters

-q snf_queue

The name of the SnF queue for which a queue session is to be acquired. This name was specified when the queue was configured (see SnF queue options: SnfQueueOptions).

-order

The order in which messages are to be retrieved from the SnF queue:

FIFO: Messages are retrieved from the queue in "first in, first out" order, that is, in the same order in which they were added to the queue. This is the default.
Urgent: Messages with urgent priority are retrieved from the queue in FIFO order. Only after all urgent messages were processed are messages with normal priority retrieved from the queue, also in FIFO order.
FileAct: FileAct messages are retrieved from the queue in FIFO order. Only after all FileAct messages were processed are InterAct messages retrieved from the queue, also in FIFO order.
InterAct: InterAct messages are retrieved from the queue in FIFO order. Only after all InterAct messages were processed are FileAct messages retrieved from the queue, also in FIFO order.

The default is specified by the OrderBy attribute of the SnF queue (see SnF queue options: SnfQueueOptions).

-rm

Whether the SnF queue is to be opened in recovery mode. If true, the session is opened in recovery mode. In recovery mode, messages that already have an output sequence number are sent first, regardless of the selected ordering. The default recovery mode is set for each SnF queue by its RecoveryMode attribute (see SnF queue options: SnfQueueOptions).

-num number

Acquiring an SnF queue requires message partner options (these are described in SAG message partner options: SagMPOptions). These options are specified by an SAG MP option set. Which SAG MP option set is used depends on the following:

If the acquire command does not specify the -num parameter, and if a value is not specified for the SagMPOptionSetNum attribute of the CO of type DnfEfaSnFQueue that corresponds to this SnF queue, the SAG MP option set with the name specified for the SagMPOptionSet attribute is used.
If the acquire command specifies the -num parameter, or if a value is specified for the SagMPOptionSetNum attribute of the CO of type DnfEfaSnFQueue that corresponds to this SnF queue, the SAG MP option set with the name comprising the value of the SagMPOptionSet attribute concatenated with the value specified for the -num parameter or the SagMPOptionSetNum attribute.

The value is a two-digit (01 - 99) suffix that is to be appended to the name specified by the SagMPOptionSet attribute. The default is specified by the value of the SagMPOptionSetNum attribute of the SnF queue. If the SagMPOptionSetNum attribute is not configured for the SnF queue, and if -num is not specified, nothing is appended to the name of the SAG MP option set.

-force

If this parameter is specified, a queue session for the specified queue is acquired even if a queue session for this queue is already open.

Examples

The following command acquires the SnF queue with the name xxxxdeff_generic:

INST1.BANKA.DNF_O_CMD>ac -q xxxxdeff_generic

The response looks similar to this:

DNFO0427I Acquiring of SnF queue initiated.

The SIPN processes the command and sends a response to the MSIF transfer service, which issues an event similar to this:

DNFO1703I 2011-08-30 13:33:03 BANKA DNF_O_FT SnF queue 'xxxxdef_generic' 
          was acquired:
Session ID       : 'xxxxdeff_generic:p:615309'
Next OSN         : '120'
Recovery mode    : 'true'
Order by         : 'FIFO'
SAG MP option set: 'sagmp5'
SNL ID           : 'snl01665'

Which SAG MP option set is used depends on the values of the SagMPOptionSet and SagMPOptionSetNum attributes of the SnF queue with the name xxxxdeff_generic:

No number is to be appended to the value of SagMPOptionSet:

Value of SagMPOptionSet   : sagmp5
Value of SagMPOptionSetNum: (attribute not specified)
SAG MP option set used    : sagmp5

A default number is to be appended to the value of SagMPOptionSet:

Value of SagMPOptionSet   : sagmp5
Value of SagMPOptionSetNum: 03
SAG MP option set used    : sagmp503

The following command acquires the SnF queue with the name xxxxdeff_generic, even if a session for this queue is already open. The output also shows information about the previous session.

INST1.BANKA.DNF_O_CMD>ac -q xxxxdeff_generic -force

The response looks similar to this:

DNFO0427I Acquiring of SnF queue initiated.

The SIPN processes the command and sends a response to the MSIF transfer service, which issues an event similar to this:

DNFO1703I 2011-08-30 13:33:03 BANKA DNF_O_FT SnF queue xxxxdef_generic was acquired:
Session ID       : 'xxxxdeff_generic:p:615309'
Next OSN         : '120'
Recovery mode    : 'true'
Order by         : 'FIFO'
SAG MP option set: 'sagmp5'
SNL ID           : 'snl01665'
DNFO1710I 2011-08-30 13:33:03 BANKA DNF_O_FT Information about previous SnF session,
which ended when SnF queue ’xxxxdeff_generic’ was acquired by force:
 Authoriser DN : 'cn=ia-authoriser,o=xxxxdeff,o=swift'
 SNL ID        : 'snl01665'
 Session mode  : 'Push'
 Order by      : 'FIFO'
 Recovery mode : 'false'

The output sequence number (OSN) shown in this response is the OSN of the next expected message.