Create Message - OMCRTMSG

Update (Carrier Function)

This function updates a single Carrier record.

Note: Release 5.2 changes are highlighted in red.

    
<?xml version="1.0" encoding="utf-8"?>    
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">    
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">    
  <soap:Body>    
    <Update xmlns="http://www.omnitracs.com">    
      <oldCarrier>    
        <Name>string</Name>    
        <Street>string</Street>    
        <Street2>string</Street2>    
        <City>string</City>    
        <State>string</State>    
        <Postal>string</Postal>    
        <MiscInfo>string</MiscInfo>    
        <USDotNumber>string</USDotNumber>    
      </oldCarrier>    
      <newCarrier>    
        <Name>string</Name>    
        <Street>string</Street>    
        <Street2>string</Street2>    
        <City>string</City>    
        <State>string</State>    
        <Postal>string</Postal>    
        <MiscInfo>string</MiscInfo>    
        <USDotNumber>string</USDotNumber>    
      </newCarrier>    
    </Update>    
  </soap:Body>    
</soap:Envelope>    

    
<?xml version="1.0" encoding="utf-8"?>    
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">    
  <soap:Body>    
    <UpdateResponse xmlns="http://www.omnitracs.com" />    
  </soap:Body>    
</soap:Envelope>    

Source Entity Identifier

Denotes the source (sender) of the message. The source must be a simple entity: user, application or vehicle.

Reserved #1

Should be set to blanks by the calling program.

Reserved #2

Should be set to zero by the calling program.

Destination List

List of up to 20 destination entity identifiers (addressees). Each entry is 11 characters long. The list is terminated by first blank entry. Note that to send to all users, all vehicles, or to the NMC there may be only one destination: *ALLVEH, *ALLUSR, or *NMC. Note that to send to a T2 device, the first character must be blank, and characters 2-11 must contain a left-justified, zero-filled T2 device ID.

Times to Transmit

Should be set to zero by the calling program.

Message Priority

Valid values are:

Schedule Message

Schedule for off-peak (batch) transmission. Valid values are:

Return Receipt

Valid values are:

Word Wrap

Valid values are:

Route Reply

Determines how replies to this message will be routed. If the message is text (not binary), and the source of the message is a user or an application, and the destination includes one or more vehicles, then this parameter must be set to one of the following:

Otherwise, this parameter must be set to *NONE (or blanks). Also, *PERSONAL is only valid if the 'Source Entity Identifier' is a user.

Macro Number / Binary Data Type

If 'Message Body Type' is text this field indicates the macro template number. Zero value indicates free form in this case.
If 'Message Body Type' is binary this field indicates the binary data type.
If 'Message Body Type' is T2 this field indicates the T2 data type.

Macro Version / Binary Data Subtype

If 'Message Body Type' is text this field indicates the macro template version number. Zero value indicates free form in this case.
If 'Message Body Type' is binary this field indicates the binary data subtype.
If 'Message Body Type' is T2 this field is ignored. It should be set to 0 by the caller.

External Application ID

Should the calling application be one that stores the returned GMH from this program, this field should contain the registered QTRACS external application id to which the 692 transaction will be sent. See chapter 2 of this document for an explanation of the 692 transaction.
This is only necessary in a RI (remote integration) environment.

Reserved #3

Should be set to blanks by the calling program.

Message Body Type

Indicates the type of the body of the message. Valid values are:

Message Body Length

Specifies the length of the message body passed to the program. Range is 1 : 3900.

Message Body

Body of the message to be sent in external (full field) format. External format is the same format that is currently used by external applications through the transactional interface. The list of characters that may be included in a QTRACS message body is contained in Appendix A. Any invalid characters will be replaced with a blank (hex 40) prior to storage and/or transmission.

(2) Output Block

OUTPUT; CHAR(21)

Global Message Handle

Global message handle that has been assigned to this message. This handle uniquely identifies the message, and may be used as an argument to various QTRACS API calls.

