Change Vehicle Coverage - OMCHGCVG

Change Vehicle Coverage (OMCHGCVG) ^RI

Required Parameter Group:

1	Vehicle Identifier	Input	Char(10)
2	Coverage Identifier	Input	Char(10)
3	Group Identifier *OBSOLETE*	Input	Char(10)
4	Return Status	Output	Char(1)

Optional Parameter Group:

5

Make Coverage a Vehicle Message Group

Input

Char(1)

API Overview:
Each vehicle in the QTRACS/400 database is said to be 'owned' or 'covered'. The owner, or coverage, of a vehicle may be a single user, or a group of users (address list). Messages that originate from vehicles are routed to their owners. Vehicles can also be members of groups which allows a single broadcast message to be sent to a group of vehicles instead of multiple individually addressed messages. It is possible to change the coverage and group of a vehicle by calling this API.
The Change Vehicle Coverage API (OMCHGCVG) changes the owner of a vehicle from one coverage to another. It is especially useful for sites that are doing regional dispatching in which vehicles must be moved from one region to another based on their load assignment.

Required Parameter Group Details:
(1) Vehicle Identifier
INPUT; CHAR(10)
This parameter contains the identifier of the vehicle whose dispatch coverage and/or group is to be changed.

(2) Coverage Identifier
INPUT; CHAR(10)
This parameter contains the identifier of the new user (or group of users) that will cover the vehicle. Specifying a value in this field is optional even though all vehicles must have a coverage. An input value of *LOVAL implies that no change is desired for this field, its current value will remain unchanged.

*(3) Group Identifier OBSOLETE*
INPUT; CHAR(10)
This parameter contains the identifier of the message group in which the vehicle belongs. Specifying a value in this field is optional because a vehicle is not required to be a member of a message group. An input value of *LOVAL implies that no change is desired for this field, its current value will remain unchanged.

(4) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:

0	Success, coverage changed
1	Failure, user is not authorized to modify a vehicle's coverage
2	Failure, unknown vehicle identifier specified
3	Failure, coverage identifier is not a user or address list
4	Failure, unknown group identifier specified
5	Failure, no change in coverage identifier or group identifier was specified
6	Failure, auxiliary vehicle identifier and group identifier cannot be specified together
7	Failure, OmniOne vehicle identifier and group identifier cannot be specified together
8	Failure, coverage identifier is an address list whose membership exceeds the maximum limit
9	Failure, message group is over the maximum vehicle limit of 32,767
A	Failure, API failed when called remotely

Optional Parameter Group Details:
(5) Make Coverage a Vehicle Message Group
INPUT; CHAR(1)
This parameter indicates whether or not a new coverage ID will be declared to be a forward vehicle message group as well. A new coverage is created when the first vehicle is assigned to a user or address list that currently does not cover any vehicles. Only in this instance, will the API look at this flag to determine whether or not it should also establish that coverage ID to be an vehicle message group as well.
Valid values are:

Y	If a new coverage ID is created, declare it to be a vehicle message group as well (default).
N	If a new coverage ID is created, do not declare it to be a vehicle message group.

If this parameter is not specified by the calling program, the API will execute its default logic; it will operate as if the parameter was passed and 'Y' was specified.

Effect
Upon completion of a successful call to this API, the vehicle specified will become owned by the user or address list specified in the coverage identifier parameter. All unsolicited messages from the vehicle will be routed to this coverage. If the coverage identifier is a user, then all unsolicited messages from the vehicle will be routed to the user. If the coverage identifier is an address list, then all unsolicited messages from the vehicle will be routed to each user in that address list.

If the previous owner of the vehicle was declared to be a 'vehicle message group', then the vehicle will be removed from that message group. If the new owner of the vehicle is declared to be a 'vehicle message group', then the vehicle will become a member of that message group.