Skip to main content
Omnitracs Knowledge Base

Create Message - OMCRTMSG

Create Message (OMCRTMSG)RI

Required Parameter Group:

1 Input Block Input Char(4174)
2 Output Block Output Char(21)

API Overview:
The Create Message API (OMCRTMSG) is used to create and transmit a QTRACS forward message that is addressed to any valid QTRACS entity that is capable of receiving forward messages.

There are several benefits that are realized by utilizing this API to create a forward message (as opposed to passing a transaction to QTRACS):

  1. This API will stamp each message with a 'submitted' date. This is the date that the message was created and it will be used to sequence that message within the user directory. This is very important because each message generated via this API will be written immediately to the QTRACS Message Database. Messages to remote entities (vehicles or T2-equipped trailers) will be viewed as pending messages until they are sent to the NMC by the Communications Manager.
  2. This API will also associate each message with a global message handle (GMH). The global message handle may be used by external applications to reference QTRACS messages. The external application does not provide the handle, rather it is returned to the application through the OMCRTMSG call. Allowing the API to stamp the message with a GMH also ensures that messages will be sent in logical order with relation to their GMH.
  3. The API will provide immediate feedback on the validity of a message request. Each message and its associated parameters will be validated, and if invalid, control will be immediately returned to the calling application. In addition to a return status code, a reason code is also be generated that indicates why the transaction was rejected. The reason code may be used to return a textual description of the problem. These descriptions are kept in an OS400 message file (TRAQMSGF) and may be language dependent.
  4. The API will 'scrub' the message body of any invalid characters. The message body that is passed to OMCRTMSG will be scanned for the presence of any invalid characters. If any are found, they will be replaced with a blank (hex 40). The message will be stored in the QTRACS Message Database and transmitted to the NMC in its valid form. Any invalid characters are 'lost forever'.

Required Parameter Group Details:
(1) Input Block

1-10 Source Entity Identifier Char(10)
11-11 Reserved #1(set to blanks) Char(1)
12-13 Reserved #2(set to zero) Packed(3,0)
14-233 Destination List (20 destinations) Char(220)
234-235 Times to Transmit Packed(3,0)
236-236 Message Priority Char(1)
237-237 Schedule Message Char(1)
238-238 Return Receipt Char(1)
239-239 Word Wrap Char(1)
240-249 Route Reply Char(10)
250-251 Macro Number / Binary Data Type Packed(3,0)
252-253 Macro Version / Binary Data Subtype Packed(3,0)
254-263 External Application ID (for RI only) Char(10)
264-270 Reserved #3(set to blanks) Char(7)
271-271 Message Body Type Char(1)
272-274 Message Body Length Packed(5,0)
275-4174 Message Body Char(3900)

Update (Carrier Function)

This function updates a single Carrier record.

Note: Release 5.2 changes are highlighted in red.

XML Request


  • null fields are the fields that are either omitted or initialized to a special value - string "NULL".
    • E.g., <Street>NULL<Street/> will be interpreted as a null field.
  • Empty string fields are, e.g., <Street /> or <Street></Street>

The Update function takes the following request parameters:

Parameter Type Optional Description
Name String Yes Carrier name, required in both old and new. New carrier name must be at least 4 characters.
Street String Yes Street segment of Carrier address
Street2 String Yes Street segment of Carrier address - line 2
City String Yes City segment of Carrier address
State String Yes State segment of Carrier address
Postal String Yes Postal code segment of Carrier address
MiscInfo String Yes Additional information. This can be used to match the corresponding company's office information field
USDotNumber String Yes Identifying number issued by DOT
  • oldCarrier record is found based on Name specified in oldCarrier and on NMCAccount derived from the user login credentials.
  • Only oldCarrier/Name field is used. Any other oldCarrier fields are ignored.
  • Name is a required filed in both oldCarrier and newCarrier. It may not be either an empty string or null.
  • Name must be unique for a given customer. If this constraint is violated, SOAP fault "System.Web.Services.Protocols.SoapException: Record already exists." will result.
<?xml version="1.0" encoding="utf-8"?>    
<soap:Envelope xmlns:xsi="" xmlns:xsd="" xmlns:soap="">    
<soap:Envelope xmlns:xsi="" xmlns:xsd="" xmlns:soap="">    
    <Update xmlns="">    

XML Response

The return result indicates success or failure via SOAP exceptions.

<?xml version="1.0" encoding="utf-8"?>    
<soap:Envelope xmlns:xsi="" xmlns:xsd="" xmlns:soap="">    
    <UpdateResponse xmlns="" />    

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:

0 normal priority
1 important priority
2 sleepy priority
3 sleepy plus priority
4 low (if text or binary message) / immediate (if T2 msg)
5 attention priority
9 emergency priority

Schedule Message

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

0 disable
1 enable
2 enable (but don't require a batch message period to exist)

Return Receipt

Valid values are:

0 disable
1 enable

Word Wrap

Valid values are:

0 disable
1 enable (wrap text on 38-character boundaries)

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:

Entity Name replies routed to this 'U' or 'L' type entity
*PERSONAL replies routed to sender
*DISPATCH replies routed to coverage

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.

000 T2 Update Status
001 T2 Parameter Query
002 T2 Parameter Update

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:

B binary data
T text data
R T2 text data

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


1-5 Global Message Handle Packed(9,0)
6-12 Message Creation Timestamp Packed(13,0)
13-13 Scheduled Message Char(1)
14-14 Return Status Char(1)
15-18 Reason Code Char(4)
19-21 Number of Message Recipients Packed(5,0)

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:

0 message submitted successfully
1 message submittal was rejected (see 'reason code' parameter for more info)

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.


Local Entity Consists Of Description
USER01 A local user
USER02 A local user
USER03 A local user
USER04 A local user
LIST01 USER01 USER02 USER03 An address list consisting of the four users.
TRAILER An external application
Remote Entity Covered By
TRUCK01 LIST01 A vehicle that is covered by a group of users as indicated in the address list.
TRUCK02 LIST01 A vehicle that is covered by a group of users as indicated in the address list.
TRUCK03 LIST01 A vehicle that is covered by a group of users as indicated in the address list.
TRUCK04 USER04 A vehicle that is covered by a single user.
TRUCK05 USER04 A vehicle that is covered by a single user.
0126777216 A trailer equipped with a terrestrial T2 device.
Sender Receiver Disposition
USER01 USER01 USER02 USER03 USER04 This is a message from USER01 to an explicit list of other users including himself. USER01 will be eliminated from the list of destinations and the message will be sent to USER02, USER03 and USER04. USER01 will already have a copy of this message since USER01 is the sender.
USER02 LIST01 This is a message from USER02 to an address list consisting of 3 users. USER02 is one of the three users. USER02 is removed from the list of addressees because USER02 is the sender. USER02 will already see a copy of this message since USER02 is the sender.
USER04 @USER04 This message will be transmitted to the vehicles that are being covered by USER04. These are TRUCK04 and TRUCK05 in the example.
USER01 @LIST01 TRUCK02 This message will be rejected because the remote vehicle entity TRUCK02 appears twice in the destination list: Implicitly as a member of the LIST01 fleet and explicitly by direct reference. This is an illegal address list. OMCRTMSG cannot resolve it.
TRAILER 0126777216 This a T2 message from the TrailerTRACS external application to a T2-equipped trailer. It is so designated by specifying the CMBTIN field as R. Only TrailerTRACS may send T2 messages. The recipient of a T2 message must be a single T2 device as specified by the 10-digit T2 Device ID. T2 messages may not be sent to users, applications, or vehicles.

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.

  • Was this article helpful?