Message Creation Timestamp

This is the timestamp of the creation of the message. It is the "sent" date. This timestamp is represented in QTRACS internal time code (13 packed decimal digits).

Scheduled Message

Indicates whether the message was sent in *IMMEDIATE or *BATCH mode. Returned values are:

Return Status

Indicates the success or failure of this submit request. Returned values are:

Reason Code

In the case of failures or rejections, this field contains the reason code. OS/400 messages for the reason codes are contained in the TRAQMSGF message file and can be found by concatenating the 4 character reason code to 'CRC'.

Number of Message Recipients

Number of recipients of the message. This is the number of primitive addressees (vehicles and/or users) that were actually sent the message after all expansion of composite addresses was performed.

API Effect

A properly formatted call to this API will create, store and transmit a QTRACS message addressed to the selected recipient(s).

The OMCRTMSG API performs the following functions when it processes a submit message request:

• The message is validated.
• The body of the message is validated. Validation will only be performed for macro fields that have a value specified or for required macro fields. See Appendix C for possible values for all macro field types.
• The body of the message is processed into (1) its storable/displayable form and (2) in the case of messages that are addressed to remote entities, its transmittable form as defined in the "OmniTRACS Customer Interface Packet Specification" . The body is stored in the QTRACS Message Database.
• The destination addresses are parsed and expanded (fanned out). A "from" entry and the appropriate "to" entries are added to the Message Database.
• The host message number (HMN) for each transmitted component of the message is used to indicate the grouping in the "to" entries of the fanned out of remote composite entities. This is done so that the router can process the message submit acknowledgment and forward message confirmation transaction back into the database, setting the GFMN in the proper destination list entries.
• Messages that are addressed to local entities are stored in the "UNSN" state and the notification code is called in order to notify the recipients based on their notification preferences. These messages are available to the addressees immediately after the call to OMCRTMSG completes.
• Messages that are addressed to vehicles or T2 devices (remote entities) are stored in the "PEND" state indicating that the message has been submitted to the communications manager for transmission.
• Transactions are formulated and sent to the communications manager requesting the transmission of messages to remote entities.
• The API returns a reason code indicating the disposition of the message request.
• The API returns the global message handle (GMH) of the newly created message for use with QTRACS APIs.
• It is illegal to send a message to yourself. The OMCRTMSG API will remove the sender entity from the destination list before transmitting the message. An error will be returned and the message will be rejected if the removal of the sender entity causes the list of destinations to become empty.
• Duplicated explicit local destinations are removed from the list of destinations without causing an error.
• Multiple explicit references to the same remote addressee are rejected.
• Any destination list that causes more than one copy of a message to be addressed to a single remote entity is rejected.
• Overlap of user addressees in implicit references is allowed.
• Attempts to send a message to any combination of destinations which collectively exceed the forward message addressees limit will be rejected.

Examples:

Considerations for Use of OMCRTMSG API
Appendix A shows the list of valid characters for QTRACS forward messages.
The OMCRTMSG API differs from the Version 3 transactional interface in that the message request is validated immediately as a part of the OMCRTMSG call. This means that illegal or invalid messages will be rejected at the time of the call in most cases and will not be written into the QTRACS database. The external application program must detect rejected messages by checking the DMREAS reason code for non-zero values. The application should notify the system operator or OmniTRACS administrator when messages are requested. The reason code can be used as a pointer to a message description in the TRAQMSGF message file by appending it to the "CRC" prefix. The TRAQMSGF message may be used to notify the appropriate parties of failed message submittal requests from within external applications.

The message validation in OMCRTMSG includes the complete validation of all of the input fields including the list of destinations.
The message body is 'scrubbed' of any invalid characters. Any that may be found are replaced with a blank (hex 40) prior to storage and/or transmission to the NMC. One or more invalid characters found in a message body are not considered an error. The bad characters are simply replaced and the message is handled normally.