Administrator's Guide for Rational ClearCase MultiSite, Release 2002.05.00, All Platforms

mkorder

Creates a shipping order for use by the store-and-forward facility

APPLICABILITY

Product	Command type
MultiSite	MultiSite command

Platform
UNIX
Windows

SYNOPSIS

mkorder -dat·a packet-pname [ -scl·ass storage-class-name ]: [ -pex·pire date-time ] [ -not·ify e-mail-address ]
[ -c·omment comment | -cq·uery | -cqe·ach | -nc·omment ]
[ -shi·p -cop·y | -fsh·ip [ -cop·y ] | -out order-pname ] destination ...

This command is located in ccase-home-dir/etc on UNIX and ccase-home-dir\bin on Windows.

DESCRIPTION

This command creates a shipping order file for an existing packet or any other file. The shipping order is used by the shipping_server command to send the packet to one or more destinations.

mkorder submits to the store-and-forward facility a packet that was created with mkreplica -out or syncreplica -out. You can also use mkorder to resubmit store-and-forward packets whose shipping orders have expired, and to transfer other files among sites.

A shipping order must be located in the same directory as its associated packet or file.

NOTE: The store-and-forward facility deletes a packet after delivering it successfully (except when the destination is the local host). If you use this command to process a file that must be preserved at your site even after delivery to another site, you must specify the -copy option.

RESTRICTIONS

None.

OPTIONS AND ARGUMENTS

SPECIFYING THE PACKET FILE. Default: None.

-dat·a packet-pname: The pathname of the packet or file.
: NOTE: If packet-pname contains a colon character ( : ), mkorder changes the colon to a period character ( . ) during processing. This allows packets to be delivered to Windows machines, which do not allow colons within file names.

SPECIFYING WHERE TO PLACE THE SHIPPING ORDER. Default: Creates a shipping order in the directory where the packet-pname file is located.

-scl·ass class-name: Specifies the storage class of the packet and shipping order. If you also use -ship or -fship, mkorder looks up the storage class in the store-and-forward configuration settings (on Windows, in the MultiSite Control Panel; on UNIX, in the file ccase-home-dir/config/services/shipping.conf) to determine the location of the storage bay to use.
: If you omit this option but use -ship or -fship, mkorder places the shipping order in the storage bay location specified for the -default class in the MultiSite Control Panel or the shipping.conf file.

-shi·p -cop·y
-fsh·ip [ -cop·y ]: Creates a shipping order for the packet-pname file. Using -fship (force ship) invokes shipping_server to send the packet. Using -ship places the shipping order in a storage bay. To send the packet, run shipping_server or set up invocations of sync_export_list -poll with the schedule command. (See the schedule reference page in the Command Reference.)
: -copy is required with -ship, and optional with -fship:

-out order-pname: Places the shipping order in the specified file instead of in a storage bay. An error occurs if the file already exists.

HANDLING PACKET-DELIVERY FAILURES. Default: If a packet cannot be delivered, it is sent through the store-and-forward facility back to the administrator at the site of the originating replica. A mail message is sent to the store-and-forward administrator. This occurs after repeated attempts to deliver the packet have failed, and the allotted time has expired; it can also occur when the destination host is unknown or a data file does not exist. The store-and-forward configuration settings specify the expiration period and the e-mail address of the administrator.

-pex·pire date-time: Specifies the time at which the store-and-forward facility stops attempting to deliver the packet and generates a failure mail message instead.
: UNIX: This option overrides the storage class's EXPIRATION specification in the store-and-forward configuration file. See the shipping.conf reference page for a discussion of this specification and of delivery retries in general.
: Windows: This option overrides the storage class's Packet Expiration specification in the MultiSite Control Panel. See the MultiSite Control Panel reference page for a discussion of this specification, and of delivery retries in general.
: The date-time argument can have any of the following formats:
: date.time | date | time | now
where:
: Specify the time in 24-hour format, relative to the local time zone. If you omit the time, the default value is 00:00:00. If you omit the date, the default value is today. If you omit the century, year, or a specific date, the most recent one is used. Specify UTC if you want the time to be resolved to the same moment in time regardless of time zone. Use the plus (+) or minus (-) operator to specify a positive or negative offset to the UTC time. If you specify UTC without hour or minute offsets, the default setting is Greenwich Mean Time (GMT). (Dates before January 1, 1970 Universal Coordinated Time (UTC) are invalid.)
: Examples:

: 22-November-1998 sunday yesterday.16:00 8-jun 13:00 today 9-Aug.10:00UTC

-not·ify e-mail-address: The delivery-failure message is sent to the specified e-mail address.
: If a failure occurs on a Windows host that does not have e-mail notification enabled, a message appears in the Windows Event Viewer. The message includes the e-mail-address value specified with this option and a note requesting that this user be informed of the status of the operation. For information about enabling e-mail notification, see the MultiSite Control Panel reference page.

EVENT RECORDS AND COMMENTS. Default: Creates one or more event records, with commenting controlled by the standard ClearCase user profile (default: -nc). See EVENT RECORDS AND COMMENTS in the multitool reference page.

-c·omment comment | -cq·uery | -cqe·ach | -nc·omment: Overrides the default with one of the MultiSite comment options.

SPECIFYING THE DESTINATION. Default: None.

destination ...: One or more host names (which must be usable by hosts in different domains) or IP addresses. When sending a MultiSite packet, you must specify the host where the replica actually resides or is to be created.

EXAMPLES

Create a shipping order for file p1, which is located in the default storage bay. Store the shipping order in the same storage bay as p1, and specify that the file is to be sent to host goldengate. The lines are broken for readability. You must enter the command on a single physical line.

mkorder -data "c:\Program Files\Rational\ClearCase\var\shipping\ms_ship\p1" -out "c:\Program Files\Rational\ClearCase\var\shipping\ms_ship\p1_order" goldengate Shipping order "c:\Program Files\Rational\ClearCase\var \shipping\ms_ship\p1_order" generated.

Create a shipping order in the default storage bay for a specified file that is to be delivered to host goldengate. Specify that admin must be notified if the file is not delivered successfully.

/usr/atria/etc/mkorder -data /usr/tmp/to_goldengate -ship -copy -notify admin goldengate Shipping order "/var/adm/atria/shipping/ms_ship/sh_o_to_goldengate" generated.

Create a shipping order for the same file, but place it in the storage bay for a particular storage class. Attempt immediate delivery (-fship), and allow delivery attempts to continue until the beginning of May 18.

mkorder -data c:\tmp\to_goldengate -fship -copy -sclass ClassA -pexpire 18-May goldengate Shipping order "c:\tmp\sclass\ClassA\sh_o_to_goldengate" generated. Attempting to forward/deliver generated packets... -- Forwarded/delivered packet c:\tmp\sclass\ClassA\sh_o_to_goldengate

FILES

ccase-home-dir/config/services/shipping.conf

date	:=	`day-of-week` \| `long-date`
`time`	:=	`h`[`h`]:`m`[`m`][:`s`[`s`]] [UTC [ [ + \| - ]`h`[`h`][:`m`[`m`] ] ] ]
`day-of-week`	:=	today \|yesterday \|Sunday \| ... \|Saturday \|Sun \| ... \|Sat
`long-date`	:=	`d`[`d`]-`month`[-[`yy`]`yy`]
`month`	:=	January \|... \|December \|Jan \|... \|Dec